rules

type Arg struct {
	String   string
	Complete bool
	Type     string
	// Name is the keyword/named-argument name this argument was passed under
	// ("shell" for `subprocess.run(cmd, shell=True)`), or "" for a positional
	// argument or a language/frontend that does not record names. Without it a
	// guard can only see that SOME boolean argument is true, which cannot
	// distinguish the dangerous `shell=True` from an innocuous `check=True`.
	// Rules read it through `kwargs`, which indexes arguments by this name.
	Name string
	// Tainted reports whether this argument carries taint at the call, so a rule
	// can ask WHICH argument the untrusted value arrived in: in
	// `subprocess.run(["ls", name])` it is an argv element, not the command.
	// False where there is no taint state (a dangerous-call guard), so a rule
	// keying on it never suppresses there.
	Tainted bool
	// Elems are an in-place container's elements in order (Type "aggregate"):
	// `arg[0].Elems[0]` is argv[0] of `subprocess.run(["sh", "-c", cmd])`.
	// Entries is the keyed form (Type "map"), indexed by constant keys; a
	// computed key names nothing and is absent.
	//
	// Both are EMPTY when the structure was not reconstructed, indistinguishably
	// from "no elements" — so a rule must demand positive evidence before
	// suppressing, and see .TaintInChildren below.
	Elems   []Arg
	Entries map[string]Arg
	// TaintInChildren reports that reading Elems/Entries will actually find the
	// taint. A value can be Tainted with this FALSE — mutated after it was built
	// (`d = {}` then `d[k] = tainted`), taint in a non-constant key, built
	// elsewhere (`tainted.split(",")`), or never reconstructed — where walking the
	// children finds nothing and would wrongly read as safe.
	//
	// The polarity is deliberate: the zero value is "not accounted for", so a site
	// that forgets this field costs a spurious finding, not a silent miss.
	TaintInChildren bool
}

type Callee struct {
	Pattern string
	When    string
}

type ConstArg struct {
	Index   int    `yaml:"index"`   // logical (receiver-excluded) argument index
	Matches string `yaml:"matches"` // regexp the constant string argument must match
}

type EvalHostFixed func() bool

type ExtendRefs []string

type GlobSet struct {
	// contains filtered or unexported fields
}

type Guard struct {
	// contains filtered or unexported fields
}

