IKARUS scan.server - Quickstart Guide ===================================== Minimum Requirements -------------------- - Operating system +- Windows Server 2019 and above (32- and 64-bit) +- Linux: Debian and RPM packages (64-bit) are provided +- Linux: archive with binaries - RAM: 8 GB - Free hard disk space: 2 GB - CPU: depends on the expected scan load, preferably quad core CPU or better - Internet access for automatic updates - Administrator/Root privileges Installation ------------ Windows: Start the setup executable and follow the instructions Debian: dpkg -i ikarus-scanserver-x.y.z_amd64.deb RPM: rpm -i ikarus-scanserver-x.y.zrh5.x86_64.rpm Linux archive: unpack, then run ./bin/scanserver_* -install Post-installation ----------------- Importing the license file. Method 1: Put the license file into /opt/scanserver/import_licenses folder Method 2: Windows (32-bit): C:\Program Files\IKARUS\scan.server\bin\scanserver.exe -importlicense Windows (64-bit): C:\Program Files\IKARUS\scan.server\bin\scanserver_w64.exe -importlicense Linux: /opt/scanserver/bin/scanserver_l64 -importlicense Configuration ------------- By default, the IKARUS scan.server is running on port 80. To change it, and other options, use conf/scanserver.json and comments therein. Restart the "scanserver" service to apply changes. Scanning files -------------- JSON HTTP endpoint: /api/scan - interface to scan as JSON PUT file: scan with default config POST json-body: use the post-data to scan according to json-config GET/POST with "q" argument: use the "q" argument to scan according to json-config POST with "q" and "up_file" arguments: scan the uploaded file "up_file" with JSON config "q" (or default config if provided) Any provided scan-config parameter overrides the corresponding default scan-config parameters ftom server-config. Example usage: http:///api/scan/?q={"input":{"filename":"/path/to/file"}} See JSON_desc.txt for full list of possible options and response format. After the request is processed and the file is scanned, the IKARUS scan.server returns a JSON response with information about the scanned file. See appendix A for a response example. Other HTTP endpoints: /api/config/get - return configuration as JSON /api/keepalive - All endpoints are working in keep-alive mode to increase throughput, closing TCP connections after 10 seconds of inactivity. Send a keepalive request to reset the 10 seconds timer for current connection /api/softstop - stop the server in a clean way /api/hardstop - terminate the server immediately, don't restart the service /api/hardrestart - terminate the server immediately, restart the service. watchdog must be enabled for this feature to work, and on windows the service should be configured for automatic restart on failure. /api/control - control the server GET or POST with "q" parameter or json-body to control the server Now only {"cmd": "reload", "wait": boolean} command is supported. It reloads T3+VDB. {"wait": true} will wait for the reload to complete before sending the response, otherwise it will do a reload in background /metrics - Prometheus metrics endpoint Legacy XML endpoints (kept for backwards compatibility): 1) HTTP POST request to http:///virusscan with the file in a multipart container 2) HTTP PUT request to http:///virusscan with the file 3) HTTP GET request to http:///virusscan?filename= Additionally, we provide an example Python script (scanserver_upload.py) which will use an HTTP PUT request to the XML endpoint to upload a file to the IKARUS scan.server. It accepts two parameters: - HTTP server: URL to scan service including the virusscan path, e.g. http://127.0.0.1/virusscan - File to upload: Path to file that should be scanned Automatic updates ----------------- The IKARUS scan.server connects every 10 minutes to the IKARUS update servers to check for new versions of the modules (service and update binaries, scan engine module and virus database). Requesting version information ------------------------------ To get information about the version numbers of IKARUS scan.server and the update module, as well as scan.engine and VDB version information, send an HTTP GET request to http:///api/config/get - return configuration as JSON. http:///versioninfo Provides version information in XML. ClamAV interface ---------------- IKARUS scan.server supports a ClamAV compatible TCP socket that mimics clamd (default TCP port: 3310, unix socket is supported as well). It only supports the scanning of single files and buffers. For further information regarding the use of the interface directly, please read the ClamAV documentation at https://www.clamav.net/documents/scanning#clamd (commands supported: SCAN, CONTSCAN, MULTISCAN, INSTREAM, FILDES, VERSION, and RELOAD) Signals ---------------- On Linux, SIGINT or SIGTERM initiate a graceful shutdown when used once, or cause a hard exit when used twice. SIGUSR1 initiates a VDB reload. Appendix A - scan.server JSON scan result ----------------------------------------- Request: http:///api/scan/?q={"input":{"filename":"F:/tmp/pw_protected_eicar.zip"},"passwords":["test","asdfasdfff"],"options":{"report_passwords":true},"output":{"pretty":true}} Response: { "file": "F:/tmp/pw_protected_eicar.zip", "items": [ { "item": 2, "name": "F:/tmp/pw_protected_eicar.zip:eicar.com", "status": "infected", "crc": 13432166488320302741, "filetype": 2823, "filesize": 68, "statistics": { "passwords": [ "asdfasdfff" ] } } ], "result": { "crc64": 8376063534806477876, "filetype": 297, "status": "infected", "infected_item": "F:/tmp/pw_protected_eicar.zip==>eicar.com", "sigid": 462103, "signame": "EICAR-Test-File", "num_items": 2, "time": 7503 } } Appendix B - scan.server reply for JSON version information request ------------------------------------------------------------------- { "running_threads": 5, "version": "IKARUS Scan.Server 6.0.0.0", "t3": { "major": 6, "minor": 0, "patch": 1, "hash": "1f228d4e5f5262db2816b8422653112c40f2cb693bf755959de8de6e6e39dd5c" }, "vdb": { "build": 104579, "num_sigs": 454839, "num_crcs": 10068227, "num_adcrcs": 1138550, "num_negcrcs": 2795380, "num_hdrcrcs": 115, "creation_date": "2022-02-10 13:18:14" } }