Documentation
¶
Overview ¶
Package scan checks uploaded files for malware. It defines the Scanner contract, a client for ClamAV's clamd daemon (the free scanner most self-hosted products use), and Inspect, which plugs any Scanner into an upload.Policy so every upload path scans before it reports success.
Scanning fails closed: a file is accepted only on a clean verdict, so a scanner that is down refuses uploads (CodeUnavailable) instead of letting them through unscanned. An app that prefers to stay up wraps its Scanner and decides there.
Index ¶
Constants ¶
const ( // DefaultTimeout bounds one scan, connection included. DefaultTimeout = 2 * time.Minute // DefaultChunkSize is the size of the INSTREAM chunks sent to clamd. DefaultChunkSize = 64 << 10 )
Defaults of Clamd.
const ( AlgorithmMD5 = "md5" AlgorithmSHA256 = "sha256" )
The exact-hash algorithms this package computes.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Clamd ¶
type Clamd struct {
Network string
Address string
// Timeout bounds one scan; 0 means DefaultTimeout.
Timeout time.Duration
// ChunkSize of the stream; 0 means DefaultChunkSize.
ChunkSize int
}
Clamd scans with a clamd daemon over TCP ("tcp", "127.0.0.1:3310") or a Unix socket ("unix", "/run/clamav/clamd.ctl"), streaming the file with the INSTREAM command, so the daemon needs no access to the files. clamd refuses streams over its StreamMaxLength (100 MiB by default in current ClamAV, 25 MB in old releases); keep it at least as large as the largest upload a policy allows, or such uploads fail with CodeTooLarge.
type Digest ¶
type Digest struct {
// Algorithm names the fingerprint: AlgorithmMD5, AlgorithmSHA256, or
// the name a perceptual Fingerprinter gives its own.
Algorithm string
// Value is the fingerprint, lower-case hex for the exact hashes.
Value string
}
Digest is a fingerprint of a file's content: an exact hash (MD5 and SHA-256 are what published hash lists use) or a perceptual hash that survives resizing and re-encoding (PDQ, PhotoDNA), computed by a Fingerprinter.
type Fingerprinter ¶
Fingerprinter computes one Digest of r. Perceptual hashing needs an image decoder and lives in the application (or a module with its own dependencies); it plugs in here.
type HashMatcher ¶
HashMatcher looks a fingerprint up in a list of known content: a hash list loaded in memory (HashSet), a moderation service, or a database. A match is a Verdict with Clean false and Signature naming the list entry; an error means the lookup did not complete.
type HashMatcherFunc ¶
HashMatcherFunc adapts a function to HashMatcher, for a moderation API call.
type HashSet ¶
type HashSet struct {
// contains filtered or unexported fields
}
HashSet is a HashMatcher over a fixed list of digests held in memory, for lists that are published as files and loaded at start-up. It is immutable once built; load a new list into a new HashSet. Exact hashes match case-insensitively.
func NewHashSet ¶
NewHashSet returns a HashSet matching digests, reporting signature (the list's name, such as "known-abuse:2026-10") on a match; the matched digest is not echoed, because the signature reaches the uploader.
type Scanner ¶
Scanner scans a stream. An error means the scan did not complete; it says nothing about the content.
func HashScanner ¶
func HashScanner(f Fingerprinter, m HashMatcher) Scanner
HashScanner returns a Scanner that fingerprints the stream with f and asks m, so a hash list plugs into Inspect like a virus scanner and fails closed the same way. Chain it with a malware Scanner through upload.Inspectors to run both.
type ScannerFunc ¶
ScannerFunc adapts a function to Scanner, for cloud scanning APIs and tests.