{"id":14384358,"url":"https://github.com/benzino77/clamav-rest-api","last_synced_at":"2025-04-05T02:04:46.884Z","repository":{"id":37691428,"uuid":"272689666","full_name":"benzino77/clamav-rest-api","owner":"benzino77","description":"ClamAV REST API. Scan files using simple POST request.","archived":false,"fork":false,"pushed_at":"2024-12-08T14:23:03.000Z","size":11505,"stargazers_count":147,"open_issues_count":4,"forks_count":47,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T01:03:37.340Z","etag":null,"topics":["api-server","clamav","nodejs","rest-api","virus-scanning"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benzino77.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"benzino77","github":["benzino77"]}},"created_at":"2020-06-16T11:27:58.000Z","updated_at":"2025-03-11T06:42:04.000Z","dependencies_parsed_at":"2024-01-14T20:16:00.895Z","dependency_job_id":"a7b7b35b-5256-428c-89dc-8783d258bbce","html_url":"https://github.com/benzino77/clamav-rest-api","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benzino77%2Fclamav-rest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benzino77%2Fclamav-rest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benzino77%2Fclamav-rest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benzino77%2Fclamav-rest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benzino77","download_url":"https://codeload.github.com/benzino77/clamav-rest-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276163,"owners_count":20912288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-server","clamav","nodejs","rest-api","virus-scanning"],"created_at":"2024-08-28T18:01:19.863Z","updated_at":"2025-04-05T02:04:46.866Z","avatar_url":"https://github.com/benzino77.png","language":"JavaScript","funding_links":["https://ko-fi.com/benzino77","https://github.com/sponsors/benzino77"],"categories":["JavaScript"],"sub_categories":[],"readme":"## Overview\n\nThis is a simple implementation of REST API for ClamAV virus scanner. You can use it to scan files uploaded by users, before they are saved or put into final destination, or to scan files on demand. Because _clamav-rest-api_ is running in your environment, you do not need to pass your files to third party entities.\n\n\u003cvideo src=\"https://github.com/user-attachments/assets/54be5afc-776a-4b02-93ac-e010005e1b79\"\u003eScreencast\n\u003c/video\u003e\n\nThe screen recording above is showing how to use _clamav-rest-api_ synchronously and asynchronously \u003csup\u003e[1](#notes)\u003c/sup\u003e. There are three types of async callbacks available:\n\n### WEBHOOK Call\n\nCall external HTTP endpoint on scan complete.\n\n![Webhook](./docs/images/Postman-webhook.jpg)\n\n### REDIS pub/sub\n\nPublish scan result to a given _REDIS_ channel on scan complete\n\n![REDIS pub/sub](./docs/images/Postman-redis.jpg)\n\n### AWS SNS\n\nPublish scan result to a given _SNS Topic_ which (like on the screencast and the screen below) can be passed to _AWS Lambda_ function.\n\n![AWS SNS](./docs/images/Postman-sns.jpg)\n\n\u003e [!NOTE]\n\u003e In all three cases the message body passed to a callback is a `JSON` object containing scan result and `request_id`.\n\n## How to start clamav-rest-api?\n\nFirst of all you have to have running ClamAV instance configured to accept TCP connections from `clamav-rest-api` instances. For more details I will guide you to CalmAV documentation ([here](https://blog.clamav.net/2016/06/regarding-use-of-clamav-daemons-tcp.html) and [here](https://www.clamav.net/documents/configuration#clamdconf)) but it's enough to say that you need `TCPSocket 3310` and eventually `TCPAddr` in your `clamd.conf` file. The easiest way is to use docker image with ClamAV already configured. I'm using `clamav/clamav` docker [image](https://hub.docker.com/r/clamav/clamav) during tests and development.\n\n**_Note_:**\nYou have to give `clamav/clamav` a minute to start because it needs to refresh signatures from ClamAV servers (update its viruses database).\n\n**_Recommended_** way of using `clamav-rest-api` is to start it as docker container or on k8s cluster (see [Configuration](#Configuration) below):\n\nIn [examples](./examples/k8s) directory there are kubernetes YAML files to create `configMap`, `deployments` and `services`. Just run `kubectl` command to create them in proper order:\n\n```bash\nkubectl apply -f cra-configmap.yml\nkubectl apply -f clamavd.yml\nkubectl apply -f cra.yml\n```\n\n`clamav-rest-api` service is published on `nodePort` 30080. On cluster network it is available on port 3000.\n\nTo start using clamav-rest-api on docker environment follow the steps below:\n\n```\ndocker run -d -p 8080:8080 \\\n-e NODE_ENV=production \\\n-e APP_PORT=8080 \\\n-e APP_FORM_KEY=FILES \\\n-e CLAMD_IP=192.168.10.10 \\\n-e APP_MAX_FILE_SIZE=26214400 \\\nbenzino77/clamav-rest-api\n```\n\nor\n\n```\ndocker run -d -p 8080:8080 -v /local/path/to/.env:/clamav-rest-api/.env benzino77/clamav-rest-api\n```\n\nor, if you are running docker in Swarm mode, you can use `configs`\n\n```\ndocker config create cra /path/to/.env\ndocker service create --name clamav-rest-api --publish published=8080,target=8080 --config src=cra,target=\"/clamav-rest-api/.env\" benzino77/clamav-rest-api\n```\n\nThere is also an [example](./examples/docker-compose.yml) how to run _full_ stack on docker Swarm (clamavd and clamav-rest-api combined):\n\n```\ndocker stack deploy -c docker-compose.yml cra\n```\n\nYou can also start `clamav-rest-api` by cloning the repo and run commands listed below:\n\n```\nnpm install\nnpm install -D # if you want to run tests or examples\n# Configuration described below - needed before start app\nnpm start\n```\n\n## Configuration\n\n`clamav-rest-api` needs some information to run properly. For example it needs to know where to find ClamAV. This kind of information can be provided by `.env` file or by setting environment variables. Example `.env` file can be find [here](./.env.example). What you need to do is to copy `.env.example` file to `.env` and edit it to provide configuration parameters which meet your needs.\nHere is a short description of those parameters:\n\n- `NODE_ENV` - describe application environment (production, development, test, etc.)\n- `APP_PORT` - port number on which `clamav-rest-api` will listen to requests\n- `APP_FORM_KEY` - form key (element name) used when uploading files to scan (see [examples directory](examples/)). `clamav-rest-api` will only accept files uploaded with this form key.\n- `APP_MORGAN_LOG_FORMAT` - log format used by `clamav-rest-api` to display information about requests. More infor can be found [here](https://github.com/expressjs/morgan#predefined-formats)\n- `APP_MAX_FILE_SIZE` - max size (in bytes) of **single** file which will be accepted by `clamav-rest-api`. You have to also take care of `MaxScanSize`, `MaxFileSize`, etc. in your `clamd.conf` file.\n- `APP_MAX_FILES_NUMBER` - maximum number of files uploaded to scan\n- `CLAMD_IP` - ClamAV IP address\n- `CLAMD_PORT` - ClamAV listen port\n- `CLAMD_TIMEOUT`- ClamAV timeout connection in milliseconds\n- `STATS_COLLECT` - `true` or `false` indicating whether stats about scanning should be collected \u003csup\u003e[1](#notes)\u003c/sup\u003e\n  - `STATS_REDIS` - address of the _REDIS_ server for collecting statistics: `redis[s]://[host][:port]`.\n  - `STATS_REDIS_INSECURE` - `true` or `false` indicates whether to check remote server SSL certificate\n  - `STATS_REDIS_AUTH` - _REDIS_ server credentials passed as `JSON`: `{\"username\":\"user_name\",\"password\":\"user_password\"}`\n\nAs stated before you can set all those parameters by setting environment variables:\n\n_Linux/MacOSX_\n\n```\nexport APP_PORT=8080\nexport NODE_ENV=production\nexport CLAMD_IP=localhost\nexport APP_FORM_KEY=FILES\nnpm start\n```\n\nor\n\n```\nAPP_PORT=8080 NODE_ENV=production CLAMD_IP=clamavd CLAMD_IP=localhost APP_FORM_KEY=FILES npm start\n```\n\n## API endpoints\n\nThere are couple API endpoints:\n\n`POST /api/v1/scan` - to scan files (see [examples](#Examples))\n\n`POST /api/v1/asyncscan` - to scan files asynchronously \u003csup\u003e[1](#notes)\u003c/sup\u003e\n\n`GET /api/v1/version` - to get ClamAV version\n\n`GET /api/v1/dbsignatures` - to get local (currently used by CRA) and remote (obtained from clamav.net) virus database signatures. It can be useful to check whether the local database is up-to-date.\n\n`GET /api/v1/stats` - endpoint which provides information about the number of scanned files, number of infected files and a list of founded viruses. Stats are stored in _REDIS_ \u003csup\u003e[1](#notes)\u003c/sup\u003e.\n\n## Notes\n\n\u003e [!IMPORTANT]\n\u003e The asynchronous scanning and statistics reports are not included neither in this repository nor `benzino77/clamav-rest-api` docker image\n\nIf you are interested in the asynchronous scanning or statistics reports drop me a message at antczak.piotr[@_@]gmail.com with your proposition.\n\n## Examples\n\n### wget example\n\nOooops: _Wget does not currently support \"multipart/form-data\" for transmitting POST data_\n\n### curl example\n\n```\n❯ curl -s -XPOST http://localhost:3000/api/v1/scan -F FILES=@src/tests/1Mfile01.rnd -F FILES=@src/tests/eicar_com.zip | jq\n{\n  \"success\": true,\n  \"data\": {\n    \"result\": [\n      {\n        \"name\": \"1Mfile01.rnd\",\n        \"is_infected\": false,\n        \"viruses\": []\n      },\n      {\n        \"name\": \"eicar_com.zip\",\n        \"is_infected\": true,\n        \"viruses\": [\n          \"Win.Test.EICAR_HDB-1\"\n        ]\n      }\n    ]\n  }\n}\n```\n\n### httpie example\n\n```\n❯ http --form POST http://localhost:3000/api/v1/scan FILES@src/tests/1Mfile01.rnd FILES@src/tests/eicar_com.zip\nHTTP/1.1 200 OK\nAccess-Control-Allow-Origin: *\nConnection: keep-alive\nContent-Length: 172\nContent-Type: application/json; charset=utf-8\nDate: Sun, 07 Jun 2020 10:11:34 GMT\nETag: W/\"ac-dmIyPllIezz2lPUbemX0zYljm9w\"\nX-Powered-By: Express\n\n{\n    \"data\": {\n        \"result\": [\n            {\n                \"is_infected\": false,\n                \"name\": \"1Mfile01.rnd\",\n                \"viruses\": []\n            },\n            {\n                \"is_infected\": true,\n                \"name\": \"eicar_com.zip\",\n                \"viruses\": [\n                    \"Win.Test.EICAR_HDB-1\"\n                ]\n            }\n        ]\n    },\n    \"success\": true\n}\n```\n\n### Postman example\n\n![Postman scan](./docs/images/Postman.jpg)\n\n![Postman statistics](./docs/images/Postman-stats.jpg)\n\n### Client and server side examples\n\nSimple examples how to call `clamav-rest-api` (from client/browser side) using form action and axios library can be found in [examples/html](./examples/html) directory.\n\nServer side examples (Node.js) using axios, fetch and request library can be found in [examples/nodejs](./examples/nodejs) directory.\n\nThere is also simple Python [example](./examples/python) using `requests` library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenzino77%2Fclamav-rest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenzino77%2Fclamav-rest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenzino77%2Fclamav-rest-api/lists"}