File security

The File security screen lets you follow the mandatory pipeline every file goes through before Docling and the RAG (upload, quarantine, ClamAV, YARA-X, validation), the live state of each engine instance, the counts of the last 24 hours, the analyses and the blocked files, the rules of the tenant, and lets you test a file without ingesting it. Portal path: /security/file-security, menu Security and governance > File security. It is used by security officers and tenant administrators who run the scanning, and by auditors who read it.

What the screen shows

The screen (FileSecurity in portal/src/screens/file-security.tsx, requests in portal/src/lib/file-security.ts) has, from top to bottom:

• Warning banner "File security is not fully protected", shown when needed with one line per warning: development mode, platform not ready (uploads refused, fail closed), ClamAV or YARA-X not configured, down or degraded, ClamAV signatures older than the allowed age.
• Mandatory pipeline ("No file reaches Docling or the RAG before both engines and the validation released it."): the steps Upload > Quarantine > ClamAV > YARA-X > Validation > Docling > RAG / AI. Each engine step shows {healthy}/{total} up, degraded, Down or Not configured; the platform steps show Active. Below: the Mode badge (enforce or development), Ready or Not ready, and "Checked" with the date. Read from GET /v1/file-security/status, refreshed every 30 seconds.
• Last 24 hours cards, read from GET /v1/file-security/stats (refreshed every 60 seconds): Files analysed, Released, Blocked, Malware, Suspicious, Last blocked (or Never), then the counts By source.
• Four tabs:

Tab	Content
Engines	Two sections, ClamAV gateways and YARA-X workers, each with a badge {healthy}/{total} healthy and one card per instance: address, Up or Down, Version, Latency, and for ClamAV Signature version, Published, Age (with a warning when the signatures are stale), for YARA-X Rules (version and count), Rules sha256, Loaded. An error of the instance is shown in red. Without instance: "No instance declared".
Analyses	Table read from GET /v1/file-security/scans (50 rows, cursor), filters Status (Quarantined, Released, Blocked), Verdict (Clean, Malware, Suspicious, Unscannable, Scan error, Policy violation) and Source (Knowledge, Media, Multimodal, Transcription, Connector, Channel, API). Columns File, Verdict, Status, Source, Detected type, Size, Sample kept, sha256, Date.
Blocked files	The same table with the status fixed to blocked (filters Verdict and Source). "Files blocked by the engines or the rules stay in quarantine here."
Rules	Locked rules (read only, "Platform rules that no tenant can change."): Scan before any ingestion, Required engines, Refuse when an engine is unavailable (fail closed), Block malware, Block unscannable files, each with its value. Rules of the tenant: the editable fields below, read from GET /v1/file-security/policy, with "Updated {at} by {by}" or "Platform defaults, never changed."

Editable rules of the tenant:

Field	Bounds	Meaning
Maximum size (bytes)	1024 to the platform ceiling (file_scan_max_bytes, 50 MiB by default)	Larger files are refused.
Quarantine retention (days)	1 to 365	How long a kept sample stays before its purge.
Maximum signature age (hours)	1 to 720	Age above which the ClamAV signatures are stale.
When signatures are stale	Warn and keep scanning or Block the uploads	Behaviour with stale signatures.
Allow archives	switch	ZIP and other archives are opened and scanned within the nesting limit.
Block Office macros	switch	A document with macros is blocked instead of reported.
Block a declared type that differs from the detected type	switch	Detected from the magic bytes of the file.
Keep encrypted samples of blocked files	switch	Lets a blocked file be rescanned; purged after the retention.
Allowed types	at least one known type	Types detected from the content; any other type is refused.

A click on a row, or Details, opens the analysis (GET /v1/file-security/scans/{scan_id}): verdict and status badges, Source, Declared type, Detected type, Size, sha256, Sent by, Received, Analysed, Sample kept, Sample purged on, Rescan of (link to the original record), Reasons, the ClamAV section (result, Signature, Instance, Version, Signature version, Duration) and the YARA-X section (result, Rules version, Rules sha256, Instance, Duration, and the matches Rule, Severity, Action, Verdict, or "No YARA-X match.").

Actions

Button or action	What it does	API call	Roles
Test a file (page header), then Analyse	Opens a dialog: choose a File, click Analyse. The file is scanned like an upload (quarantine, ClamAV, YARA-X, rules) but never ingested; the dialog shows the verdict, the status, the reasons and the sha256, with Open the analysis.	POST /v1/file-security/scans	Every user of the tenant
Refresh (Mandatory pipeline)	Reads the state of the engines again.	GET /v1/file-security/status	tenant_admin, security_officer, auditor
Status, Verdict, Source filters	Filter the list as soon as a value is chosen.	GET /v1/file-security/scans (query status, verdict, source)	Every user of the tenant (only its own scans without a reader role)
Details (row menu) or row click	Opens the analysis.	GET /v1/file-security/scans/{scan_id}	Every user who can see the scan
Rescan (row menu or detail), then Confirm	Scans the kept sample again with the current engines and rules; a new record is created and opened, the original upload is never released. Message "Rescan done: {verdict}."	POST /v1/file-security/scans/{scan_id}/rescan	Enabled for platform_admin, tenant_admin, security_officer when a sample is kept; server: security_officer, tenant_admin
Purge the sample (row menu or detail), then Confirm	Deletes the encrypted sample for good; the record and its verdict stay. Message "Sample purged." Audited.	DELETE /v1/file-security/scans/{scan_id}/sample	Same as Rescan
Save the rules (Rules)	Sends only the changed fields. Message "Rules saved." Audited as file_security.policy.update.	PUT /v1/file-security/policy	security_officer, tenant_admin (fields disabled for others)
Undo the changes (Rules)	Puts the form back to the loaded rules, without any call.	None	Readers of the rules
Cancel (dialogs)	Closes the dialog without any call.	None	Everyone
Retry (error state)	Reads the failed section again.	The route of the section	Same as the section

