Crate taudit_api 

taudit-api — stable wire types for JSON / SARIF / CloudEvents

This crate owns every Rust type that appears in taudit’s emitted output (JSON taudit-report.schema.json, JSON authority-graph.v1.json, SARIF result.message.text and result.ruleId, CloudEvents tauditruleid / tauditfindingfingerprint extension attributes).

Stability promise (0.x)

While at 0.x:

• Additive changes (new variants, new fields) MAY ship in any minor bump. Consumers should pin a minor (taudit-api = "0.1") and review on each upgrade.
• Breaking changes (renamed fields, removed variants, changed serde representations) trigger a 0.{N+1} minor bump and a CHANGELOG migration note.

At 1.0, the promise lifts: only 2.0 permits breaking changes; all 1.x minor bumps are additive.

Use in downstream tooling

Downstream consumers (tsign, axiom, custom SIEM integrations, Backstage plugins) should depend on taudit-api directly rather than taudit-core. taudit-core is workspace-internal and may break between minors; taudit-api is the public contract.

See ADR 0001 (graph as product) and ADR 0004 (prereleases publish to crates.io).

Structs

AuthorityEdgeSummary

Abbreviated authority context for HasAccessTo → identity edges in JSON exports (ADR 0002 Phase 2). Copied from the target identity’s trust zone and selected metadata keys so consumers need not reverse-engineer raw META_* strings for common questions. Omitted on edges where absent.

Edge

A directed edge in the authority graph.

Finding

A finding is a concrete, actionable authority issue.

FindingExtras

Optional finding metadata. Lives on every Finding via #[serde(flatten)] so consumers see the fields at the top of the finding object — same place they’d appear if declared inline on Finding. Default-constructed extras serialize to nothing (all Option::None and empty Vecs skip-serialize), so existing snapshots remain byte-stable until a rule populates a field.

Node

A node in the authority graph.

ParamSpec

Pipeline-level parameter declaration captured from a top-level parameters: block. Used by rules that need to reason about whether caller-supplied parameter values are constrained (values: allowlist) or free-form (no allowlist on a string parameter — shell-injection risk).

PipelineSource

Where the pipeline definition came from.

PropagationPath

A path that authority took through the graph. The path is the product — it’s what makes findings persuasive.

Enums

AuthorityCompleteness

How complete is this authority graph? Parsers set this based on whether they could fully resolve all authority relationships in the pipeline YAML.

EdgeKind

Edge semantics model authority/data flow — not syntactic YAML relations. Design test: “Can authority propagate along this edge?”

FindingCategory

MVP categories (1-5) are derivable from pipeline YAML alone. Stretch categories (6-9) need heuristics or metadata enrichment.

FindingSource

Provenance of a finding — distinguishes findings emitted by built-in taudit rules from findings emitted by user-loaded custom invariant YAML (--invariants-dir). Custom rules can emit arbitrarily-worded findings at any severity, so an operator piping output into a JIRA workflow or SARIF upload needs a non-spoofable signal of which file the rule came from. Serializes as "built-in" (string) for built-in findings and {"custom": "<path>"} for custom-rule findings — see docs/finding-fingerprint.md for the contract.

FixEffort

Coarse-grained remediation effort. Surfaces in JSON time_to_fix and SARIF properties.timeToFix so triage dashboards can sort by severity * effort.

GapKind

The category of reason why a graph is partial.

IdentityScope

How broad is an identity’s scope? Classifies the risk surface of tokens, service principals, and OIDC identities.

NodeKind

Semantic kind of a graph node.

Recommendation

Routing: scope findings -> TsafeRemediation; isolation findings -> CellosRemediation.

Severity

Severity of a finding. Ordered by rank() (Critical = most severe).

TrustZone

Trust classification. Explicit on every node — not inferred from kind.

Constants

AUTHORITY_EDGE_SUMMARY_FIELD_MAX

Maximum characters per summary string field on AuthorityEdgeSummary.

META_ADD_SPN_TO_ENV

Marks a Step task that runs with addSpnToEnvironment: true, exposing the federated SPN (idToken / servicePrincipalKey / servicePrincipalId / tenantId) to the inline script body via environment variables.

META_ATTESTS

Marks a Step that performs cryptographic provenance attestation (e.g. actions/attest-build-provenance).

META_CACHE_KEY

Marks a Step that calls actions/cache (or actions/cache/save / actions/cache/restore). The cell value is the raw key: input from the step’s with: block. Consumed by pr_specific_cache_key_in_default_branch_consumer to detect PR-derived cache keys (head_ref, head.ref, actor) that a default-branch run can later restore — classic cache poisoning.

META_CHECKOUT_REF

