The Pearl

The Pearl is a web application which provides a convenience API calling ClamAV to check a uploaded file for viruses and then also doing a VeraPDF validation of the file sent.

On naming

The Pearl is a novel by John Steinbeck and clams have pearls.

Installation

N.B. The Pearl needs to use VeraPDF >= 1.21.288.

Deploy The Pearl as a service

1. Download the pearlservice.exe executable from the Github Release page.
2. On the same server that will run the service, install ClamAV MSI package
3. On the same server that will run the service, install VeraPDF
4. Ensure that the folder which contains the verapdf.bat script is on the system's PATH envronment variable
5. Install The Pearl as a service by running pearlservice.exe install in a terminal with Administrator privileges
6. Start the service either through the Windows Services or by calling pearlservice.exe start.

Run The Pearl as a standalone Python program

1. On the same server that will run the service, install ClamAV MSI package, or run it locally through Docker: docker run -p 3310:3310 --rm clamav/clamav
2. On the same server that will run the service, install VeraPDF
3. Ensure that the folder which contains the verapdf.bat script is on the system's PATH environment variable
4. Install The Pearl into your virtual environment: pip install https://github.com/hbldh/ThePearl
5. Run it by calling serve-the-pearl.

Usage

Run The Pearl with uvicorn:

python pearlapi.py

or by the entry point created if you use pip for installation:

serve-the-pearl

Swagger

See the Swagger API specs by opening the page /docs.

Examples

Test detection of viruses by e.g.

> echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' `
| curl -F 'file=@-' -u hbldh:secret123 http://127.0.0.1:8132 `
| ConvertFrom-Json | ConvertTo-Json -Depth 50
{
  "VirusFound": true,
  "IsValidPDF": false,
  "Error": null,
  "Details": {
    "ClamAV": {
      "stream": [
        "FOUND",
        "Eicar-Signature"
      ]
    },
    "VeraPDF": "Not tested"
  }
}

Test non detections with any other file, e.g.

curl -F 'file=@./verapdf/documents/veraPDFPDFAConformanceCheckerGUI.pdf' `
     -u hbldh:secret123 `
     http://127.0.0.1:8132 `
| ConvertFrom-Json | ConvertTo-Json -Depth 50
{
  "VirusFound": false,
  "IsValidPDF": false,
  "Error": null,
  "Details": {
    "ClamAV": {
      "stream": [
        "OK",
        null
      ]
    },
    "VeraPDF": {
      "report": {
        "buildInformation":...
        "jobs": ...
        "batchSummary": {
          "duration": {
            "start": 1662724877443,
            "finish": 1662724878828,
            "difference": 1385,
            "duration": "00:00:01.385"
          },
          "totalJobs": 1,
          "outOfMemory": 0,
          "veraExceptions": 0,
          "failedEncryptedJobs": 0,
          "validationSummary": {
            "nonCompliantPdfaCount": 1,
            "failedJobCount": 0,
            "totalJobCount": 1,
            "compliantPdfaCount": 0,
            "successfulJobCount": 1
          },
          "failedParsingJobs": 0,
          "featuresSummary": {
            "failedJobCount": 0,
            "totalJobCount": 0,
            "successfulJobCount": 0
          },
          "repairSummary": {
            "failedJobCount": 0,
            "totalJobCount": 0,
            "successfulJobCount": 0
          },
          "multiJob": false
        }
      }
    }
  }
}

The PDF in question is not PDF/A compliant, so the result is nonCompliantPdfaCount key is equal to 1.