danger

Purge the sample cannot be undone: the file can no longer be rescanned. Purge only when the analysis is closed.

Roles

The portal disables Rescan and Purge the sample outside SCAN_OPERATORS (platform_admin, tenant_admin, security_officer) and the rule fields outside POLICY_WRITERS (security_officer, tenant_admin), both in portal/src/lib/file-security.ts; a reader sees "Read only: a security officer or a tenant administrator changes the rules." The Control Plane (services/control-plane/src/eai/domains/file_security/__init__.py, roles in services/control-plane/src/eai/domains/file_security/service.py) decides:

• status and rules: tenant_admin, security_officer, auditor (READERS);
• change the rules, rescan, purge: security_officer, tenant_admin (WRITERS);
• test a file, list and stats: any user of the tenant; without a reader role, only the scans this user sent;
• platform_admin passes every role check.

Typical tasks

Check that the scanning protects the platform

1. Read the banner and the pipeline. A missing or down engine means uploads are refused (fail closed) or, in development mode, skipped. Open the screen. Expected result: no warning banner, every engine step up, Mode enforce and Ready. If it fails: "Development mode" must never be seen in production; "Not configured" means the engine is not installed (install it with the Navin Manager).
2. Open the engines. Tab Engines. Expected result: every instance Up, a recent Published date of the signatures and the expected rules sha256. If it fails: the stale signature warning means the internal mirror of the signatures is not updated.
3. Test with a harmless file. Click Test a file, choose a file, Analyse. Expected result: the verdict Clean and the status Released. If it fails: file_scan_unavailable (HTTP 503) means the engines did not answer; nothing was ingested.

Investigate a blocked file

1. Find it. Tab Blocked files, filter Verdict if needed. Expected result: the blocked files with their verdict and source. If it fails: "No blocked file" means nothing was blocked.
2. Read the analysis. Click the row. Expected result: the Reasons, the ClamAV Signature or the YARA-X matches. If it fails: not_found means the scan is not visible to you (it was sent by someone else and you have no reader role).
3. Rescan after a rules update. A false positive may disappear with new signatures or rules. Rescan, then Confirm. Expected result: "Rescan done: {verdict}." and the new record opens, with Rescan of pointing to the original. If it fails: the button is disabled without a kept sample ("No sample kept for this file: rescan and purge are not available."); file_sample_unavailable (HTTP 409) from the API.
4. Purge the sample. Once closed, the encrypted sample has no use. Purge the sample, then Confirm. Expected result: "Sample purged." and Sample kept No. If it fails: forbidden means you are not security_officer nor tenant_admin.

Tighten the rules of the tenant

1. Change the values. Tab Rules, section Rules of the tenant: lower Maximum size (bytes), turn on Block Office macros, untick the Allowed types you do not accept. Expected result: the fields change and Save the rules is enabled. If it fails: fields disabled and "Read only" mean a missing role; a red message lists the problems (for example "Pick at least one allowed type.").
2. Save. Click Save the rules. Expected result: "Rules saved." and "Updated {at} by {by}" with your name. If it fails: file_security_rule_locked (HTTP 422) for a locked rule; invalid_request (HTTP 422) with field and reason for a value out of bounds.

Troubleshooting

Symptom	Cause	Fix
Banner "The platform is not ready to scan"	No engine answers: uploads are refused (fail closed).	Check the ClamAV gateways and YARA-X workers in Engines.
file_scan_unavailable (HTTP 503)	The scan engines are unavailable; the file was not ingested.	Restore the engines, then try again.
file_blocked (HTTP 422) on an upload elsewhere	The file was blocked by the scan (verdict in the message); it was not ingested.	Read the analysis in Blocked files.
file_sample_unavailable (HTTP 409)	No sample is kept for this scan.	Turn on Keep encrypted samples of blocked files for the next files.
file_security_rule_locked (HTTP 422)	These file security rules are locked and cannot be changed.	Change only the rules of the tenant.
invalid_request (HTTP 422) with unknown_types	An allowed type is not a known type.	Choose types from the list.
invalid_request (HTTP 400) with content_base64	The content sent is not valid base64 (invalid base64), or it is missing.	Choose the file again; through the API, send a valid content_base64 or a multipart file.
forbidden (HTTP 403) on the status or the rules	Reading needs tenant_admin, security_officer or auditor.	Ask for one of these roles.
invalid_cursor (HTTP 400)	The pagination cursor is invalid.	Change a filter or reload the page.

Related pages

• File security guide
• Security posture
• RAG quarantine
• Knowledge bases
• Media
• Data protection