Keep a file unavailable until its scan finishes

Declare policy and provision its scanner

Use the file’s scanPolicy for an explicit requirement or exception. An unspecified field inherits the application’s configured scanner posture. The backend reads this decision in file-scanning.backend.service.ts; the separate global predicate is included, with intervening commentary omitted.

shouldScan(fileMetadata?: FileSchemaMetadata): boolean {
  const scanPolicy = fileMetadata?.scanPolicy;

  if (scanPolicy === 'required') return true;
  if (scanPolicy === 'skip') return false;

  return this.isGlobalScanningEnabled();
}

isGlobalScanningEnabled(): boolean {
  if (!this.appConfigService.isInitialized()) return false;
  return this.clamavScanner.isConfigured() || this.yaraScanner.isEnabled();
}

Move into scanning before dispatching work

The upload handler awaits scan initiation before returning upload acceptance and file metadata. Upload acceptance does not mean the scan has finished: file.readiness reports whether the returned file can be attached. Inside the scan service, the status transition occurs before asynchronous scanner execution. This excerpt omits validation above and the error-logging callback below.

await this.filesService.updateFileStatus(
  fileId,
  FileStatus.SCANNING,
  executionContext,
);

if (onClean) {
  this.onCleanCallbacks.set(fileId, onClean);
}

this.logDebug('File transitioned to SCANNING, dispatching scan', { fileId });

Distinguish a clean result from a failed check

Configured ClamAV signature scanning runs first; enabled YARA pattern scanning follows if the earlier layer has not refused the file. The pipeline requires at least one configured scanner when scanning is requested. Startup validation reports incompatible required-field and scanner configurations, and the runtime also refuses to certify a file clean when no scanner is available.

A clean verdict transitions the file to CLEAN and releases configured follow-on work. An infection moves it through INFECTED toward QUARANTINED; quarantine keeps the stored bytes but blocks normal download. A scanner or storage error moves it to FAILED, requiring recovery or re-scan. The same state checks stop linking while scanning. Standard file controls refresh pending metadata and publish the new reference only after it becomes ready; the form also preserves the processing error through submit validation. Scanning reduces malware risk; it does not validate the business meaning or confidentiality of a document.

Read readiness before attaching a file

Upload responses include file.readiness; the authorized metadata endpoint returns the same FileMetadata contract. The standard single- and multiple-file controls handle this for local files and provider selections. Custom upload interfaces must inspect readiness rather than treat HTTP success as permission to attach.

Readiness describes attachment eligibility, not download authorization. The backend still checks access and lifecycle state when linking or serving a file. Polling observes a scan; it does not start a new scan or automatically retry a failed one. With scanning skipped or inactive, an ordinary completed upload can already report ready.

Match field policy to the startup contract

Use status for current download eligibility and the emitted failure/malware events for investigation. The absence of a clean-event row must not be interpreted as proof that no scan ran.

Connect a required field to the deployed scanner

This illustrative attachment field requires scanning, independently of the inherited application posture:

import { z_file } from '@wildo-ai/zod-decorators';

const attachment = z_file({
  multiple: false,
  allowedMimeTypes: ['application/pdf'],
  scanPolicy: 'required',
});

Provision a ClamAV daemon reachable from the backend, then supply its address through the application’s environment setup. For example, these values assume the backend can resolve a service named clamav; setting them does not install or start the daemon:

CLAMAV_HOST=clamav
CLAMAV_PORT=3310

The configuration loader seeds fileScanning.antivirus; the scanner reads that resolved configuration. Startup validation checks required fields against ClamAV configuration. A configured address is not proof that the scanner is healthy: the upload path still needs the daemon to accept and complete a scan.

For the additional YARA layer, provision the YARA scanning service and its rules, then configure both the enable flag and its reachable address:

YARA_ENABLED=true
YARA_HOST=yara
YARA_PORT=8080

Those names are illustrative deployment addresses. The YARA service consumes fileScanning.yara.enabled and fileScanning.yara.connection; enabling it without a host is a configuration problem. YARA alone does not satisfy the current startup requirement for a field marked required.

Retain the uploaded file ID while observing processing. Repeated metadata reads observe the existing scan; uploading again creates another upload rather than repairing the first scan.