Step-level metadata: the value passed to actions/checkout’s with.ref input (verbatim, including any ${{ … }} expressions). Stamped only on actions/checkout steps that supply a ref:. Consumed by manual_dispatch_input_to_url_or_command.

META_CHECKOUT_SELF

Marks a Step that performs a checkout: self (ADO) or default actions/checkout on a PR context.

META_CLI_FLAG_EXPOSED

Marks a Secret node whose value is interpolated into a CLI flag argument (e.g. -var "key=$(SECRET)"). CLI flag values appear in pipeline log output even when ADO secret masking is active, because the command string is logged before masking runs and Terraform itself logs -var values.

META_CONDITION

Step-level metadata: the AND-joined chain of condition: expressions that gate this step’s runtime execution (stage condition, then job condition, then step condition, joined with AND). Stamped by parsers that surface runtime gating expressions — currently the ADO parser (stage / job / step condition:). Presence of this key means the step is NOT unconditionally reachable on every trigger; the runtime evaluator decides via expression (e.g. eq(variables['Build.SourceBranch'], 'refs/heads/main')). Consumed by apply_compensating_controls to downgrade severity on findings whose firing step is gated behind a conditional.

META_CONTAINER

Marks an Image node as a job container (not a uses: action).

META_DEPENDS_ON

Step-level metadata: comma-joined list of upstream stage / job names this step’s container declared via a non-default dependsOn: value. Default ADO behaviour (“depends on the previous job/stage”) is NOT stamped — only explicit overrides. Currently a parser-side hook for future cross-job taint rules; no consumer rule exists yet.

META_DIGEST

Records the digest of a pinned action / image reference.

META_DISPATCH_INPUTS

Graph-level metadata: comma-joined list of workflow_dispatch.inputs.* names declared by the workflow. Empty / absent if the workflow has no workflow_dispatch trigger. Consumed by manual_dispatch_input_to_url_or_command to taint-track input flow into command lines, URLs, and actions/checkout refs.

META_DOTENV_FILE

Records the GitLab artifacts.reports.dotenv: file path for a Step. When set, the file’s KEY=value lines are silently exported as pipeline variables for every downstream job that consumes this job via needs: or dependencies:. Consumed by dotenv_artifact_flows_to_privileged_deployment.

META_DOWNLOADS_ARTIFACT

Marks a Step that downloads a workflow artifact (typically actions/download-artifact or dawidd6/action-download-artifact). In workflow_run-triggered consumers, the originating run’s artifacts were produced from PR context — the consumer must treat their content as untrusted input even when the consumer itself runs with elevated perms.

META_ENVIRONMENT_NAME

Records the deployment environment name on a Step (e.g. GitLab environment.name: / GHA environment:). Used by rules that gate on production-like environment names.

META_ENVIRONMENT_URL

Records a Step’s environment:url: value verbatim. Stamped by the GitLab parser when the job declares an environment: mapping with a url: field. Consumed by untrusted_ci_var_in_shell_interpolation because environment:url: is rendered by the GitLab UI and any predefined-CI-var interpolated into it is a stored-XSS / open-redirect sink.

META_ENV_APPROVAL

Marks a Step that belongs to an ADO deployment job whose environment: is configured with required approvals — a manual gate that breaks automatic authority propagation. Findings whose path crosses such a node have their severity reduced by one step (Critical → High → Medium → Low).

META_ENV_GATE_WRITES_SECRET_VALUE

Marks a Step that writes a $(secretRef) value to the env gate. Co-set with META_WRITES_ENV_GATE when the written VALUE contains an ADO $(VAR) expression, distinguishing secret-exfiltration from plain-integer or literal env-gate writes.

META_FORK_CHECK

Marks a Step in a GHA workflow as carrying an if: condition that references the standard fork-check pattern (github.event.pull_request.head.repo.fork == false or the equivalent head.repo.full_name == github.repository). Stamped by the GHA parser so rules can credit the step with the compensating control without re-parsing the YAML expression. Bool stored as "true".

META_GHA_ACTION

Step-level metadata: normalized GitHub Actions uses: action name without its @ref suffix, for example docker/login-action. Set only by the GHA parser on uses: steps.

META_GHA_WITH_INPUTS

Step-level metadata: sorted scalar with: inputs for a GHA uses: step, encoded as newline-delimited key=value records. Non-scalar inputs are omitted. Consumed by action-specific rules that need precision controls such as mask-password: false or skip_install: true.

META_GITLAB_ALLOW_FAILURE

Marks a Step (GitLab job) declared with allow_failure: true. Used by security_job_silently_skipped to detect scanner jobs that pass silently.

META_GITLAB_CACHE_KEY

Records the literal cache.key: value declared on a GitLab job (or the empty string if no cache is declared). Consumed by cache_key_crosses_trust_boundary to detect cross-trust cache keys.

