tools-security-ratchet

Source-level security invariant ratchet. Encodes the invariant classes found by the 2026-07 audit (docs/reports/SECURITY-FINDINGS.md) as checks over the tree, with a shrinking baseline of known violations. New violations fail the build; fixing one and re-baselining is the only way the count goes down.

Tier	tools
Role	unclassified (baselined)
Path	`crates/tools/security-ratchet`
Edition	2021
Targets	tools-security-ratchet, tools_security_ratchet
Public items	14 across 0 modules
Tests	17

What it is for

Source-level security invariant ratchet.

Every check here encodes an invariant class from the 2026-07 audit (docs/reports/SECURITY-FINDINGS.md). The audit's systemic result was that mechanisms were correct and unguarded — deleting one turned no test red — and that per-instance tests do not generalise: the R19 remediation shipped 16 tests that each asserted on one already-fixed struct, so violation number 17 was invisible.

A ratchet is the answer to that class. It scans the whole tree, compares against a committed baseline of known violations, and fails only on ones the baseline does not contain. Fixing a violation and re-baselining is the only way the count goes down; adding one fails the build.

Capabilities

`crate root`

Source-level security invariant ratchet.

Item
`pub const CANONICAL_TENANT_GUC: & str`

`Baseline`

Source-level security invariant ratchet.

Item
`pub struct Baseline`
`Baseline :: fn load(path : & Path) -> Result <Self>`
`Baseline :: fn save(& self, path : & Path) -> Result <()>`

`Check`

Source-level security invariant ratchet.

Item
`pub enum Check`
`Check :: fn all() -> & 'static Check`
`Check :: fn remedy(& self) -> & 'static str`
`Check :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result`
`fn check(repo_root : & Path, baseline : & Baseline) -> Result <Report>`

`Finding`

Source-level security invariant ratchet.

Item
`pub struct Finding`
`Finding :: fn key(& self) -> String`
`fn scan(repo_root : & Path) -> Result <Vec <Finding>>`

`Report`

Source-level security invariant ratchet.

Item
`pub struct Report`
`Report :: fn is_clean(& self) -> bool`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

No public modules: the crate root is its whole surface.

Public surface

`crate root`

Item	What it is
`pub enum Check`	Which invariant a finding violates.
`Check :: fn all() -> & 'static Check`	—
`Check :: fn remedy(& self) -> & 'static str`	One line on what to do about it, printed with every new violation.
`Check :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result`	—
`pub struct Finding`	One violation
`Finding :: fn key(& self) -> String`	—
`pub struct Baseline`	The committed set of known-acceptable violations.
`Baseline :: fn load(path : & Path) -> Result <Self>`	—
`Baseline :: fn save(& self, path : & Path) -> Result <()>`	—
`pub struct Report`	Result of a scan measured against a baseline.
`Report :: fn is_clean(& self) -> bool`	—
`pub const CANONICAL_TENANT_GUC: & str`	SQL: a tenant GUC read under a non-canonical name.
`fn scan(repo_root : & Path) -> Result <Vec <Finding>>`	Scan the tree rooted at `repo_root` and return every violation found.
`fn check(repo_root : & Path, baseline : & Baseline) -> Result <Report>`	Scan and compare against the baseline.

No pub use re-exports: every item above is declared in this crate.

Boundary

Depends on no other workspace tier.

Shares tier tools with 84 other crates: tools-advisory-reach, tools-archive-guard, tools-artifact-scaffold, tools-ask-ai-core, tools-ask-ais, tools-ask-gemini, tools-book, tools-book-report, … (84 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`tools`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/tools/security-ratchet`
Vocabulary in force (lexicon)	`current`

Dependencies

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`anyhow`	`^1`	—	no	always
`regex`	`^1`	—	no	always
`serde`	`^1`	`derive`	no	always
`serde_json`	`^1`	—	no	always

Development. None.

Build. None.

Depended on by. Nothing in this workspace.

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
bin	`tools-security-ratchet`	`src/main.rs`
lib	`tools_security_ratchet`	`src/lib.rs`

Error model

No public error type was detected: no public item declares a type named *Error, and no public signature returns one.

Operational characteristics

Property	Evidence
async public surface	none detected
async runtime	none detected
database access	none detected
network I/O	none detected
unsafe code	none detected
environment variables	yes

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Variable	Read in
`CARGO_MANIFEST_DIR`	`src/lib.rs`

No workspace crate depends on this one.

Verification

Kind	Count
Unit tests	17
Integration tests	0
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Examples	Consumers
`crate root`	7	0	0

What the tests establish, by name:

a_commented_out_advisory_lock_is_not_a_violation — src/lib.rs
a_quoted_example_in_a_sql_comment_is_not_a_declaration — src/lib.rs
a_raw_string_secret_is_still_flagged — src/lib.rs
a_real_declaration_after_a_comment_is_still_flagged — src/lib.rs
a_secret_named_field_holding_a_sealing_wrapper_is_not_a_leak — src/lib.rs
a_secret_named_field_holding_another_struct_is_that_struct_s_problem — src/lib.rs
a_workflow_runs_the_live_database_suites — src/lib.rs
connection_urls_are_secret_shaped — src/lib.rs
detects_auto_debug_over_a_dsn_field — src/lib.rs
detects_auto_debug_over_a_secret_field — src/lib.rs
enable_without_force_is_a_finding_and_with_force_is_not — src/lib.rs
ignores_struct_without_debug_derive — src/lib.rs
non_canonical_tenant_guc_is_flagged — src/lib.rs
one_arg_advisory_lock_flagged_two_arg_clean — src/lib.rs
plain_web_urls_are_not_secret_shaped — src/lib.rs
secret_names_match_only_real_secrets — src/lib.rs
some_workflow_actually_calls_the_reusable_verify_gate — src/lib.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	8	14
Public modules with a `//!` block	0	0

pie showData
    title Public items with rustdoc
    "Documented" : 8
    "No rustdoc detected" : 6

Metrics

Metric	Value
Rust source files	2
Source lines	1117
Code lines	899
Public API items	14
Public modules	0
Tests	17
Examples	0
Cargo features	0
Direct runtime dependencies	4
Workspace reverse dependencies	0

pie showData
    title Public API by kind
    "constant" : 1
    "enum" : 1
    "function" : 2
    "method" : 7
    "struct" : 3

pie showData
    title Rust source composition
    "Code" : 899
    "Blank or comment" : 218

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

What it is for

Capabilities

crate root

Baseline

Check

Finding

Report

How to use it

Module structure

Public surface

Boundary

Where it sits

Dependencies

Feature flags

Targets

Error model

Operational characteristics

Configuration

Related capabilities

Verification

Documentation coverage

Metrics

Generation

`crate root`

`Baseline`

`Check`

`Finding`

`Report`