type Rule struct {
	ID        string   `yaml:"id"`
	Languages []string `yaml:"languages"` // empty => applies to all languages
	Severity  Severity `yaml:"severity"`

	// Confidence overrides the confidence a dangerous-call finding is reported
	// with; empty means High. Set "medium" for a heuristic call-site rule that
	// wants a human/LLM look: confidence is what makes a finding TRIAGEABLE
	// (internal/llm.Filter reviews everything at or below its threshold), while
	// severity alone decides the CI gate (-fail-on). Ignored by dataflow rules,
	// whose confidence comes from the flow itself (intra-procedural High,
	// cross-function Medium).
	Confidence string `yaml:"confidence"`

	CWE     string `yaml:"cwe"`
	Message string `yaml:"message"`

	// Extend names one or more `_`-prefixed fragment files (e.g.
	// "$_go-common.yaml") whose pattern-list fields are merged into this rule at
	// load time, keeping a language's shared sources/propagators in one place.
	// The loader appends the fragment's entries ahead of this rule's own (deduped)
	// and then clears Extend; it never reaches the matcher. Accepts a single
	// scalar or a YAML sequence. See internal/rules/loader.
	Extend ExtendRefs `yaml:"extend"`

	Sources    []string `yaml:"sources"`
	Sanitizers []string `yaml:"sanitizers"`

	// RequestObjectSources are source globs whose value is an untrusted HTTP
	// request OBJECT (not a scalar), e.g. Go's synthetic "go:@net/http.Request".
	// A DEPENDENCY function containing one internally (a framework accessor
	// reading *http.Request through a field, with no tainted argument) generates
	// request taint out of nowhere, so the engine seeds such a function when user
	// code calls it directly (buildReqSourceHosts); otherwise the demand-driven
	// dependency scope would never analyze it. These are also ordinary sources
	// (list them in Sources too); this only tags the flavor.
	RequestObjectSources []string `yaml:"request_object_sources"`

	// Sinks are taint-sink patterns; each is a bare glob string or a `{sink, when}`
	// mapping adding a dynamic guard (see Sink). A pattern may append a "#i[,j...]"
	// suffix limiting the sink to LOGICAL (receiver-excluded) argument indices — so
	// for "go:...Query#0" only arg 0 is an injection point and a bound-parameter
	// query `db.Query("... = ?", taintedParam)` is correctly NOT flagged.
	Sinks []Sink `yaml:"sinks"`

	// When is the rule's DEFAULT dynamic guard: a sink (or dangerous-call callee)
	// that declares no `when:` of its own inherits this one. A guard like
	// `not hostFixed()` is rule POLICY; declaring it once here stops a sink added
	// later from silently opting out. An entry's own `when:` always wins, so
	// `when: 'true'` on one sink is the per-sink opt-out. Inheritance is applied
	// where the guard is resolved (effectiveWhen), so a sink merged in from a
	// fragment inherits it too.
	When string `yaml:"when"`

	Propagators []string `yaml:"propagators"` // callees that pass taint arg->result (e.g. fmt.Sprintf)

	// Kind selects the rule's evaluation model:
	//   ""/"taint"        the default source->sink dataflow rule.
	//   "dangerous-call"  a non-dataflow, call-site-syntactic check: any call to a
	//                     Callee glob is a finding, optionally gated on a constant
	//                     string argument — for zero-noise categories like weak
	//                     crypto and insecure randomness that need no taint.
	//   "secret"          a non-dataflow, non-call check: Matches is run over every
	//                     string CONSTANT in the IR and over the lines of textual
	//                     config files, so a credential is caught wherever it is
	//                     written. No callee is involved at all.
	Kind string `yaml:"kind"`

	// Matches is a kind: secret rule's detector — a Go regexp run against string
	// constants and config-file lines. Keep it specific (a fixed prefix or a
	// structural marker) rather than entropy-based: a CI gate cannot afford the
	// noise. Ignored by other kinds; see MatchesRe.
	Matches string `yaml:"matches"`

	// Callees are the dangerous-call patterns for a kind: dangerous-call rule —
	// each a bare glob string or a `{callee, when}` mapping adding a guard (see Callee).
	Callees []Callee `yaml:"callees"`

	// ConstArg optionally restricts a dangerous-call match to calls whose constant
	// string argument at the LOGICAL index Index matches the Matches regexp — e.g.
	// the "MD5" literal in MessageDigest.getInstance("MD5"). Nil means any call to
	// a Callee fires regardless of arguments.
	ConstArg *ConstArg `yaml:"const_arg"`

	// Validators are guard/barrier callees: a boolean-returning check (an
	// allowlist test, a regexp match, a path-containment predicate like
	// filepath.IsLocal) that, when it dominates the branch leading to a sink,
	// clears the checked value's taint on that path. Unlike a Sanitizer — which
	// transforms a value and returns a clean result — a Validator returns a bool
	// and leaves the value unchanged, neutralizing the finding by controlling
	// which path reaches the sink. Matched by canonical-FQN glob, like sinks.
	Validators []string `yaml:"validators"`
	// contains filtered or unexported fields
}

type RuleSet struct {
	Rules []Rule `yaml:"rules"`

	// DefaultPropagators are taint-preserving library transforms that apply to
	// EVERY rule on top of its own Propagators. The loader fills this from the
	// `_default-propagators.yaml` fragment; Compile hands it to each rule, so the
	// engine never has to know defaults exist. Not from this document's YAML.
	DefaultPropagators []string `yaml:"-"`
	// contains filtered or unexported fields
}

type Severity string

type Sink struct {
	Pattern string
	When    string
}