Filament Antivirus Laravel Package

Product Decisions This Supports

Unblocking an upload-dependent feature. If your roadmap has anything that accepts files from untrusted users — customer document intake, seller media, HR/legal submissions, support attachments — this package converts "we need a scanning story before we ship" from a multi-sprint backlog item into an integration task. That is the single highest-leverage decision it informs: it lets you ship the feature this quarter instead of deferring it.

Build vs. buy for the operator experience. The scanning engine is ClamAV — free, mature, and something you would shell out to anyway. What you are actually deciding about is the admin surface: a Filament dashboard showing infected files, quarantine state, and scan results, backed by an antivirus_incidents table that doubles as an audit trail. Building that UI and that schema in-house is the expensive part. The package is an argument for not building it.

A concrete answer to security questionnaires. "How do you handle malicious uploads?" is a standard line item in SOC 2 / ISO 27001 readiness and enterprise procurement. A named, auditable scanning step with a persisted incident record and quarantine trail turns a blank field into a documented control — cheaply. v1.0.0 shipping the incidents table and a dashboard makes this evidence producible rather than merely assertable.

Roadmap sequencing for the admin panel. Adoption cost is concentrated almost entirely in teams already standardized on Filament. For those teams it is a low-ceremony addition (one validation rule, one dashboard page); for everyone else it is not a candidate regardless of its merits, which makes it a scoping input rather than a general platform bet.

Retrofitting an existing corpus. The antivirus:scan command turns "we already have three years of unscanned uploads" from a bespoke migration project into a scheduled backfill with an operator-facing disposition queue. That materially changes the cost of remediating a legacy file store, and it's a decision you can make now rather than defer.

Use cases it plausibly serves well: multi-tenant SaaS accepting customer documents, internal tools with HR/legal file intake, marketplaces with seller-uploaded media, any Laravel app already running Filament as its back office.

Use cases where the value collapses: high-volume media pipelines (ClamAV is not a throughput tool), object-storage-first architectures where files never touch the app server, and anything requiring DLP, content disarm and reconstruction, or sandbox detonation rather than signature matching.

The caveat for the decision log: a 1.0.0 tag from a single maintainer with no dependents means "the author has declared the API stable," not "this has been exercised in production by strangers." It is a reference implementation you could adopt, not an ecosystem-standard dependency. The strategic call isn't "use this package" — it's "we need a scanning interface with a quarantine model, and this is one credible starting point to wrap behind our own abstraction so we can swap it later."

When to Consider This Package

Adopt (or at least prototype) when all of these hold:

• You are on Laravel + Filament, versions compatible with the package's constraints. Verify this first — Filament moves fast and majors break upload internals; it is the most likely reason adoption fails.
• You need signature-based malware scanning of uploaded files and nothing more sophisticated. ClamAV catches commodity malware, not targeted attacks.
• You have, or can get, operational ownership of a ClamAV daemon or binary — sidecar container, clamd service, or managed endpoint. This is the real cost, and it is not a composer install. The package's null driver removes this need in dev and CI, which is genuinely useful, but it also means the default path in a misconfigured environment is no scanning at all — see the fail-open/fail-closed note below.
• Your upload volume is modest — interactive user uploads, not gigabytes per minute. Plan an async/queued path rather than a synchronous request-time scan; confirm which mode AntivirusFileRule uses before you assume.
• You need a quarantine workflow and an operator UI and would otherwise build one.
• You are comfortable vendoring or forking an MIT-licensed, thinly-adopted package and owning it thereafter.

Look elsewhere — or write the thin layer yourself — when:

• You're not on Filament. The dashboard is most of the differentiated value; without it you're wrapping clamdscan in roughly a hundred lines of your own code, which you should just do.
• You need guaranteed maintenance, SLAs, or a security-review trail. One maintainer, zero dependents, no community CVE-watching, and a 1.0.0 that has not yet been pressure-tested by an installed base. On a security-critical path that is material risk. Consider commercial APIs (VirusTotal, Cloudmersive, OPSWAT, AWS GuardDuty Malware Protection for S3) for regulated, customer-facing uploads.
• Files live in S3/GCS and never hit the app server. Cloud-native malware protection fits better; retrofitting a local daemon is a step backwards.
• You need detection beyond signatures — phishing content, macro behavior, zero-days, policy violations. ClamAV will not find those.
• You need sub-second synchronous results at scale.

Diligence checklist before committing: confirm the Laravel/Filament version matrix; read the source end-to-end (it should take an hour — that's a feature); check whether AntivirusFileRule scanning is queued or blocking on the request; confirm where quarantine lives and whether it is encrypted at rest; inspect the antivirus_incidents schema for what it does and does not record; decide explicitly whether scanner failure is fail-open or fail-closed — that is a product decision, not just a technical one; verify the null driver cannot be selected in production by config or accident; wire antivirus:status into your health checks; check release cadence and issue responsiveness now that a 1.0 baseline exists.

How to Pitch It (Stakeholders)

To executives — one paragraph. We have a gap in how we handle user-uploaded files: right now we accept anything. This package gives us malware scanning, a quarantine workflow, and an audit trail inside our existing admin panel at effectively zero license cost (MIT), using ClamAV, the standard open-source antivirus engine. It converts a security exposure — and a likely procurement question — into a solved problem in days rather than a multi-sprint build, and it gives us a supported path to scan the files we've already accumulated. The honest trade-off is maturity: it is a small, single-maintainer project that just reached its first stable release, so the recommendation is to adopt the pattern behind our own interface rather than depend on it directly. That keeps the upside and removes the lock-in.

To engineering — the ask. Spike this for two days. Wire it behind an internal FileScanner interface so the package is an implementation detail, not a dependency baked into upload controllers. Confirm Filament compatibility, confirm scans run on a queue rather than in the request, and make fail-open/fail-closed an explicit config with a documented default. Lock the null driver out of production config. Stand up antivirus:status as a health-check probe from day one. If the spike lands, we own a forked, understood, ~500-line surface area; if it doesn't, we've spent two days and we write the equivalent ourselves. Suggested rollout: a one-week sandbox spike validating that the EICAR test file is caught on upload (not merely on save), a two-to-three-week shadow mode that logs detections without blocking to establish a false-positive baseline, enforcement on public and anonymous upload surfaces first, then an async backfill of the existing corpus using antivirus:scan with a monitored quarantine queue, then hardening (alerting, quarantine quotas, retention policy, release/restore runbook).

Framing to use and avoid. Pitch it as "a reference implementation that buys us the admin UI and the incident record" — not as "a security vendor dependency." The 1.0.0 tag is a useful maturity signal for the conversation but should not be presented as evidence of production hardening. Avoid implying it provides comprehensive protection; it is commodity signature scanning plus good operational ergonomics. Overclaiming here is how you end up in an uncomfortable conversation after an incident.

Success metrics for the initiative: percentage of uploads scanned, median scan latency, quarantine volume and disposition time, false-positive rate and release turnaround, percentage of the legacy corpus backfilled, and zero unscanned files reaching persistent storage.