Skip to main content

Custom Signatures

Custom signatures allow you to detect organization-specific threats, internal indicators of compromise (IOCs), or known-bad files that are not covered by public ClamAV databases. This feature is available on Team tier and above.

Overview​

Custom signatures are ClamAV-compatible database files that you upload through the web console. They are distributed to all scanner pods in your cluster via the signature puller sidecar and loaded by the ClamAV daemon alongside official databases.

How It Works​

  1. You upload a signature database file in the web console
  2. The file is stored in the Guardimesh SaaS storage service
  3. Scanner puller sidecars download new signatures on their next update cycle (every 12 hours, or on pod restart)
  4. ClamAV reloads its databases to include the new signatures
  5. Subsequent scans use the custom signatures

Tier Limits​

TierMax DatabasesMax Size per DatabaseSupported Formats
Team102 MB.hsb, .sfp, .db
EnterpriseUnlimited5 MB.hsb, .sfp, .db, .ldb

Signature Formats​

Hash-Based Signatures (.hsb)​

The simplest format. Detects files by their exact hash (MD5, SHA1, or SHA256).

SignatureName:FileSize:Hash:FileType

Example — detect a known malicious binary by SHA256:

Malware.Linux.Miner-CustomIOC:4096:a1b2c3d4e5f6...full_sha256_hash...:*

Fields:

  • SignatureName: Your chosen name (will appear in scan results)
  • FileSize: Expected file size in bytes (use * for any size)
  • Hash: MD5, SHA1, or SHA256 hash of the file
  • FileType: ClamAV file type (use * for any)

Signature-Based Pattern Files (.db)​

Simple body-based signatures that match byte patterns in files.

SignatureName:TargetType:Offset:HexSignature

Example — detect a specific string in any file:

Suspicious.Script.CryptoMiner:0:*:6d696e65722e7374617274

Fields:

  • SignatureName: Your chosen name
  • TargetType: 0 = any file, 1 = PE, 6 = ELF, 9 = Mach-O
  • Offset: Byte offset (* = anywhere, 0 = beginning, EOF-n = end)
  • HexSignature: Hex-encoded byte pattern to match

Logical Signatures (.ldb) — Enterprise Only​

Complex signatures with boolean logic, allowing multiple conditions.

SignatureName;TargetDescriptionBlock;LogicalExpression;Subsig0;Subsig1;...

Example — detect a file containing both a specific string AND an ELF header:

Custom.ELF.Backdoor;Engine:81-255,Target:6;0&1;6d61696e;7265766572736573

Fields:

  • SignatureName: Your chosen name
  • TargetDescriptionBlock: Engine version range and target type
  • LogicalExpression: Boolean expression referencing subsignatures (0&1 = both must match)
  • Subsig0, Subsig1, ...: Hex-encoded patterns

Hash Signatures for PE Sections (.sfp)​

Detects PE (Windows) executables by section hashes — useful for detecting packed malware where the overall hash changes but section content remains constant.

SignatureName:SectionSize:SectionHash

Uploading Custom Signatures​

Via Web Console​

  1. Log in to the web console
  2. Navigate to Custom Signatures in the sidebar
  3. Click Upload Signature Database
  4. Select your .hsb, .sfp, .db, or .ldb file
  5. Provide a descriptive name
  6. Click Upload

The upload is validated for correct format before being accepted.

Propagation Time​

After upload, signatures propagate to scanners within:

  • Up to 12 hours (default puller update interval)
  • Immediately on pod restart (init container pulls all signatures)

To force immediate propagation, restart the scanner DaemonSet:

kubectl rollout restart daemonset -n guardimesh-system -l app.kubernetes.io/component=guardimesh-scanner

Creating a Custom Signature​

Example: Detecting a Known-Bad Binary by Hash​

  1. Calculate the SHA256 hash of the malicious file:
sha256sum /path/to/malicious-binary
# Output: a1b2c3d4e5f6789... malicious-binary
  1. Get the file size:
stat --format=%s /path/to/malicious-binary
# Output: 4096
  1. Create the signature file:
echo "Custom.Malware.InternalIOC-001:4096:a1b2c3d4e5f6789...:*" > my-signatures.hsb
  1. Upload my-signatures.hsb via the web console.

Example: Detecting Cryptocurrency Miners​

Create a .db file to detect common mining pool connection strings:

Custom.Miner.PoolConnection-Stratum:0:*:7374726174756d2b7463703a2f2f
Custom.Miner.PoolConnection-XMR:0:*:786d722d65752e6e616e6f706f6f6c2e6f7267
Custom.Miner.PoolConnection-Nicehash:0:*:6e696365686173682e636f6d

These hex strings decode to:

  • stratum+tcp:// (mining protocol prefix)
  • xmr-eu.nanopool.org (Monero mining pool)
  • nicehash.com (mining marketplace)

Testing Custom Signatures​

Using the Test Container​

  1. Create a file that matches your signature:
# For hash-based signatures, use the exact file
# For pattern-based signatures, create a file containing the pattern
echo -n "stratum+tcp://pool.example.com" > /tmp/test-miner-string
  1. Build a test container image:
FROM alpine:latest
COPY test-miner-string /var/tmp/test-miner-string
CMD ["sleep", "infinity"]
  1. Push to your registry and deploy:
docker build -t your-registry/guardimesh-custom-sig-test:latest .
docker push your-registry/guardimesh-custom-sig-test:latest

kubectl run custom-sig-test \
  --image=your-registry/guardimesh-custom-sig-test:latest \
  --restart=Never \
  --namespace=default
  1. Check scan results in the web console — you should see a detection with your custom signature name.

Using clamscan Locally​

Test your signature file locally before uploading:

# Install ClamAV locally
sudo apt-get install clamav

# Test against a sample file
clamscan --database=my-signatures.hsb /path/to/test-file

Managing Signatures​

Viewing Active Signatures​

The Custom Signatures page in the web console shows:

  • Database name
  • File format
  • Size
  • Upload date
  • Number of signatures in the file

Disabling a Signature Database​

Toggle a database to disabled in the console. Disabled databases are not downloaded by scanner pullers on the next update cycle.

Deleting a Signature Database​

Delete a database from the console. It will be removed from scanners on the next puller update cycle. Active ClamAV instances will stop using it after their next database reload.

Best Practices​

  1. Use descriptive signature names — Include a category and identifier: Custom.Miner.PoolConnection-Stratum, not sig1
  2. Test before uploading — Validate signatures locally with clamscan --database=yourfile.hsb
  3. Minimize false positives — Use specific hashes for known-bad files; use pattern signatures only for truly unique byte sequences
  4. Document your signatures — Maintain an internal record of what each signature detects and why it was added
  5. Review periodically — Remove signatures for threats that are no longer relevant
  6. Use hash signatures when possible — They are the most precise and have zero false-positive risk

Signature Format Reference​

For complete ClamAV signature format documentation, see the ClamAV Signature Writing Guide.

Next Steps​