Adding a rule

Teach cryptarium about a crypto API by editing YAML. You usually do not need to change Go. What you will do: add a rule, add a positive and negative fixture, run make lint-rules.

Checklist

Stable id (do not rename later; SARIF baselines break)
Canonical primitive (or honest UNKNOWN)
Honest confidence (high only when the match proves the algorithm and key details)
Positive fixture that must match
Negative fixture that must not (especially comments)
references link to the API docs
make lint-rules passes

Full field list: Rule packs. Fixture layout: Fixtures. Shipped C packs (append new symbols there): rules/c/openssl.yaml, rules/c/libsodium.yaml, rules/c/mbedtls.yaml. C++-only packs: rules/cpp/cryptopp.yaml, rules/cpp/botan.yaml. Do not re-add OpenSSL under rules/cpp/; C++ files already load C packs.

Example 1: JavaScript

Append to rules/javascript/webcrypto.yaml (also covers TypeScript files):

  - id: js.crypto.generatekeypairsync
    primitive: UNKNOWN
    assetType: algorithm
    functions: [keygen]
    confidence: low
    match:
      kind: call
      package: crypto
      symbol: generateKeyPairSync
    references:
      - "https://nodejs.org/api/crypto.html#cryptogeneratekeypairsynctype-options"

Shipped rules in that pack already look like this:

  - id: js.crypto.createcipheriv.aes
    primitive: AES
    functions: [encrypt]
    confidence: medium
    match:
      kind: call
      package: crypto
      symbol: createCipheriv

Use medium or low when the API can pick the algorithm at runtime (for example generateKey or generateKeyPairSync). Do not guess RSA from the function name alone.

Positive fixture (testdata/rules/js.crypto.createcipheriv.aes/positive.js):

const crypto = require("crypto");

function seal(key, iv, plain) {
  return crypto.createCipheriv("aes-256-gcm", key, iv).update(plain);
}

Negative fixture (must not match):

// crypto.createCipheriv is only mentioned in a comment.
function seal() {
  return null;
}

Example 2: C / OpenSSL

Append to rules/c/openssl.yaml:

  - id: c.openssl.rsa_generate_key_ex
    primitive: RSA
    assetType: algorithm
    functions: [keygen]
    confidence: high
    match:
      kind: call
      package: openssl
      symbol: RSA_generate_key_ex
    references:
      - "https://www.openssl.org/docs/man3.0/man3/RSA_generate_key.html"

C++ files also load c packs. Put a rule in rules/cpp/ only when it should not apply to plain C. Compare with a vague API in the same pack:

  - id: c.openssl.evp_pkey_keygen
    primitive: UNKNOWN
    functions: [keygen]
    confidence: medium
    match:
      kind: call
      package: openssl
      symbol: EVP_PKEY_keygen

EVP_PKEY_keygen can create many key types. UNKNOWN is the right call. Positive fixture:

#include <openssl/rsa.h>

int make_rsa(RSA *rsa, BIGNUM *e) {
    return RSA_generate_key_ex(rsa, 2048, e, NULL);
}

Negative fixture:

/* RSA_generate_key_ex is only mentioned in a comment. */
int make_rsa(void) {
    return 0;
}

Enhance a rule

Common upgrades:

Lower false positives by tightening package / symbol.
Raise confidence only after you extract real parameters (or the symbol alone is unambiguous).
Add static parameters only when every hit shares them (example: known AES-128 constant).

    parameters:
      keySize: { value: 128 }

Extend the library catalog

To flag a Go module in go.mod, edit rules/libraries/catalog.yaml:

  - name: github.com/example/pq-crypto
    ecosystem: go
    primitives: [ML-KEM, ML-DSA]
    confidence: medium

A library in the lockfile is medium confidence at most. It is not proof the code uses that crypto. See Correlation.

When not to write a rule

Need	Use instead
Parse certificates	Certs detector
nginx / SSH / JWT config strings	Config detector
Follow data across files	Out of scope for YAML rules

What happens after the match?

The source detector emits a finding (where + what API).
Classification assigns Broken / Weakened / Safe / Unknown.
Scoring sets priority for the report.

Your YAML should describe the call site. It should not invent a migration target.

Validate

make lint-rules
make test
make check

Get started

Concepts

Detectors & rules

Guides

Reference

Adding a rule

Adding a rule

Checklist

Example 1: JavaScript

Example 2: C / OpenSSL

Enhance a rule

Extend the library catalog

When not to write a rule

What happens after the match?

Validate

Adding a rule

Checklist

Example 1: JavaScript

Example 2: C / OpenSSL

Enhance a rule

Extend the library catalog

When not to write a rule

What happens after the match?

Validate

Related