Download the PHP package attachmentav/virus-scan-sdk without Composer

attachmentav-sdk-php

An SDK to integrate virus and malware scan capabilities into PHP applications. Scan files for viruses, trojans, and other kinds of malware with attachmentAV powered by Sophos.

• Supports the attachmentAV API (SaaS) and (Self-hosted on AWS).
• PHP 8.0 or newer.
• Works with any PSR-18 HTTP client: Guzzle, Symfony HttpClient, and others are detected automatically.
• Integrates with Laravel: auto-discovered service provider, facade, config file, and a VirusFree validation rule.
• Works with Symfony, Slim, Laminas/Mezzio, CodeIgniter, Yii, CakePHP, and plain PHP.
• Verifies the signatures of callbacks sent by attachmentAV.

Getting started

First, install the package attachmentav/virus-scan-sdk from Packagist with Composer.

The SDK needs a PSR-18 HTTP client. Laravel already includes Guzzle. Symfony applications can use symfony/http-client together with nyholm/psr7. If your project has no HTTP client yet, the php-http/discovery Composer plugin installs one for you, or you can install one yourself: composer require guzzlehttp/guzzle.

Second, get an API key by subscribing to the attachmentAV API (SaaS).

Third, send a scan request. Replace <API_KEY_PLACEHOLDER> with your API key.

The scan result looks like this:

What is attachmentAV?

attachmentAV offers antivirus for SaaS and cloud platforms. Scan your files and attachments stored in the cloud for viruses, worms, and trojans. attachmentAV detects malware in real-time. Supports Amazon S3, Atlassian, Cloudflare R2, Salesforce, WordPress, and more.

The attachmentAV Virus and Malware Scan API provides a REST API that allows you to integrate malware scans into your application. The solution comes in two variants:

• attachmentAV Virus Scan API (SaaS): Get started quickly with a fully managed service.
• attachmentAV Virus Scan API (self-hosted on AWS): Deploy the production-ready API on AWS.

attachmentAV raises the bar for information security. Our solution is ISO 27001 certified and GDPR compliant. We are establishing, implementing, maintaining, and continually improving an information security management system (ISMS). Sensitive data is encrypted in transit as well as at rest and deleted immediately after processing. More than 1,000 customers trust our malware protection technology.

Configure SDK

Configure SDK (SaaS)

An active subscription and API key are required. The region must match the region selected for the subscription. The default is Region::EU.

The SDK sends the API key in the x-api-key header.

Configure SDK (self-hosted on AWS)

When you followed the setup guide, you set the ApiKeys parameter of the CloudFormation stack. Replace <API_KEY_PLACEHOLDER> with one of those keys. Replace attachmentav.yourcompany.com with the domain name of your attachmentAV API installation.

