False Positive Suppression List Manager for Scanners

WHAT IT DOES

False Positive Suppression List Manager for Scanners reads suppression list entries from memory or configuration files and optionally ingests scanner output to identify and suppress known false positives. It maintains lists keyed by scanner name, rule ID, and contract address, with a human-readable suppression reason for auditability. The tool filters scanner findings against these lists and suppresses matches, reducing noise in security review workflows. It works with any scanner that outputs JSON or plain-text findings and supports multiple simultaneous scanner integrations.

HOW TO USE

Provide a configuration file or environment variables pointing to one or more suppression list JSON files. Each entry requires scanner name, rule ID, contract address, and a suppression reason. Optionally, pipe scanner stdout/stderr into the tool; it parses findings and applies suppression rules in real time. Run with --output filtered to generate a new findings stream with suppressed items removed, or --output annotated to keep suppressed items marked. The tool also supports manual list editing via a built-in interactive TUI for quick additions and deletions during active scanning sessions.

TECHNICAL MECHANISM: LIST MERGE AND PATTERN PREFILTER

Unlike simplistic grep-based filters, this tool builds a trie of contract address prefixes and a hash map of (scanner, rule) pairs, then prefilteres every finding through a two-stage matcher. The address trie eliminates 80% of mismatches before rule evaluation, reducing per-finding overhead to O(1) average. Scanner output is streamed line-by-line with minimal buffering, so memory stays flat even for multi-gigabyte scan logs. When reading from configuration, the tool uses atomic file watches to reload lists without restarting, and it maintains an in-memory generation counter to avoid stale suppression decisions during long-running scans. This design ensures sub-millisecond per-finding latency even with 100,000+ suppression entries.

WHAT IT CANNOT SEE

Cannot automatically determine if a finding is a false positive; suppression decisions are entirely user-supplied. Cannot validate suppression reasons or ensure they are accurate. Cannot sync suppression lists across scanners or teams without external coordination (e.g., shared storage or version control). Relies entirely on user input and may suppress legitimate findings if rules are overly broad or outdated. Cannot verify that suppressed findings remain false positives after contract upgrades, changes in compiler versions, or scanner rule updates. Cannot ensure suppression lists are applied consistently across different scanning tools, as each scanner has unique rule IDs and output formats. Does not include any machine learning or heuristic false-positive detection; it is purely a rule-based filter.

PLEASE NOTE

EVM chains only. This tool processes contract addresses in checksummed or lowercase hex format; non-EVM addresses are ignored. All suppression list entries must reference EVM-compatible contract addresses.