META_GITLAB_CACHE_POLICY

Records the cache.policy: value declared on a GitLab job (pull / push / pull-push / pull_push). When absent, the GitLab runtime default is pull-push. Consumed by cache_key_crosses_trust_boundary.

META_GITLAB_DIND_SERVICE

Marks a Step (GitLab job) that declares one or more services: entries matching docker:*-dind or docker:dind. Combined with secret-bearing HasAccessTo edges it indicates a runtime sandbox-escape primitive — any inline build step can docker run -v /:/host from inside dind.

META_GITLAB_EXTENDS

Records the comma-joined list of extends: template names a GitLab job inherits from. Used by scanner-name pattern matching in security_job_silently_skipped because GitLab security templates are usually consumed via extends: rather than by job-name match.

META_GITLAB_INCLUDES

Graph-level metadata: JSON-encoded array of include: entries declared by a GitLab CI pipeline. Each entry is an object with fields:

META_GITLAB_TRIGGER_KIND

Marks a Step (GitLab job) that defines a trigger: block (downstream / child pipeline). Value is "static" for a fixed downstream project: or include: of in-tree YAML, and "dynamic" when the include source is an artifact: (dynamic child pipelines — code-injection sink).

META_IDENTITY_SCOPE

Records the inferred breadth of an identity’s scope (broad / constrained / unknown).

META_IMPLICIT

Marks an Identity node as implicitly injected by the platform (e.g. ADO System.AccessToken). Implicit tokens are structurally accessible to all tasks by platform design — exposure to untrusted steps is Info-level (structural) rather than Critical (misconfiguration).

META_INFERRED

Marks a metadata value that the parser inferred rather than read literally.

META_INTERACTIVE_DEBUG

Marks a Step that uses an interactive debug action (mxschmitt/action-tmate, lhotari/action-upterm, actions/tmate, etc.). The cell value is the action reference (e.g. mxschmitt/action-tmate@v3). A successful debug session gives the operator an external SSH endpoint with the runner’s full environment loaded — every secret in scope, the checked-out HEAD, and write access to whatever the GITHUB_TOKEN holds.

META_INTERPRETS_ARTIFACT

Marks a Step whose body interprets artifact (or other untrusted file) content into a privileged sink — unzip/tar -x, cat/jq piping into >> $GITHUB_ENV/>> $GITHUB_OUTPUT, eval, posting to a PR comment via actions/github-script body:/issue_body:, or evaluating extracted text. Combined with META_DOWNLOADS_ARTIFACT upstream in the same job and a workflow_run/pull_request_target trigger this is the classic mypy_primer / coverage-comment artifact-RCE pattern.

META_JOB_NAME

Records the parent job name on every Step node, enabling per-job subgraph filtering (e.g. taudit map --job build) and downstream consumers that need to attribute steps back to their containing job. Set by both the GHA and ADO parsers on every Step they create within a job’s scope.

META_JOB_OUTPUTS

Graph-level metadata: pipe-delimited list of <job>\t<name>\t<source> records, one per jobs.<id>.outputs.<name>. Records are joined with |, fields within a record with \t. source is one of secret (value reads secrets.*), oidc (value references steps.*.outputs.* from a step that holds an OIDC identity), step_output (any other steps.*.outputs.*), or literal. Plain-text rather than JSON to keep the parser crate free of serde_json. Consumed by sensitive_value_in_job_output.

META_NEEDS

Records, on a Step, the upstream job names this step consumes via GitLab needs: or dependencies:. Comma-separated job names. Used to build dotenv-flow dependency chains across stages.

META_NO_WORKFLOW_PERMISSIONS

Graph-level metadata: marks a GitHub Actions workflow as having NO top-level permissions: block declared. Set by the GHA parser when workflow.permissions is absent so rules can detect the negative-space “no permissions block at all” pattern (which leaves GITHUB_TOKEN at its broad platform default — contents: write, packages: write, etc.).

META_OIDC

Marks an Identity node as OIDC-capable (permissions: id-token: write).

META_OIDC_AUDIENCE

Records the OIDC audience (aud:) value of an id_tokens: entry on an Identity node. GitLab CI emits one Identity per id_tokens: key; the audience is what trades for downstream cloud creds (Vault path, AWS role, etc), so audience reuse across MR-context and protected-context jobs is the precise privilege-overscope signal. Set by the GitLab parser.

META_OIDC_AUDIENCES

Records the comma-joined list of id_tokens.aud: values when GitLab CI declares the audience as a YAML sequence (multi-cloud broker — strongest over-scoping signal). When set, the legacy META_OIDC_AUDIENCE field holds the same comma-joined string for backward compatibility, and this field is the explicit “this was a list” marker. Set by the GitLab parser only on the multi-aud path; absent for scalar aud: values.

