Skip to main content

Custom rule packs

Vulkro ships a large built-in detector set, but you can add your own detection patterns without waiting on a release. Custom rules are written in YAML, run alongside the built-in detectors on every scan, and can encode organisation-specific concerns: an internal token format, a banned API, a framework convention your team enforces.

Two pattern modes​

Each rule matches one of two ways:

  • regex: a file-glob filter plus a regular expression. Cheap, matches on raw bytes, good for secret formats and simple text patterns.
  • ast: a tree-sitter language plus a node type and identifier match. Higher precision, requires the file to parse, good for "this specific call in this specific language".
vulkro-rules.yaml
rules:
  - id: corp-internal-token
    severity: critical
    owasp: SecurityMisconfiguration
    confidence: high
    message: "Internal corp token committed to source"
    remediation: "Rotate the token and read it from an environment variable instead."
    pattern:
      regex: "intsk_[A-Za-z0-9]{32}"
      file_globs:
        - "src/**/*.{ts,js,py,go}"
        - "**/.env*"

  - id: deny-eval-react
    severity: high
    owasp: ServerSideRequestForgery
    confidence: high
    message: "eval() in a React component: potential XSS sink"
    remediation: "Parse the input instead, for example JSON.parse for JSON-shaped data."
    pattern:
      ast:
        language: typescript
        node: "call_expression"
        callee_identifier: "eval"
      file_globs:
        - "src/**/*.{tsx,jsx}"

Duplicate rule IDs are an error at load time, so keep IDs unique across every file that a scan loads.

Where rules come from​

A scan merges rules from these sources:

  • A vulkro-rules.yaml file at the project root is auto-discovered. No flag is needed.
  • vulkro scan . --rules <PATH> adds an extra rule file or a directory of rule files for that run.
  • Installed rule packs under ~/.vulkro/rule-packs/<author>/<name>/<version>/ participate in every subsequent scan.

Test a rule locally​

Point a scan at a small fixture project and iterate until each rule fires where you expect and stays quiet where you do not:

vulkro scan ./test-project --rules ./my-rules.yaml

Keep a directory of positive and negative fixtures next to your rules so you can re-run them as a regression check when you edit a pattern.

Rule packs from the registry​

A rule pack is a versioned bundle of rules published under an <author>/<name> id. Manage packs with vulkro rules:

vulkro rules list                     # available packs in the registry index
vulkro rules add acme/api-security    # fetch, verify signature, install
vulkro rules installed                # what is installed locally
vulkro rules verify acme/api-security # re-check the on-disk signature
vulkro rules remove acme/api-security # uninstall every version
vulkro rules update                   # refresh the registry index

Packs are signed, and add installs a pack only after its signature verifies against the trust roots the binary ships with. verify re-checks an installed pack at any time. Pin a version with vulkro rules add acme/[email protected]; the default is the latest published version.

Reuse existing Semgrep rules​

If you already maintain Semgrep rules, convert one into Vulkro's format:

vulkro rules import-semgrep my-semgrep-rules.yaml

The importer writes a vulkro-rules.yaml next to the input, which a later vulkro scan auto-discovers with no extra flag. Translation is best-effort: simple patterns become regexes, and compound shapes (pattern-either, pattern-not, patterns:) are skipped with a warning per rule, so review the output before relying on it. Exit code is 0 on success, 2 on a read or parse error.

Last updated on