submit_assertions

Submit assertions for a security control or an assumption.

Mutating: persists new assertion records against the target. It does NOT run verification itself — assertions are checked later in CI (structurally, then semantically) and cryptographically attested; submitting only records the claims to be verified. To read existing assertions use list_assertions; to remove one use delete_assertion.

Each assertion is a typed, machine-verifiable claim about a system property (source code, configuration, infrastructure, or external service settings).

Provide exactly one of control_id or assumption_id:

• control_id: proves a control is implemented (e.g., "CTRL-01")

• assumption_id: proves a system property claim (e.g., "AS5" — asset non-applicability, attacker non-applicability, scope decisions)

For assumption assertions against the feature description (greenfield), use target instead of file in params: {"type": "pattern_matches", "params": {"target": "feature_description", "pattern": "password.*TOTP"}, "description": "..."}

Args: model_id: ID of the threat model. control_id: ID of the control (omit if using assumption_id). assumption_id: ID of the assumption (omit if using control_id). assertions_json: JSON array of assertion objects. Each object has: - type (required): one of the assertion types below - params (required): type-specific parameters (file or target + pattern/name/etc.) - description (required): human-readable explanation of what this proves - repo (optional): "org/repo-name" for multi-repo setups

Assertion types:

• function_exists: Check that a function or method exists in a file. Supports Python, JavaScript, TypeScript, Go, Rust, Swift, Java, C#. Params: file (File path relative to project root), name (Function or method name)

• class_exists: Check that a class, struct, or interface exists in a file. Params: file (File path relative to project root), name (Class, struct, or interface name)

• decorator_present: Check that a decorator is applied to a function (Python). Params: file (File path relative to project root), function (Function name), decorator (Decorator name (without @))

• function_calls: Check that a function calls another function. Params: file (File path relative to project root), caller (Calling function name), callee (Called function name)

• import_present: Check that a module is imported in a file. Supports Python, JavaScript, Go, Rust. Params: file (File path relative to project root), module (Module or package name)

• file_exists: Check that a file exists at the given path. Params: file (File path relative to project root)

• file_hash: Check that a file's hash matches an expected value. Use scope_file/scope_start/scope_end to reference the code that pins this hash (e.g., a deploy script that verifies the file's integrity). Params: file (File path relative to project root), algorithm (Hash algorithm: sha256, sha384, sha512, md5), expected_hash (Expected hex-encoded hash), scope_file (File containing code that references/checks this hash. Tier 2 reviews this code to verify the hash check is meaningful.); optional: scope_start (Regex marking start of the relevant code section in scope_file.), scope_end (Regex marking end of the relevant code section in scope_file.)

• pattern_matches: Check that a regex pattern exists in a file. Uses RE2 syntax (no backreferences, lookahead, or lookbehind). Params: file (File path relative to project root), pattern (RE2 regex pattern to search for); optional: scope_start (Regex pattern marking the start of the search scope within the file. Only content between scope_start and scope_end is searched.), scope_end (Regex pattern marking the end of the search scope. Defaults to end of file if omitted.), multiline (If true, ^ and $ match line boundaries instead of string boundaries. Default: false.), dotall (If true, . matches newlines, enabling patterns that span multiple lines. Default: false.)

• pattern_absent: Check that a regex pattern does NOT exist in a file. Uses RE2 syntax (no backreferences, lookahead, or lookbehind). Params: file (File path relative to project root), pattern (RE2 regex pattern that must be absent); optional: scope_start (Regex pattern marking the start of the search scope within the file. Only content between scope_start and scope_end is checked for absence.), scope_end (Regex pattern marking the end of the search scope. Defaults to end of file if omitted.), multiline (If true, ^ and $ match line boundaries instead of string boundaries. Default: false.), dotall (If true, . matches newlines, enabling patterns that span multiple lines. Default: false.)

• no_plaintext_secret: Check that no plaintext secrets matching given patterns exist in a file. Patterns use RE2 syntax (no backreferences, lookahead, or lookbehind). Params: file (File path relative to project root), patterns (JSON array of regex patterns to check for secrets)

• config_key_exists: Check that a config key exists. Supports JSON, YAML, TOML, INI, .env files. Use dot notation for nested keys. Params: file (File path relative to project root), key (Config key (dot notation for nested))

• config_value_matches: Check that a config value matches a regex pattern. Uses RE2 syntax (no backreferences, lookahead, or lookbehind). Params: file (File path relative to project root), key (Config key (dot notation for nested)), pattern (RE2 regex pattern the value must match)

• env_var_referenced: Check that an environment variable is referenced in a file. Detects os.environ, process.env, ${VAR}, $VAR, etc. Params: file (File path relative to project root), variable (Environment variable name)

• dependency_exists: Check that a package exists in a dependency manifest. Supports requirements.txt, package.json, Cargo.toml, go.mod, pyproject.toml, pom.xml. Params: manifest (Path to dependency manifest file), package (Package name)

• dependency_version: Check that a package version satisfies a constraint. Uses PEP 440 syntax for Python, semver for JS. Params: manifest (Path to dependency manifest file), package (Package name), constraint (Version constraint (PEP 440 or semver))

• parameter_validated: Check that a function validates a specific parameter. Tier 1 checks existence, tier 2 uses AI to verify validation logic. Params: file (File path relative to project root), function (Function name), parameter (Parameter name that should be validated)

• error_handled: Check that a function has error handling (try/catch/except, Go error checks, Rust Result). Params: file (File path relative to project root), function (Function name)

• middleware_registered: Check that middleware is registered in a file. Detects .use(), .add_middleware(), @decorator patterns. Params: file (File path relative to project root), middleware (Middleware name or class)

• http_header_set: Check that an HTTP header is set or referenced in a file. Params: file (File path relative to project root), header (HTTP header name)

• test_exists: Check that test files matching a glob pattern exist. Params: pattern (Glob pattern for test files)

• test_passes: Run tests matching a pattern and verify they pass. Auto-detects pytest, npm test, cargo test. Params: pattern (Test name or pattern to match)

• module_exists: Check that a Verilog/SystemVerilog module (or primitive/program) is declared in a file. Params: file (File path relative to project root), name (Module name)

• module_instantiated: Check that a module directly instantiates another module inside its module...endmodule body. Params: file (File path relative to project root), parent (Enclosing module name), child (Instantiated module name)

• port_exists: Check that a module declares a port, optionally with a specific direction. Detects ANSI header and non-ANSI body declarations. Params: file (File path relative to project root), module (Module name), port (Port name); optional: direction (Port direction: input, output, or inout)

• parameter_defined: Check that a parameter or localparam is declared, optionally that its assigned value matches a regex (RE2 syntax). Params: file (File path relative to project root), parameter (Parameter or localparam name); optional: module (Module to scope the search to (whole file if omitted)), pattern (RE2 regex the assigned value must match)

• signal_exists: Check that a net or variable (wire, reg, logic, bit) is declared. Params: file (File path relative to project root), name (Signal name); optional: module (Module to scope the search to (whole file if omitted)), kind (Declaration kind: wire, reg, logic, or bit)

• sva_assertion_present: Check that a named SystemVerilog assertion is present: a property declaration, or a labelled assert/assume/cover statement. Params: file (File path relative to project root), name (Property name or assertion label)

• register_reset: Check that a register is assigned on a reset path. Tier 1 finds an always block that references the reset and assigns the signal; tier 2 uses AI to verify the register resets to a safe, known value. Params: file (File path relative to project root), signal (Register/signal name that must be reset); optional: reset (Reset signal name (common rst/reset names detected if omitted))