META_PERMISSIONS

Records the permissions: block scoped to an Identity / Step node.

META_PLATFORM

Graph-level metadata: identifies the source platform of the parsed pipeline. Set by every parser to its platform() value ("github-actions", "azure-devops", "gitlab"). Allows platform-scoped rules to gate their detection without parsing the source file path.

META_READS_ENV

Marks a Step that reads from the runner-managed environment via an env.<NAME> template reference — ${{ env.X }} in a with: value, inline script body, or step env: mapping. Distinct from secrets.X references (which produce a HasAccessTo edge to a Secret node) — env.X references can be sourced from the ambient runner environment, including values laundered through $GITHUB_ENV by an earlier step. Stamped by the GHA parser so secret_via_env_gate_to_untrusted_consumer can find the gate-laundering chain that the explicit-secret rules miss.

META_REPOSITORIES

Graph-level metadata: JSON-encoded array of resources.repositories[] entries declared by the pipeline. Each entry is an object with fields alias, repo_type, name, optional ref, and used (true when the alias is referenced via template: x@alias, extends: x@alias, or checkout: alias somewhere in the same pipeline file). Set by the ADO parser; consumed by template_extends_unpinned_branch.

META_RULES_PROTECTED_ONLY

Marks a GitLab CI job (Step node) whose rules: or only: clause restricts execution to protected branches — either via an explicit if: $CI_COMMIT_REF_PROTECTED == "true" rule, an if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH rule, or an only: [main, ...] allowlist of platform-protected refs. Set by the GitLab parser. Absence on a deployment job is a control gap.

META_SCRIPT_BODY

Records the raw inline script body of a Step (the text from script: / bash: / powershell: / pwsh: / run: / task inputs.script / inputs.Inline / inputs.inlineScript). Stamped by parsers when the step has an inline script. Consumed by script-aware rules: vm_remote_exec_via_pipeline_secret, short_lived_sas_in_command_line, secret_to_inline_script_env_export, secret_materialised_to_workspace_file, keyvault_secret_to_plaintext, add_spn_with_inline_script, parameter_interpolation_into_shell. Stored verbatim — rules apply their own pattern matching.

META_SECRETS_INHERIT

Marks the synthetic Step node created for a job that delegates to a reusable workflow with secrets: inherit. The whole secret bag forwards to the callee regardless of what the callee actually consumes — when the caller is fired by an attacker-controllable trigger this is a wide-open exfiltration path. Set on the synthetic step node by the GHA parser.

META_SELF_HOSTED

Marks an Image node as a self-hosted agent pool (pool.name on ADO; runs-on: self-hosted on GHA).

META_SERVICE_CONNECTION

Marks an Identity node as an ADO service connection.

META_SERVICE_CONNECTION_NAME

Records the name of the ADO service connection a step uses (the value of inputs.azureSubscription / inputs.connectedServiceName*). Set on the Step node itself (in addition to the Identity node it links to) so rules can pattern-match on the connection name without traversing edges.

META_SETVARIABLE_ADO

Marks a Step that came from an ADO ##vso[task.setvariable] call (as opposed to a GHA >> $GITHUB_ENV redirect). Used to distinguish the two env-gate write patterns so BUG-4 suppression only applies to ADO plain-value writes.

META_TERRAFORM_AUTO_APPROVE

Marks a Step as performing terraform apply ... -auto-approve (either via an inline script or via a TerraformCLI / TerraformTask task with command: apply and commandOptions containing auto-approve).

META_TRIGGER

Graph-level metadata: identifies the trigger type (e.g. pull_request_target, pr).

META_TRIGGERS

Graph-level metadata: comma-joined list of every entry under on: (e.g. pull_request_target,issue_comment,workflow_run). Distinct from META_TRIGGER (singular) which is set only for pull_request_target / ADO pr to preserve the existing trigger_context_mismatch contract. Consumers of this list (e.g. risky_trigger_with_authority) must split on , and treat each token as a trigger name.

META_VARIABLE_GROUP

Marks a Secret node sourced from an ADO variable group (vs inline pipeline variable).

META_WORKSPACE_CLEAN

Marks an Image node (self-hosted agent pool) as having workspace isolation configured (workspace: { clean: all } or workspace: { clean: true } in ADO). When present, the agent workspace is wiped between runs, mitigating workspace poisoning attacks where a PR build leaves malicious files for the next privileged pipeline run. Absence of this key on a self-hosted Image node is the signal for shared_self_hosted_pool_no_isolation.

META_WRITES_ENV_GATE

Marks a Step that writes to the environment gate ($GITHUB_ENV, ADO ##vso[task.setvariable]).

Type Aliases

EdgeId

Unique identifier for an edge in the authority graph.

NodeId

Unique identifier for a node in the authority graph.