How to author an audit methodology

A methodology determines which questions TheSpider asks each enabled model. You author it as an immutable project configuration version in the web application.

Prerequisites

• You have the admin or owner role.
• The project exists in security or bugs mode.
• The server model catalog contains the model code you plan to run.

Design the coverage matrix

TheSpider creates work from buckets × passes × enabled models.

• A bucket is a review area, such as authentication or data integrity.
• A category is a report classification that can belong to one or more buckets.
• A pass is an audit perspective with a repository scope.
• A prompt section supplies shared instructions, a severity or impact rubric, and the output contract.

Start with two or three buckets and two focused passes. A larger matrix costs more model runs and often repeats evidence without improving coverage.

Author the configuration

1. Open the project.
2. Select Config.
3. Select Author new version.
4. Replace config_json with a configuration like this:

{
  "name": "Web API review",
  "buckets": [
    {
      "code": "auth",
      "name": "Authentication and authorization",
      "description": "Identity, session, and permission boundaries",
      "categories": ["authn", "authz"]
    },
    {
      "code": "data",
      "name": "Data integrity",
      "description": "Validation, persistence, and transaction boundaries",
      "categories": ["validation"]
    }
  ],
  "categories": [
    { "code": "authn", "name": "Authentication" },
    { "code": "authz", "name": "Authorization" },
    { "code": "validation", "name": "Input validation" }
  ],
  "passes": [
    {
      "code": "http",
      "name": "HTTP surface",
      "description": "Trace untrusted requests through authorization and validation",
      "scope": "src/http src/routes"
    },
    {
      "code": "storage",
      "name": "Persistence",
      "description": "Review queries, transactions, and tenant boundaries",
      "scope": "src/db migrations/**/*.sql"
    }
  ]
}

Each bucket and pass requires a non-empty code and name. Each pass also requires a non-empty scope. Categories are optional, but category codes referenced by a bucket must exist in categories.

Define pass scopes

A scope is a space-separated list of paths or glob tokens.

• A plain token matches an exact path or directory prefix. src/http matches files below src/http/.
• * matches across path separators. src/*.ts also matches src/sub/app.ts.
• ? matches one character.

Incremental campaigns select passes whose scope matches a changed path. Changes to dependency, lock, container, environment, and framework configuration files expand an incremental campaign to every pass because those files can affect the whole project.

Add prompt sections

Set prompt_sections to a filename-to-Markdown object:

{
  "global.md": "Audit only the bucket and pass in this slice. Report concrete, evidence-backed defects with exact file paths.",
  "severity_rubric.md": "Rate security findings as critical, high, medium, low, or info. In bug mode, interpret the same values as impact.",
  "output_schema.md": "Emit a JSON array between <THESPIDER_FINDINGS_JSON> and </THESPIDER_FINDINGS_JSON>."
}

Keep the marker in output_schema.md aligned with the configured prompt marker. The server renders these sections into every slice prompt and parses the model's raw stdout using that marker.

Create and verify the version

1. Select Create version.
2. Confirm that the Config page shows the new version and every prompt section.
3. Check the Coverage lenses value. It shows buckets × passes before model fan-out.
4. Open Settings and enable at least one model for the project.
5. Run one bounded batch:

thespider-agent run --once

Open Slices and confirm the slice completed and imported reports. If a runner produced output but no reports, use the runner troubleshooting catalog.

Version behavior

Configuration versions are immutable. A campaign stays pinned to the version it started with. Author another version to change coverage or prompt semantics; do not expect an in-flight campaign to adopt the new version.

Continue with audit workflows to choose full, incremental, and retest campaign cadence.