File security and malware scanning
The Lynkoria scanner service, the attachment quarantine lifecycle, and how other products integrate.
apps/scanner is an independent service: it has no database, no storage credentials and no Lynkoria application code. It receives file bytes, returns a verdict and keeps nothing. The Lynkoria API is one consumer; Fidescript and other products can be others through the same HTTP contract.
Verdicts
POST /v1/scan with Authorization: Bearer <consumer token> and the raw bytes as the body. Optional headers: x-lynkoria-declared-type (the uploader's claimed MIME type) and x-lynkoria-allowed-types (image/*,application/pdf).
| Status | Meaning |
|---|---|
clean | No detection, type matches the claim and policy |
infected | ClamAV signature detected (signature names it) |
rejected | empty, too_large, executable, type_mismatch, type_not_allowed or limits_exceeded (archive bomb or engine limit) |
failed | HTTP 429/503 or transport error: no verdict. Keep the file quarantined and retry later |
Every verdict includes the sniffed detectedType, sha256, size, engine and signature versions with signature age, scannedAt and scanId. Types are sniffed from magic bytes; the declared MIME type is never trusted. Executables (PE, ELF, Mach-O, shebang scripts, JAR, APK) are always rejected.
Fail closed
- Signatures older than
SCANNER_MAX_SIGNATURE_AGE_HOURS(48) make every scan fail with 503;/health/readyreports it. - Engine timeouts, unknown engine replies and an unreachable engine fail the scan.
- ClamAV bounds its work with
MaxScanSize,MaxFileSize,MaxRecursionandMaxFiles, but trims oversized archive members and reports OK instead of alerting. The scanner therefore rejects archives itself when declared uncompressed size, compression ratio or entry count exceedSCANNER_ARCHIVE_MAX_*(defaults 200 MiB, ratio 100, 5000 entries). Only the outer archive layer is inspected; nested bombs are bounded by the engine limits. - Files are buffered in memory up to
SCANNER_MAX_BYTES(50 MiB) with at mostSCANNER_MAX_CONCURRENCY(4) concurrent scans. Nothing is written to disk, so there are no temporary files or paths to traverse.
Attachments in Lynkoria
POST /v1/attachments/upload-intentreserves an attachment (pending) and returns a presigned PUT.POST /v1/attachments/{id}/completechecks size and declared type, reads the object back, and sends it to the scanner with the project's allowed types.clean→readywithscanStatus: clean, digest and sniffed type recorded.infected/rejected→ the object is deleted and the attachmentrejected. No verdict → 503; the attachment stayspending/failedand the client callscompleteagain later.- Only
ready+cleanattachments can be attached to messages or downloaded. Downloads are 5-minute presigned URLs after membership checks.
The audit trail stores digest, sniffed type, verdict and signature name, never file contents. Metrics: lynkoria_attachment_scans_total{result}; the console's Operations tab shows recent rejected and failed scans.
Deployment
infra/scanner/compose.yaml runs three containers on a private host: the scanner (only port, bound to a private IP), clamd on an internal network with no egress and a read-only signature volume, and a freshclam updater (12 checks a day) that is the only container with internet access. clamd reloads updated signatures within ten minutes (SelfCheck). Run clamd in UTC: signature dates are parsed as UTC.
ClamAV needs about 1.5–3 GiB of memory with current signatures; allocate 4 GiB to clamd. Signature downloads from the ClamAV CDN are rate limited; do not run the updater more often than needed.
Configuration (apps/scanner): SCANNER_TOKENS_JSON ({"lynkoria-api":"…","fidescript":"…"}, one random token of at least 32 characters per consumer for audit, or a list during rotation), CLAMD_HOST, CLAMD_PORT, SCANNER_MAX_BYTES, SCANNER_TIMEOUT_MS, SCANNER_MAX_CONCURRENCY, SCANNER_MAX_SIGNATURE_AGE_HOURS, SCANNER_ARCHIVE_MAX_UNCOMPRESSED, SCANNER_ARCHIVE_MAX_ENTRIES, SCANNER_ARCHIVE_MAX_RATIO, and SCANNER_TLS_CERT_FILE/SCANNER_TLS_KEY_FILE to serve HTTPS.
Service-to-service traffic stays on the private network and uses TLS 1.3 with a certificate from a private CA that consumers pin (ADR 023); production refuses a plain-HTTP scanner URL unless the scanner is on the same host. The scanner logs consumer, digest, size, sniffed type and verdict only.
Integrating Fidescript (or any product)
Fidescript keeps its own quarantine ledger and calls the scanner over HTTP; it never imports Lynkoria code. With Node.js, @lynkoria/scanner-client provides the typed contract:
import { createScannerClient, ScannerError } from '@lynkoria/scanner-client';
const scanner = createScannerClient({
url: process.env.SCANNER_URL!,
token: process.env.SCANNER_TOKEN!,
ca: process.env.SCANNER_CA_CERT, // the private CA's PEM; the only CA trusted for the scanner
});
try {
const verdict = await scanner.scan(bytes, {
declaredType: 'application/pdf',
allowedTypes: ['application/pdf'],
});
if (verdict.status === 'clean') releaseDocument(id, verdict.sha256);
else rejectDocument(id, verdict.status, verdict.reason ?? verdict.signature);
} catch (err) {
if (err instanceof ScannerError) keepQuarantined(id); // failed: retry later, never release
else throw err;
}Any other language: curl --cacert scanner-ca.crt -H "Authorization: Bearer $TOKEN" -H 'x-lynkoria-declared-type: application/pdf' --data-binary @file.pdf "$SCANNER_URL/v1/scan". GET /v1/engine returns engine and signature freshness for monitoring. Adding another engine later changes only the scanner's internals; the contract stays the same.
Verification
Protocol-level tests (fake clamd) cover clean, infected, archive bomb, spoofed MIME, disallowed types, executables, empty and oversized files, timeouts, garbled replies, stale signatures, an unreachable engine and token authentication. Against real ClamAV 1.4.6 (local container): EICAR, EICAR inside a ZIP, a clean PNG with fresh signatures and a 60 MiB zero-filled ZIP were all classified correctly. API integration tests confirm quarantine, deletion of infected objects, spoofed-type rejection and fail-closed behavior with the scanner down. Scanner throughput is unmeasured.