​

Rule packs

Pro. For “how do I tune the rules?”

penthera rules list                         # packs in effect
penthera rules verify ./my-pack             # signature, hashes, schema, ReDoS guard
penthera deps --rules ./my-pack             # add a pack to a scan (repeatable)
penthera --repo . --rules ./my-pack

​

Trust model

1. Bundled in a release. lib/rules/<name>/ ships inside the npm package. Releases are staged on npm by CI and go live only when the maintainer approves them with 2FA (see .github/workflows/publish.yml). The publish workflow runs npm run rules:check, which refuses to stage a release with a bundled pack that is not signed by a key in lib/rules/allowed_signers. So a rule change has to pass through the maintainer’s signing key, which never enters CI, as well as through the 2FA approval.
2. By path, from you. --rules <dir> loads a pack from a directory you name. It must be signed by a key in lib/rules/allowed_signers or in a file you pass with --rules-signers <file>.

​

Why no runtime fetching

​

What verification checks

1. Signature. pack.json.sig is an OpenSSH signature (ssh-keygen -Y sign, namespace penthera-rules) over the exact bytes of pack.json. The signing key must be in an allowed_signers file, with namespaces (if set) including penthera-rules and valid-after/valid-before respected. Penthera verifies it in Node (ed25519 or RSA ≥ 2048), so it needs no ssh-keygen at run time.
2. File hashes. Every rule file’s SHA-256 must match pack.json. Rule files must be plain names in the pack directory: no paths, no .., no symlinks, size-capped.
3. Schema. Every rule is validated against its kind (below). Strings that reach your terminal or report may not contain control characters, ANSI escapes or bidi overrides. Template paths must stay on the scan target. min_penthera must not be newer than your Penthera.
4. ReDoS guard. Every regex must pass lib/rules/regex-guard.js (below).

​

Format

my-pack/
  pack.json        index: name, version, created_at, min_penthera, rules[]
  pack.json.sig    ssh-keygen -Y sign -n penthera-rules
  secrets.json     rule files, one kind each
  packages.json

{
  "schema": 1,
  "name": "ioc-2025-2026",
  "version": "1.0.0",
  "created_at": "2026-10-19T14:45:12Z",
  "min_penthera": "1.2.0",
  "description": "…",
  "rules": [
    { "file": "packages.json", "kind": "ioc-package", "sha256": "…" }
  ]
}

​

Kinds

​

The ReDoS guard

1. patterns longer than 512 characters, or with flags other than imsu;
2. backreferences and lookaround;
3. nested quantifiers: (a+)+, (\w*\s?)*;
4. alternation under an unbounded quantifier: (a|aa)+;
5. bounded repeats above 256;
6. an unbounded quantifier that every start position can reach and rescan (\s*x, [a-z]+@, x[^\n]*\| on xxxx…);
7. chains of quantifiers over overlapping characters (.*b.*, \s+\S*\s*), unless all of them are bounded and their product stays under 1,024.

​

Bundled packs

​

Writing and signing a pack

mkdir my-pack && $EDITOR my-pack/secrets.json   # { "kind": "secret", "rules": [ … ] }
npm run rules:build -- my-pack --name my-pack --version 1.0.0
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n penthera-rules my-pack/pack.json
echo "me@example.com namespaces=\"penthera-rules\" $(cut -d' ' -f1,2 ~/.ssh/id_ed25519.pub)" > my-signers
penthera rules verify my-pack --rules-signers my-signers
penthera deps --rules my-pack --rules-signers my-signers

​

Signing a release (maintainer)

1. Review the change: git diff lib/rules/. The signature vouches for every rule in the pack.
2. Sign each changed pack locally, never in CI: scripts/rules/sign-pack.sh lib/rules/<name> [~/.ssh/key]. The script rebuilds pack.json, signs it with ssh-keygen -Y sign -n penthera-rules, and runs penthera rules verify.
3. npm run rules:check must pass. The publish workflow runs it before staging.
4. Commit pack.json.sig with the release.