.vulqn.json Reference

Add a .vulqn.json file to the root of a repository when the default review behavior needs to be more specific for that repo.

VULQN reads the config from the PR head commit. That means a PR can introduce or update .vulqn.json, and the new config applies to that same PR.

All fields are optional except version.

{
  "version": 1
}

If the file is missing, invalid JSON, missing version, or uses an unsupported future version, VULQN falls back to defaults.

Full example

{
  "version": 1,
  "ignore": {
    "pathPrefixes": ["docs/", "scripts/"],
    "extensions": [".generated.ts"],
    "filenames": ["schema.graphql"]
  },
  "focus": {
    "paths": ["src/", "packages/"]
  },
  "rules": [
    {
      "paths": ["src/auth/"],
      "instructions": "Flag hardcoded credentials, missing authorization checks, and token expiry bugs."
    }
  ],
  "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
  }
}

Defaults

Area	Default
`ignore`	No custom ignores beyond VULQN’s global ignored files.
`focus`	Review all reviewable files.
`rules`	No custom instructions.
`scoring.criticalPenalty`	`25`
`scoring.mediumPenalty`	`8`
`scoring.praiseBonus`	`5`
`scoring.praiseCap`	`15`
`confidence.failOnCritical`	`true`
`confidence.failBelowScore`	`80`
`confidence.minFindingConfidence`	`"medium"`
`trigger.skipDrafts`	`false`
`trigger.targetBranches`	`[]` meaning all branches allowed by repository settings.
`trigger.skipAuthors`	`[]`
`output.updatePrDescription`	`true`

`ignore`

Use ignore to exclude files that are not worth reviewing in this repository.

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

Field	Type	Behavior
`pathPrefixes`	`string[]`	Skips files whose path starts with one of these prefixes.
`extensions`	`string[]`	Skips files whose path ends with one of these strings.
`filenames`	`string[]`	Skips files whose basename matches exactly.

ignore adds to VULQN’s global ignored files. It cannot force VULQN to review files that are globally ignored, such as common lock files, binaries, build outputs, image assets, fonts, archives, and .vulqn.json itself.

`focus`

Use focus when only specific areas of a repository should be reviewed.

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

Field	Type	Behavior
`paths`	`string[]`	Reviews only files whose path starts with one of these prefixes.

If focus.paths would exclude every changed file in a PR, VULQN ignores the focus setting for that review. This avoids accidentally creating a config that suppresses all review coverage.

`rules`

Use rules to give VULQN path-specific review instructions.

{
  "rules": [
    {
      "paths": ["backend/payments/"],
      "instructions": "Check idempotency, decimal handling, refund paths, and Stripe webhook verification."
    },
    {
      "paths": ["src/auth/"],
      "instructions": "Flag missing authorization checks and unsafe token handling."
    }
  ]
}

Field	Type	Behavior
`paths`	`string[]`	The path prefixes where the rule applies.
`instructions`	`string`	Extra review guidance for matching files.

Multiple rules can match the same file. VULQN applies all matching instructions.

Limits:

Each rule’s instructions are capped at 2,000 characters.
All rule instructions together are capped at 10,000 characters.
Empty paths or blank instructions are ignored.

Write rules like code review guidance, not prompt engineering. Good rules are concrete, scoped, and tied to repository conventions.

`scoring`

Use scoring to change how VULQN calculates the confidence score.

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

Formula:

100 - (critical * criticalPenalty) - (medium * mediumPenalty) + min(praise * praiseBonus, praiseCap)

The final score is clamped between 0 and 100.

Field	Type	Default
`criticalPenalty`	non-negative number	`25`
`mediumPenalty`	non-negative number	`8`
`praiseBonus`	non-negative number	`5`
`praiseCap`	non-negative number	`15`

Invalid numeric values are ignored and the default for that field is used.

`confidence`

Use confidence to control the build status gate and the minimum finding confidence shown on the PR.

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

Field	Type	Default	Behavior
`failOnCritical`	`boolean`	`true`	Any critical finding fails the build status.
`failBelowScore`	number from 0 to 100	`80`	Fails the build status when confidence is strictly below this score.
`minFindingConfidence`	`"medium"` or `"high"`	`"medium"`	Drops findings below the selected confidence level.

Set minFindingConfidence to "high" only if your team prefers fewer, stronger findings over broader coverage.

`trigger`

Use trigger to skip PRs that should not be reviewed.

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

Field	Type	Default	Behavior
`skipDrafts`	`boolean`	`false`	Skips draft PRs.
`targetBranches`	`string[]`	`[]`	Reviews only PRs targeting one of these branches. Empty means no config-level branch restriction.
`skipAuthors`	`string[]`	`[]`	Skips PRs from matching author names or author IDs.

`output`

Use output to control the PR description review block.

{
  "output": {
    "updatePrDescription": true
  }
}

Field	Type	Default	Behavior
`updatePrDescription`	`boolean`	`true`	Adds or updates the VULQN review block in the PR description.

The schema also accepts postSummary for forward compatibility, but current review output is centered on inline comments, the PR description block, build status, and dashboard history.

Common patterns

Review only application code

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

Skip generated files

{
  "version": 1,
  "ignore": {
    "pathPrefixes": ["generated/"],
    "extensions": [".generated.ts", ".pb.go"]
  }
}

Make build status less strict

{
  "version": 1,
  "confidence": {
    "failOnCritical": true,
    "failBelowScore": 70
  }
}

Require high-confidence findings only

{
  "version": 1,
  "confidence": {
    "minFindingConfidence": "high"
  }
}

.vulqn.json Reference

Full example

Defaults

ignore

focus

rules

scoring

confidence

trigger

output