create-rule

Skill: Create Rule

OpenTaint is a whole-program, interprocedural, field-sensitive alias analysis engine. It already propagates through visible application code, calls, aliases, and individual fields; custom rules and approximations model only the assigned source, sink, or opaque-method boundary. Compile-time constants and literals carry no taint, so a source or carrier whose output is only a constant introduces nothing.

A unit names the source or sink members to detect. Identify an existing built-in or project library rule when it already implements the boundary, otherwise author a custom rule, then verify the unit against its test project. Every selected or created source rule must carry the unit's untrusted-data-source tag, and every selected or created sink rule must carry its unit group's *-sink tag. Production joins use those tags and are assembled later only when a new sink tag needs one.

Inputs

Provided by the caller, fall back to the default value when omitted. Ask back only when a required input is missing and has no sensible default

• project-root (optional) — root of the target project. Opentaint keeps all analysis artifacts under the fixed <project-root>/.opentaint/ directory, so every .opentaint/... path below resolves there. Default: current directory
• language (required) — target language for this project and language-specific instructions
• side (required) — sources or sinks; the unit's side. It selects the unit file, the sample style, and the test sub-project
• unit (required) — the <package-kebab> identifying the unit. Its spec and tracking are in .opentaint/tracking/rules/<side>/<unit>.yaml; its test project is .opentaint/test-projects/<unit>/<side> and its compiled model .opentaint/test-compiled/<unit>/<side>
• fix-target (optional) — a created rule <path>#<id> the main scan flagged, plus the false positive or false negative to correct. When set, narrow or broaden that one rule instead of authoring from the unit

Workflow

1. Check existing coverage

Browse the built-in library rules and .opentaint/rules to determine whether one already matches each unit entry. When one does, do not author a duplicate: set its rule_id in .opentaint/tracking/rules/<side>/<unit>.yaml to <relative-yaml-path>#<rule-id>. This string is tracking bookkeeping only. Do not add a rule reference to any production rule, production joins remain tag-based and are written later. The following command prints the built-in rules root path. Browse both roots using the language reference and search by the entry's exact language-specific identifier:

opentaint health --rules

Read .opentaint/tracking/rules/tags.yaml. A source unit must carry tag: untrusted-data-source, each sink unit group carries the one existing or newly registered *-sink tag its rules must extend.

In fix mode, don't author from the unit: go straight to that one flagged rule, adjust it by the false-positive/negative guidance per step 4, re-run this side's tests, and stop — leave the unit's other entries untouched. Otherwise, when entries already carry rule_id, continue from those recorded implementations and author only entries still lacking coverage. When the unit is partway (some stages done, some not), continue from the first unfinished stage on the artifacts already on disk rather than restarting.

2. Author the library rules

Derive each rule's pattern from the unit's exact member identifiers, recorded signatures, and relevant declaration metadata. Bind the tainted value to $UNTRUSTED and put the unit/group tag on the lib rule. A sink tag belongs to the whole semantic group, not to an individual method. One rule can cover several group methods and several rules can carry the same tag. The rule forms and locations are in the language reference.

For side: sinks, iterate groups: ensure every method under groups[].sinks has an implementing rule_id, and put the enclosing groups[].tag on every custom rule you create. For side: sources, use the unit's top-level tag.

3. Write the test joins

A library rule emits nothing on its own — to exercise it, wire it to the generic taint marker in a throwaway test join. Write one join for the side into the test project's marker rules, referencing the generic marker on one end and each lib rule_id selected for the unit on the other, so a positive sample's tainted value flows marker-to-rule (a sink side) or rule-to-marker (a source side). The test joins live only in the test project, never in the scanned rules tree. Their form, naming, and location are in the language reference.

4. Test until success

Run the rule tests directly as a foreground, blocking command and wait for exit — never background them or use Monitor. Load your lib rules and the test joins + markers, and iterate until every sample passes:

opentaint test rule run .opentaint/test-compiled/<unit>/<side> \
  -o .opentaint/test-results/<unit>/<side> \
  --ruleset .opentaint/rules --ruleset .opentaint/test-projects/<unit>/<side>/test-rules \
  --passthrough-approximations .opentaint/pass-through

