.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.

Note

Repository branch filters in Settings are checked before .vulqn.json. Use settings for broad repository coverage and trigger.targetBranches for repo-owned policy.

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"
  }
}