maf-sandbox-antivirus
Experimental. Import emits
MafSandboxAntivirusExperimentalWarning. Not yet published. The first package release requires a completed, eligibleantivirusimage 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.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| maf_sandbox_antivirus-0.1.1.tar.gz | 15.8 kB | With provenance | Details for maf_sandbox_antivirus-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| maf_sandbox_antivirus-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for maf_sandbox_antivirus-0.1.1-py3-none-any.whl |
Total release size: 33.5 kB
Release files / maf_sandbox_antivirus-0.1.1.tar.gz
| Download URL | maf_sandbox_antivirus-0.1.1.tar.gz |
|---|---|
| Size | 15.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0facca90bb821e99814a2349af0a29f131e70eab4acee050e753967fa1b5051b
|
|
BLAKE2b-256 checksum How to use checksums |
8afbf03eae40d1f0ab2c347d28ded85012920dfc6937a2e7a0d5b375fb41facf
|
| 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 5, 2026.
Transparency logRelease files / maf_sandbox_antivirus-0.1.1-py3-none-any.whl
| Download URL | maf_sandbox_antivirus-0.1.1-py3-none-any.whl |
|---|---|
| Size | 17.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3470a1fc2a06a6d2752f71ff0bcced7aac03745af044e94105e385b8e51db29c
|
|
BLAKE2b-256 checksum How to use checksums |
c2e0688a9b244d27342e30d02da4288029c84a0dbee99a629a29ef0d089adca2
|
| 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 5, 2026.
Transparency logSecurity for maf-sandbox-antivirus 0.1.1
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.
Attestation for maf_sandbox_antivirus-0.1.1.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 5, 2026.
Transparency logA 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.