test rule run auto-loads the built-in rules, so pass only your custom rulesets. Apply the passthrough approximations as-is, an empty one is harmless. Read the result with the bundled script — it prints the pass/fail counts and names the failing samples, so you never parse the JSON by hand:

uv run <skill-dir>/scripts/check-test-result.py <unit>/<side>

Fix by the verdict it reports:

• falseNegative → the match is too narrow, broaden it and confirm the metavariable names line up across branches and between refs and on
• falsePositive → the match is too broad, add an exclusion or a sanitizer
• skipped / disabled → the rule wasn't exercised; fix the sample's rule-test.yaml entrypoint or rule-id, or enable the rule

The concrete pattern operators for each fix are in the language reference.

5. Escalate when a positive won't converge

A positive that won't pass after ~3 rule fixes may have a cause no rule edit can fix. Localize the cause per references/debugging.md, then leave stages.tests_passing: pending and report it (per Output), rather than editing blindly.

Output

Artifacts

• the custom library rule file(s) under .opentaint/rules
• .opentaint/tracking/rules/<side>/<unit>.yaml — the unit's entries updated (per Tracking)

Summary

• the implementing lib rule ids, identifying which were built-in and which were created, a one-line test summary for the side, and the exact test rule run command used
• if blocked at step 5: stages.tests_passing left pending, and the cause —
  • a dropped library method on the failing sample's flow → the methods that need a model, to be approximated before a re-dispatch
  • nothing dropped and no clear rule cause → non-convergence, for the orchestrator to intervene

Tracking

This skill writes each unit entry's implementing rule_id and the unit's stages.tests_passing. rule_id is a <relative-yaml-path>#<id> locator for either the custom lib rule created for that entry or an existing built-in lib rule proven to cover it. Preserve the source unit's top-level tag and every sink groups[].tag, those tags are the authoring contract. A blocked unit stays tests_passing: pending.

.opentaint/tracking/rules/sources/<package-kebab>.yaml — one source unit per package (a dependency can span several packages), the file named for that package with . → -. tag is always the reusable untrusted-data-source group. dependencies names the dependency the package comes from, sources each an entry point { method, signature, note, rule_id } (method and signature use the exact language-specific identifiers from the plan), stages tracks the unit through rule authoring, and a blocker string is added under it when the unit can't be made to pass. Keep it clear from comments

dependencies:
  - <dependency-id>
tag: untrusted-data-source
sources:
  - { method: "<qualified-member>", signature: "<language-signature>", note: untrusted message payload, rule_id: null }
stages:
  test_project: pending
  tests_passing: pending

.opentaint/tracking/rules/sinks/<package-kebab>.yaml — one sink unit per package (a dependency can span several packages, each its own unit), the file named for that package with . → -. dependencies names the dependency the package comes from. groups partitions the package's dangerous operations by reusable sink tag; each group is { tag, sinks }, and each sink is { method, signature, note, rule_id }. The tag belongs to the group, never to an individual method: one rule may cover several methods and several rules may extend the same vulnerability family. method and signature use the exact language-specific identifiers from the plan. stages tracks the unit through rule authoring. Keep it clear from comments

dependencies:
  - <dependency-id>
groups:
  - tag: path-traversal-sink
    sinks:
      - { method: "<qualified-member>", signature: "<language-signature>", note: writes data to an untrusted path, rule_id: null }
stages:
  test_project: pending
  tests_passing: pending

Constraints

• Library rules MUST have options.lib: true and severity: NOTE
• Created source rules MUST carry the untrusted-data-source tag, created sink rules MUST carry their enclosing sink group's registered *-sink tag
• The test joins MUST have metadata.cwe and metadata.short-description
• In test joins, metavariable names must match across refs and on clauses or the join won't connect. Bind the tainted value to $UNTRUSTED in every lib source/sink rule
• Test-join rule paths are relative to a ruleset root: marker rules resolve under the test project's rules, lib rules under the built-in or custom scanned rules tree
• Rule IDs must be globally unique
• The custom lib rules go in the scanned rules tree; the test joins go only in the test project's marker rules
• Never scan the main project model
• Never try to edit the test project

Gotchas

• If you think a test project is wrong — hand it back upstream
• A positive that won't pass because a library method drops taint is not a rule bug — surface it for approximation (per step 5), don't broaden the rule to force it
• Keep produced rule files comment-free