Skip to main content

maf-sandbox-antivirus

PyPI Python License

Experimental. Import emits MafSandboxAntivirusExperimentalWarning. Not yet published. The first package release requires a completed, eligible antivirus image release.

Scan one authorized binary upload in a disposable POSIX sandbox. ClamAV starts from the image's baked seed and applies host-supplied, authenticated updates before the upload is staged. Guest egress remains closed throughout; there is no runtime download or shared scan process.

from pathlib import Path
from maf_sandbox_antivirus import directory_update_provider, make_antivirus_tools

[scan_file] = make_antivirus_tools(
    router,
    quarantine_store,
    "upload-scanner",
    context,
    image=verified_antivirus_image,
    update_provider=directory_update_provider(Path("database-snapshot")),
)
answer = await scan_file.func(file="uploaded-file")

The store's async read(name) returns bytes | None; context.list_files(store) supplies authorized ListedFile entries. Names match exactly and never become host paths, guest paths or URLs. Hosts must bound ingress before the store allocates bytes. The kind independently refuses inputs over max_bytes before acquiring a guest.

The host keeps uploads quarantined until admission succeeds and promotes the exact scanned bytes. A filename is not a content identity: never rescan one value and later publish a mutable store name. The result includes a host-computed input SHA-256. Malware scanning does not promote the upload's source integrity and does not replace document parser guards.

Database updates

The optional update_provider is an async callable receiving three DatabaseIdentity objects identifying the exact image seed. It returns an immutable DatabaseUpdate containing that seed, target versions, and UpdateFile bytes. Each database uses either a consecutive chain of official signed .cdiff files or a full signed .cvd replacement. Unsigned scripts, CLD replacements, version rollback, gaps and mixed replacement/patch plans are refused. ClamAV verifies CVDs and signed CDIFFs inside the guest; hashes bind transfers but do not replace upstream signature authentication. No provider means use the seed only if its daily database meets the age ceiling.

directory_update_provider reads an immutable host-owned mirror snapshot with main.cvd, daily.cvd, bytecode.cvd and optional CDIFFs. It chooses patches when the entire chain exists, otherwise a full replacement. The host owns acquisition, refresh cadence, concurrency and atomic snapshot publication; the kind performs no network access. ClamAV's cvdupdate mirror guidance explains how to retain patches. A plain FreshClam directory normally retains updated databases rather than a distributable CDIFF history. Keep snapshots alive until their calls finish.

Updates are limited to 95 MiB and 90 patches per call. Payloads cross the backend in chunks of at most 16 MiB and are reassembled and hashed in the guest. These defaults fit ACAS's 32 MiB per-file and 128 MiB total ceilings together with the default upload size. An oversized replacement fails closed; use a newer seed image. Every call pays the local patch application and engine-loading cost even when the host reuses cached updates.

Results and limits

scan_file.func(file=...) returns core's labelled content sequence, the same result as an attached tool. The first item is core's completion sentence; a completed result has exactly one fixed verdict item (Result: clean, Result: infected, or Result: refused). Only those wrapper-owned items establish admission. Signature names, guest diagnostics and exception details are excluded from tool results. Hosts can enable DEBUG logging for maf_sandbox_antivirus._tool to retain escaped, bounded diagnostic text; those logs remain untrusted and must not be added to model prompts. Validated database metadata is in trusted_output. The upload-derived input SHA-256 is in labelled output, hidden by a FIDES host while remaining available to the host for byte binding. Hosts without FIDES must keep that field out of model prompts themselves.

clean means no detection under the configured policy, not proof that a file is harmless or that every possible file format was fully interpreted. Encrypted-content, broken-executable and scan-limit alerts are refusals. Invalid arguments, unavailable updates, invalid signatures, timeouts and engine failures return completed=False without a verdict. A stale or engine-incompatible database is refused. All acquired guests are disposed on success, refusal, failure and cancellation.

Host option Default Ceiling
exec_timeout_seconds 60 300 seconds
update_timeout_seconds 120 600 seconds, including provider and staging
max_bytes 32 MiB 128 MiB; backend admission may impose less
max_database_age_days 7 30 days, measured against host UTC using the daily database
max_filesize 32 MiB 128 MiB
max_scansize 128 MiB 512 MiB
max_files 1,000 10,000
max_recursion 16 100

All limits must be positive; non-finite values and booleans are rejected. The age ceiling uses authenticated database metadata; ClamAV's fixed seven-day advisory does not override an explicitly larger ceiling. file_store_provenance and requires_file_integrity have core's usual meaning. Use backend CPU, memory, process and disk limits as well; ClamAV's official databases need substantial memory. Start Docker qualification with 4 GiB and measure your deployment.

ZIP members undergo bounded expansion before ClamAV because native archive limits can skip some members without an alert. Stored and deflated members are decoded independently of their declared expanded size and must have complete compressed streams. Local headers, central-directory entries and data descriptors must agree on compression, flags, sizes and checksums. This guard applies the file count, member size, total expansion and recursion ceilings, and refuses encrypted entries, ZIP64/newer ZIP features or other ZIP compression methods. Other formats use ClamAV's support and alerts; absence of an alert does not establish complete format coverage.

See the kind contract and image guide.

Metadata

Release files for maf-sandbox-antivirus 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maf-sandbox-antivirus 0.2.0
File Size Uploaded Provenance Actions
maf_sandbox_antivirus-0.2.0.tar.gz 15.9 kB With provenance Details for maf_sandbox_antivirus-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maf-sandbox-antivirus 0.2.0
File Interpreter ABI Platform Actions
maf_sandbox_antivirus-0.2.0-py3-none-any.whl Python 3 none any Details for maf_sandbox_antivirus-0.2.0-py3-none-any.whl

Total release size: 33.7 kB

Release files / maf_sandbox_antivirus-0.2.0.tar.gz

Download URL maf_sandbox_antivirus-0.2.0.tar.gz
Size 15.9 kB
Tags Source
SHA-256 checksum
How to use checksums
3ef7f10576a4a1f364c28c9e9e157381835eda4b5517df552a5280defd6dc9c1
BLAKE2b-256 checksum
How to use checksums
e5b8e167a48e99848e5bf9cf186c155a03a492dfe952be162ea596356fb74eb2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / maf_sandbox_antivirus-0.2.0-py3-none-any.whl

Download URL maf_sandbox_antivirus-0.2.0-py3-none-any.whl
Size 17.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e81a65dd00ef1bdd4ff583f4b4d138db177600fd3b5de9558c5773ebebe60d93
BLAKE2b-256 checksum
How to use checksums
386da78d54957af45e1eda32ac44c554c90a07f44fc36a86b446d12937585494
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for maf-sandbox-antivirus 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for maf_sandbox_antivirus-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page