Configuration

A config found inside the audited target is written by whoever controls the target, so it can only narrow an audit. It cannot enable opt-in auditors, add credentials or switch off the --fail-on gate. Settings like that come only from flags or from a file passed with --config <path>. See apps/cli/README.md.

The config file

openaudit init writes openaudit.config.json. Flags on the command line take precedence over it.

A config found in the audited target is written by whoever controls the target, so it is only partly trusted. From there, openaudit honours only (which can only narrow the default set: it never enables opt-in or agentic auditors), exclude, categories, failOn (except "none"), ignore and options.maxPages, and prints a notice when the config narrows which auditors run. Settings that send data, cost money or add credentials (options.agentic, ai, model, headers, settings, browser, ...) are ignored with a warning. Those settings are accepted only from flags or from a file passed explicitly with --config <path>. Every report states how many findings each config or baseline suppressed. Use --no-config to ignore the target's config entirely. When CI audits untrusted changes (pull requests from forks), pass --fail-on and --no-config explicitly, because the change itself can edit the config.

{
  "only": [],
  "exclude": ["code.semgrep"],
  "categories": [],
  "failOn": "high",
  "ignore": {
    "rules": ["code.hygiene/ci-missing"],
    "paths": ["test/fixtures/**"],
    "fingerprints": []
  },
  "options": { "maxPages": 10 }
}

Every finding has a stable fingerprint. To accept a known issue, add its fingerprint to ignore.fingerprints, or pass a whole earlier report with --baseline.

Reference

Generated from openaudit schema config. Keys marked trusted only are ignored with a warning when the config is found inside the audited target; pass the file with --config <path> to use them.

Per-auditor settings

Settings for the agentic auditors go in options.settings, under "agent" for all of them or under one auditor's id.

{
  "settings": {
    "agent": { "maxTurns": 60, "maxBudgetUsd": 5 },
    "agent.webapp-security": {
      "instructions": "Test accounts: alice@test.example / bob@test.example (passwords in the staging vault). Do not touch /billing.",
      "storageState": "./auth.json"
    }
  }
}

The available keys are maxTurns, maxBudgetUsd, effort (low to max, default high), maxFindings (default 40), instructions and storageState (a Playwright storage-state file for a logged-in test account; it must live inside the project, or the working directory for URL targets). Arbitrary Playwright flags are not accepted, because several of them execute code.

JSON Schema

Point your editor at it for completion and validation: openaudit schema config > openaudit.schema.json.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "openaudit config",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "only": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exclude": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "security",
          "accessibility",
          "performance",
          "seo",
          "privacy",
          "best-practices",
          "reliability",
          "maintainability",
          "supply-chain",
          "compliance"
        ]
      }
    },
    "failOn": {
      "type": "string",
      "enum": [
        "critical",
        "high",
        "medium",
        "low",
        "info",
        "none"
      ]
    },
    "ignore": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "fingerprints": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": true
    },
    "options": {
      "type": "object",
      "properties": {
        "offline": {
          "type": "boolean"
        },
        "browser": {
          "type": "boolean"
        },
        "maxPages": {
          "type": "number"
        },
        "agentic": {
          "type": "boolean"
        },
        "ai": {
          "type": "boolean"
        },
        "model": {
          "type": "string"
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "concurrency": {
          "type": "number"
        },
        "settings": {
          "type": "object",
          "additionalProperties": {
            "type": "object"
          }
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}