The SDK sends the API key as a bearer token (Authorization: Bearer ...). If you pass only the domain (https://attachmentav.yourcompany.com), the SDK appends /api/v1.

The self-hosted variant supports the sync actions: scanSyncBinary(), scanSyncFile(), scanSyncDownload(), and scanSyncS3(). Async scans, callbacks, getUsage(), whoami(), and test() are only available for the SaaS variant.

Advanced configuration

If Guzzle or Symfony HttpClient is installed, the SDK creates the HTTP client with the configured timeout. If the API asks to wait longer than 30 seconds before retrying (Retry-After), the SDK throws a RateLimitException instead of blocking the request.

You can also pass your own PSR-18 client, e.g. to use a proxy. In that case, configure the timeout on your client:

You can also create the configuration from an array, for example from environment variables or framework configuration:

Empty values, such as environment variables that are set but blank, are treated as missing. So ATTACHMENTAV_REGION= falls back to eu.

Examples

Sync Scan: File

Upload a file to the attachmentAV Virus Scan API and get the scan result back.

SaaS: the maximum file size is 10 MB and the request timeout is 60 seconds.

The SDK always scans the whole content, from the start. A stream resource you pass stays open and is rewound afterwards, so you can keep using it, for example to store the file after a clean scan.

Find the full example: examples/sync-binary.php

Sync Scan: Download

Send a URL to the attachmentAV Virus Scan API. attachmentAV downloads the file and returns the scan result right away.

SaaS: the maximum file size is 200 MB and the request timeout is 60 seconds.

Find the full example: examples/sync-download.php

Sync Scan: S3

Send an S3 bucket name and object key to the attachmentAV Virus Scan API. attachmentAV downloads the object and returns the scan result right away.

SaaS: a bucket policy is required to grant attachmentAV access to the S3 objects. The maximum file size is 200 MB and the request timeout is 60 seconds.

Find the full example: examples/sync-s3.php

Async Scan: Download (SaaS)

Send a URL to the attachmentAV Virus Scan API. attachmentAV downloads and scans the file in the background. The maximum file size is 5 GB.

There are two ways to get the scan result: callback or polling.

Callback: attachmentAV sends the scan result to your callback URL with an HTTPS POST request. See Verify Callbacks.

Polling: pass a trace ID and poll getAsyncResult(). It returns null until the scan result is available. Scan results are stored for 24 hours. Each poll counts against your monthly quota.

Find the full example: examples/async-download-polling.php

Async Scan: S3 (SaaS)

Send an S3 bucket name and object key to the attachmentAV Virus Scan API. attachmentAV downloads and scans the object in the background. A bucket policy is required. The maximum file size is 5 GB.

Find the full example: examples/async-s3-callback.php

Callback failures (SaaS)

If attachmentAV cannot deliver a scan result to your callback URL after several retries, it records a callback failure. Callback failures are kept for 30 days.

Usage and account (SaaS)

Each of these requests counts against your monthly quota.

Find the full example: examples/usage.php

Verify Callbacks

attachmentAV signs every callback. Verify the signature before you trust the scan result. You need your tenant ID, which you can get once with $api->whoami()->getTenantId(). The SDK includes the public keys of all regions.

Use $verifier->verify(...) to get a bool instead of an exception. Use $verifier->verifyRequest($psr7Request, $callbackUrl) with PSR-7 requests (Slim, Mezzio, ...).

Find the full example: examples/verify-callback.php

Error handling

Every exception thrown by the SDK implements AttachmentAV\Exception\ExceptionInterface.

Laravel

Try it: examples/laravel is a complete upload form you can run with docker compose up.

Laravel registers the service provider and the AttachmentAV facade automatically. Add the configuration to your .env file:

Optionally, publish the config file to config/attachmentav.php:

Validate uploads with the VirusFree rule (Laravel 10+). It fails if the file is infected, cannot be scanned, or if the API cannot be reached:

Options:

• new VirusFree(allowUnscannable: true) accepts files that attachmentAV cannot scan (status no), such as encrypted archives.
• new VirusFree(failOnError: false) accepts files unscanned during transient errors (network errors, throttling, 5xx). Errors that would let every file through unscanned, such as an invalid configuration, an invalid API key, or an exceeded quota, still fail validation.

Use the facade, or inject AttachmentAV\AttachmentAVApi:

Verify callbacks in a route. Exclude the route from CSRF protection:

Symfony

Try it: examples/symfony is a complete upload form you can run with docker compose up.

Register the client as a service in config/services.yaml. If symfony/http-client and nyholm/psr7 are installed, Symfony's HTTP client is used.

Then inject AttachmentAV\AttachmentAVApi with autowiring:

Other frameworks and plain PHP

AttachmentAVApi is a plain PHP class with no framework dependencies. Create it once and register it in your framework's container, for example a CodeIgniter service, a Yii component, a Laminas factory, or a PHP-DI definition. To use a specific HTTP client, pass any PSR-18 client and PSR-17 factories:

Development

See DEV.md.

License

MIT