.vulqn.json Reference

Place a .vulqn.json file at the root of your repository to customize VULQN’s review behavior for that repo. The file is fetched from the PR’s head SHA on every review — config changes take effect immediately on the PR that introduces them.

All fields are optional. Missing fields fall back to system defaults.

Schema

{
  "version": 1,
  "ignore": { ... },
  "focus": { ... },
  "rules": [ ... ],
  "scoring": { ... },
  "confidence": { ... },
  "trigger": { ... },
  "output": { ... }
}

The top-level version field is required and must be 1.

ignore

Exclude files from review. Additive on top of VULQN’s global ignore list (which already excludes node_modules, lock files, binaries, etc.).

"ignore": {
  "pathPrefixes": ["scripts/", "docs/"],
  "extensions":   [".generated.ts", ".pb.go"],
  "filenames":    ["schema.graphql"]
}

Field	Type	Description
`pathPrefixes`	`string[]`	Drop files whose path starts with any of these prefixes
`extensions`	`string[]`	Drop files whose path ends with any of these extensions
`filenames`	`string[]`	Drop files whose basename matches exactly

focus

Only review files matching specific path prefixes. If set, files not matching any prefix are skipped.

"focus": {
  "paths": ["src/", "packages/", "apps/"]
}

Field	Type	Description
`paths`	`string[]`	Only review files matching one of these prefixes. Empty array `[]` disables focus (reviews everything).

rules

Inject custom review instructions for files matching specific path prefixes. Multiple rules can match the same file — all matching instructions are injected.

"rules": [
  {
    "paths": ["packages/core/src/ports/"],
    "instructions": "Check all new ports are exported from index.ts and have an adapter."
  },
  {
    "paths": ["backend/"],
    "instructions": "Flag any auth logic outside of the designated auth package."
  }
]

Field	Type	Description
`paths`	`string[]`	Path prefixes this rule applies to
`instructions`	`string`	Instructions injected into the AI prompt for matching files

scoring

Control how VULQN calculates the confidence score for a PR review.

"scoring": {
  "criticalPenalty": 25,
  "mediumPenalty":   8,
  "praiseBonus":     5,
  "praiseCap":       15
}

Formula: 100 - (critical × criticalPenalty) - (medium × mediumPenalty) + min(praise × praiseBonus, praiseCap)

The result is clamped to [0, 100].

Field	Type	Default	Description
`criticalPenalty`	`number`	`25`	Points deducted per critical finding
`mediumPenalty`	`number`	`8`	Points deducted per medium finding
`praiseBonus`	`number`	`5`	Points added per praise finding
`praiseCap`	`number`	`15`	Maximum total bonus from praise

All values must be ≥ 0. Invalid values fall back to defaults.

confidence

Control when VULQN fails a PR build and which findings are included.

"confidence": {
  "failOnCritical":        true,
  "failBelowScore":        80,
  "minFindingConfidence":  "medium"
}

Field	Type	Default	Description
`failOnCritical`	`boolean`	`true`	A critical finding always fails the build, regardless of score
`failBelowScore`	`number`	`80`	Fail build if confidence score is strictly below this threshold (e.g. score = 80 with threshold 80 = pass) (clamped to 0–100)
`minFindingConfidence`	`"high" \| "medium"`	`"medium"`	Drop AI findings below this confidence level

trigger

Control which PRs VULQN reviews.

"trigger": {
  "skipDrafts":     true,
  "targetBranches": ["main", "develop"],
  "skipAuthors":    ["dependabot[bot]", "renovate[bot]"]
}

Field	Type	Default	Description
`skipDrafts`	`boolean`	`false`	Skip draft/WIP PRs. GitHub uses the `draft` flag; Bitbucket detects `WIP:`, `[WIP]`, or `Draft:` title prefixes.
`targetBranches`	`string[]`	`[]` (all)	Only review PRs targeting these branches. Empty array = review all branches.
`skipAuthors`	`string[]`	`[]`	Skip PRs from these authors. Useful for bot accounts.

output

Control what VULQN posts on the PR.

"output": {
  "updatePrDescription": true,
  "postSummary":         true
}

Field	Type	Default	Description
`updatePrDescription`	`boolean`	`true`	Update the PR description with a VULQN review section
`postSummary`	`boolean`	`true`	Post a summary comment on the PR

Full example

{
  "version": 1,
  "ignore": {
    "pathPrefixes": ["docs/", "scripts/"],
    "extensions":   [".generated.ts"],
    "filenames":    ["schema.graphql"]
  },
  "focus": {
    "paths": ["src/", "packages/"]
  },
  "rules": [
    {
      "paths": ["src/auth/"],
      "instructions": "Flag any hardcoded credentials or tokens. Check all auth flows handle token expiry."
    }
  ],
  "scoring": {
    "criticalPenalty": 30,
    "mediumPenalty": 8,
    "praiseBonus": 5,
    "praiseCap": 15
  },
  "confidence": {
    "failOnCritical": true,
    "failBelowScore": 75,
    "minFindingConfidence": "medium"
  },
  "trigger": {
    "skipDrafts": true,
    "targetBranches": ["main"],
    "skipAuthors": ["dependabot[bot]", "renovate[bot]"]
  },
  "output": {
    "updatePrDescription": true,
    "postSummary": true
  }
}