Audit Best Practices

Getting the most out of Solace — prepare your repository so audits maximise signal accuracy and minimise false positives.

Solace is the AI audit engine that powers Cygent's deep security audits. The quality of Solace's audit output depends on the context provided. Prepare your repository with these files before running an audit.

The files you include determine how much context Solace has. Structured scope definitions, specs, and invariants let Solace audit with greater precision and fewer gaps.

  • scope.md (Best practice) — place in the base directory and list all files in scope for the audit. Remove any paths you want Solace to ignore. This fixes scoping errors before the audit begins.
  • /docs or /specs folder (Best practice) — all official project documentation and specifications in one folder eliminates ambiguity. The more complete this is, the better Solace understands the intended behaviour of the system.
  • invariants.md (Recommended) — either a single invariants.md or per-contract spec files defining the invariants and properties the system must hold. Solace parses these and actively tries to break them during analysis.
  • trust_model.md (Recommended) — list every role in the system. Specify whether each is administrator-controlled or a third-party permissioned role, and what it should not be able to do if compromised. Critical for RBAC protocols.
  • known-issues.md (Recommended) — document design decisions and trade-offs that could look like bugs but are intentional and accepted. This tightens the signal-to-noise ratio and reduces false positives in the final report.
  • Cross-chain context (If applicable) — for protocols with external integrations or cross-chain interactions, provide documentation on external contracts, bridges, and expected cross-chain behaviour. Solace will attempt to fetch on-chain source code automatically, but supplementary documentation significantly reduces the information gap.
💡

Solace parses invariants.md and trust_model.md directly into its analysis passes — they aren't just background reading. Time spent writing them down is time Solace spends trying to break them.

Documentation hygiene

Conflicting or outdated documentation forces Solace to make assumptions about which source is authoritative. A single, current version of each document significantly improves audit accuracy.

  • Store all documentation in a single /docs folder at the repo root.
  • Remove or archive outdated, superseded, or conflicting versions before running an audit.
  • Don't leave historical drafts alongside the latest specs — this is especially common in repos where AI-generated docs have been iterated on over time.