Skip to main content

OARepo Antivirus

oarepo-antivirus adds ClamAV scanning to file processing in an OARepo application. It provides a file processor, notification delivery for detected files, and CLI commands for scanning RDM-based Records.

Requirements

  • Python 3.14
  • OARepo 14
  • A ClamAV daemon reachable through a network socket
  • An OARepo application with Celery configured for task execution

The ClamAV daemon must accept network socket connections and support the INSTREAM command. The package uses the clamd Python client.

Installation

Install the package in the environment used by the OARepo application:

uv pip install oarepo-antivirus

The package registers AntivirusFileProcessor through the oarepo.file_processors entry point.

Configuration

The default ClamAV address is defined by ANTIVIRUS_DAEMON_ADDRESS in oarepo_antivirus/config.py:

ANTIVIRUS_DAEMON_ADDRESS = {"ip": "127.0.0.1", "port": 3310}

The setting can be overridden in the OARepo application's conf.py or Flask configuration. The processor reads the active Flask configuration when it processes a file. ClamAV signatures are reloaded before each scan.

The package registers the antivirus-scan.failure notification builder when the OARepoAntivirus extension is initialized. Its email content is rendered by the bundled template:

oarepo_antivirus/templates/invenio_notifications/antivirus-scan.failure.jinja

Behaviour on RecordFile

AntivirusFileProcessor accepts every FileRecord. For each record it:

  1. Opens the file as a binary stream.

  2. Sends the stream to ClamAV using INSTREAM.

  3. Leaves metadata unchanged when ClamAV returns OK.

  4. Stores a non-OK result in antivirus_detected:

    {
      "antivirus_detected": "Eicar-Test-Signature"
    }
    
  5. Queues an antivirus-scan.failure email notification for the record owner. The notification contains the record ID, file name, and scanner details and is rendered using the configured notification template.

The processor does not reject, quarantine, or delete files. The host application can enforce those policies using the antivirus_detected metadata (e.g. FileRecord.metadata.get("antivirus_detected", None))

Error handling

Exceptions raised while reading the Flask configuration, opening the file, reloading signatures, or communicating with ClamAV are caught and logged by the processor. Existing metadata is preserved and the exception is not propagated to the file-processing caller.

Notification errors are also isolated from file processing. If the owner cannot be resolved or has no email address, no notification is sent and a warning is logged. Failures while building or queueing the notification are logged and do not undo the antivirus_detected metadata update.

CLI interface

The commands enqueue Celery tasks; they do not wait for scans to finish. A Celery worker must be running.

Scan all files attached to one RDM record:

invenio antivirus scan record <record-pid>

Scan all records returned by the application's current RDM records service:

invenio antivirus scan all

Records whose file service is disabled are skipped. Errors while reading a record or scanning its files are logged by the Celery task and do not escape the task invocation. The CLI itself only reports that the task was queued.

Testing

Start the ClamAV test service from the repository root:

./test-setup.sh start

Run the test suite:

./run.sh test

The script uses tests/docker/docker-compose.yaml and accepts start and stop commands. Stop the service after testing:

./test-setup.sh stop

Metadata

Release files for oarepo-antivirus 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oarepo-antivirus 1.0.1
File Size Uploaded Provenance Actions
oarepo_antivirus-1.0.1.tar.gz 10.5 kB Without provenance Details for oarepo_antivirus-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oarepo-antivirus 1.0.1
File Interpreter ABI Platform Actions
oarepo_antivirus-1.0.1-py3-none-any.whl Python 3 none any Details for oarepo_antivirus-1.0.1-py3-none-any.whl

Total release size: 24.9 kB

Release files / oarepo_antivirus-1.0.1.tar.gz

Download URL oarepo_antivirus-1.0.1.tar.gz
Size 10.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1ce0ba6b6df06440401b2735c0072834257ebf6cf3b9da902b66cd9d27eb49f2
BLAKE2b-256 checksum
How to use checksums
f6ea824b1109f02bd6799a78aed0e2cd19b8db3ac248a53d68cb5f58891d3c1a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / oarepo_antivirus-1.0.1-py3-none-any.whl

Download URL oarepo_antivirus-1.0.1-py3-none-any.whl
Size 14.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a76b248ee74c2b3340bc30324c5ee76c9e9dab0f5d86576c5abfe841ddb64bc2
BLAKE2b-256 checksum
How to use checksums
87c0719d16a3496206158f9a81aaa0195d64fc202ad94326f956b2a4f1027c9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for oarepo-antivirus 1.0.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A 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.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page