gh-aw-threat-detection

Threat Detection component for GitHub Agentic Workflows. Analyzes AI agent output for security threats including prompt injection, secret leaks, and malicious patches.

Contents

• Quick Start
• Overview
• Guardrails and Security Considerations
• Usage
• Stage Status and Decisions
• Release Asset Setup
• Development
• Architecture
• Integration with gh-aw
• Specification
• Contributing
• Support
• Code of Conduct
• Security
• License

Quick Start

Build the CLI and run it against an artifacts directory:

make build
./bin/threat-detect /path/to/artifacts

Run tests locally:

make test

Overview

This tool runs as a standalone binary that analyzes artifacts produced by AI agents before safe outputs are permitted. It supports multiple AI engines (Copilot, Claude, Codex) for detection analysis.

Guardrails and Security Considerations

This project is designed to help reduce risk when running AI agent workflows by inspecting generated artifacts before they are accepted as safe output. Detection is advisory and should be combined with defense-in-depth controls such as least-privilege permissions, human review, and repository protections.

Do not treat a "safe" result as a security guarantee. Use the output as one signal in a broader security review process.

Usage

CLI

threat-detect [flags] <artifacts-dir>

Flags:

• --engine — AI engine to use (copilot, claude, codex). Default: copilot
• --model — Model override for the engine. When unset, the detector resolves the model from GH_AW_MODEL_DETECTION_{COPILOT,CLAUDE,CODEX}, then the engine CLI's native model env var (COPILOT_MODEL, ANTHROPIC_MODEL). The value is forwarded to the engine CLI verbatim and may be a model alias (gh-aw defaults the detection model to the detection alias when none is configured); aliases are resolved by the AWF API proxy, not by the detector
• --prompt-template — Path to custom prompt template
• --workflow-name — Workflow name for the prompt. Overrides WORKFLOW_NAME
• --workflow-description — Workflow description for the prompt. Overrides WORKFLOW_DESCRIPTION
• --custom-prompt — Additional detection instructions appended to the prompt. Overrides CUSTOM_PROMPT
• --custom-prompt-file — Path to a file with additional detection instructions. Takes precedence over --custom-prompt and CUSTOM_PROMPT
• --output — Path to write JSON result (defaults to stdout)
• --log-file — Path to write structured JSONL run logs (one JSON object per line). Env: THREAT_DETECTION_LOG_FILE; defaults to detection-runlog.jsonl beside --output
• --step-summary — Path to append the artifact inventory table and the rendered prompt (engine/model/retries plus the prompt actually sent, including the resolved prompt-analysis section, as a collapsible block) in the job step summary. Defaults to GITHUB_STEP_SUMMARY. Best effort: a failed write warns and never fails detection
• --retries — Retries for malformed detection outputs. Default: 1 (env: THREAT_DETECTION_RETRIES)
• --version — Print version and exit

threat-detect runs a single agentic CLI engine pass. The engine reports its verdict in-session by invoking the threat_detection_result tool, which writes a strict JSON object matching the result contract to an out-of-band result sink; the detector cancels the engine subprocess as soon as a valid result is written. The verdict is read exclusively from that sink; if no sink result is produced, a one-shot self-correction prompt is retried, and retry exhaustion is treated as an infrastructure error.

In-session result reporting (threat_detection_result)

On the agentic CLI engine path (copilot, claude, codex), the detector provisions a threat_detection_result command on the model's PATH and sets THREAT_DETECTION_RESULT_FILE to a private sink file before each engine invocation. The model reports its verdict by running the command exactly once:

threat_detection_result --prompt-injection <true|false> --secret-leak <true|false> --malicious-patch <true|false> --reason "..."

The command validates the input synchronously: on bad input it prints THREAT_DETECTION_RESULT_ERROR: and exits non-zero without recording anything, so the model can correct it in-session; on valid input it atomically records the canonical JSON verdict to the sink (first valid write wins, idempotent) and prints THREAT_DETECTION_RESULT_RECORDED:. As soon as a valid verdict is recorded, the detector cancels the engine subprocess (early termination), eliminating dead-spiral latency and cost. The detector reads the verdict exclusively from the sink; it does not scrape the engine transcript.

Exit codes:

• 0 — Safe (no threats detected)
• 1 — Threat detected
• 2 — Infrastructure/configuration error

The detector also emits a single machine-readable status line to stderr at the end of every detection run: THREAT_DETECTION_STATUS: reason=<reason> exit=<code>. (Informational modes that exit before running detection — --help and --version — emit no status line, so callers should not treat its absence in those modes as a malfunction.) The reason distinguishes outcomes that share exit code 2 — notably invalid_report_exhausted (the engine ran but the model never recorded a valid verdict) from engine_error, config_error, and cancelled. Integration wrappers use this to decide the detection step's success/failure outcome without being stricter than gh-aw: a recorded verdict (exit 0/1) and an invalid_report_exhausted outcome do not fail the step, so warn-mode workflows proceed exactly as they do under gh-aw's native engine (which treats a missing verdict as a recoverable parse_error). Only genuine engine/config failures surface as a step failure. See spec TD-21a.

JSONL run logs (--log-file)

Pass --log-file <path> (or set THREAT_DETECTION_LOG_FILE) to choose where to record a structured trace of the run. When --output is set without an explicit log path, the detector writes detection-runlog.jsonl in the output file's directory. The log uses JSON Lines: one JSON object per line, created fresh (truncating any existing file) with 0600 permissions. Every record starts with time (RFC 3339), level (info/error), and event, followed by event-specific fields. Emitted events include run_start, artifacts_loaded, artifact_degraded, prompt_built, attempt_start/attempt_recorded/attempt_no_verdict, verdict, detection_failed, and a terminal status record carrying the same reason and exit code as the stderr status line. The verdict JSON contract (--output) is unchanged; the log file is an additive observability sink. --log-file and --output must not resolve to the same file — a collision is rejected as a configuration error to avoid corrupting both outputs.

{"time":"2026-07-14T18:00:00Z","level":"info","event":"run_start","engine":"copilot","model":"","retries":1,"version":"1.2.3"}
{"time":"2026-07-14T18:00:03Z","level":"info","event":"verdict","has_threats":false,"malicious_patch":false,"prompt_injection":false,"reasons":[],"secret_leak":false}
{"time":"2026-07-14T18:00:03Z","level":"info","event":"status","exit":0,"reason":"result_recorded"}

Concluding a run (conclude)

In gh-aw-compiled workflows the detector runs inside the AWF sandbox, where the verdict cannot reach the host over stdout. Instead, detection writes its structured result to detection_result.json in a read-write mount, and a host-side step reads it back with the conclude subcommand:

threat-detect conclude --result-file /tmp/gh-aw/threat-detection/detection_result.json

conclude reproduces the gh-aw job-output contract — it writes conclusion, reason, and success to GITHUB_OUTPUT and exports GH_AW_DETECTION_CONCLUSION and GH_AW_DETECTION_REASON to GITHUB_ENV. It reads these environment inputs:

• RUN_DETECTION — when not "true", the verdict is skipped/success
• GH_AW_DETECTION_CONTINUE_ON_ERROR — anything other than "false" (compared case-insensitively) is warn mode
• DETECTION_AGENTIC_EXECUTION_OUTCOME — "failure" makes agent_failure/parse_error hard-fail

A malformed (readable but unparseable) result file always reports parse_error, and detected threats report threat_detected. When the result file is missing, conclude consults the detection run's captured log (--detection-log <path>, default <result-file-dir>/detection.log) for the terminal THREAT_DETECTION_STATUS: reason=<reason> exit=<code> line and maps it onto the host-side reason:

status reason	host-side reason
invalid_report_exhausted	parse_error
output_write_error	parse_error
engine_error	agent_failure
cancelled	agent_failure
config_error	agent_failure
absent / unrecognized / log unreadable	agent_failure ("Detection result file not found at: ")

conclude also accepts --step-summary <path> (defaulting to GITHUB_STEP_SUMMARY) to append a collapsible verdict block to the job step summary: per-field booleans (prompt_injection, secret_leak, malicious_patch), the reasons list, the resolved conclusion (success/warning/failure/skipped), and the reason code.

Tooling failures are rendered distinctly from real security findings, matching gh-aw's own output so automated scanners can tell them apart:

host-side reason	marker	block title
threat_detected	<!-- gh-aw-threat-detected -->	Threat Detection Verdict
agent_failure, parse_error	<!-- gh-aw-threat-engine-error -->	Threat Detection Engine Failure
absent (success, skipped)	none	Threat Detection Verdict

An engine failure block states plainly that the analysis engine could not complete and that this is a tooling failure, not a security finding; the same line is echoed into the job log.

conclude writes a verbose, self-contained diagnostic section to the job log: banners framing the section, the environment inputs and resolved paths, and the per-field verdict breakdown (prompt_injection/secret_leak/malicious_patch) with an indexed reasons list. When the result file is missing or unusable it also prints a recursive listing of the result directory plus detection-log statistics and every line carrying a THREAT_DETECTION_STATUS:/THREAT_DETECTION_RESULT: marker, so a failed run can be diagnosed without downloading artifacts.

Additional flags:

• --detection-log <path> — the detection run's captured log (see the reason table above); it is also the source of the diagnostic log statistics and marker lines. It is consulted for the terminal status reason but never parsed for a verdict.
• --log-file <path> — mirror the conclusion into a JSONL run log (env: THREAT_DETECTION_LOG_FILE), emitting conclude_start, conclude_verdict, conclude_directory_listing, conclude_detection_log, and conclude_outcome events. It must not resolve to the same file as --result-file or the detection log — the log is opened truncating, so a collision would destroy the input it is meant to describe. Collisions and unopenable log paths are configuration errors that fail the step.

Diagnostic output is bounded so a pathological run cannot flood the job log, and truncation is always labelled rather than passed off as a complete reading. Untrusted values (model-authored reasons, artifact filenames, detection-log lines) have control characters escaped so each stays on one line and cannot inject a workflow command into the host job log.

AI Credits and Token Usage

The threat-detection pass is a separate agentic engine invocation from the main agentic run it guards. It builds its own prompt and runs the selected engine (copilot, claude, or codex) once, so it consumes AI credits/tokens independently — in addition to (not shared with) the workflow's primary run. The cost is billed to the same engine account/credentials used for detection (COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, or OPENAI_API_KEY).

Is there a separate token cap for the detection job? threat-detect itself enforces no credit budget — it has no notion of AI credits and does not read or count tokens. On the path gh-aw actually ships, the cap is enforced around the detector, not inside it:

• AWF API-proxy maxAiCredits — when threat-detect runs under the Agentic Workflow Firewall with the API proxy and token steering enabled (apiProxy.enabled + enableTokenSteering), the compiled detection step sets apiProxy.maxAiCredits from max-ai-credits (default 400, or vars.GH_AW_DEFAULT_DETECTION_MAX_AI_CREDITS). The proxy enforces this as a cumulative per-run credit counter, so it bounds the whole pass — including --retries, not just the first attempt. This is the enforcement mechanism for the external detector path; there is no threat-detect-side budget flag to plumb.
• Early termination — as soon as the model records a verdict through the threat_detection_result tool, the detector cancels the engine subprocess, so the pass stops at the first valid verdict instead of running to the engine's own limit.
• max-turns — gh-aw's threat-detection.engine configuration accepts a max-turns value that bounds the agentic loop (see the spec, TD-14).

A plain, non-AWF ./bin/threat-detect invocation (no API proxy) has no credit cap and produces no proxy token log. It is not bounded by max-turns either — that is a gh-aw workflow setting, and the CLI neither accepts it nor forwards one to the engine. Only early termination (cancelling the engine as soon as a verdict is recorded) and the engine's own built-in limits bound its cost.

Where does the aic (AI credits) figure come from? Not from threat-detect. On the AWF path the proxy records every steered model request to token-usage.jsonl under …/sandbox/firewall/**/api-proxy-logs/, and gh-aw's parse_token_usage.cjs aggregates those records into the detection job's aic output and agent_usage.json. That figure is therefore independent of threat-detect's engine flags and of any diagnostics it interleaves into detection.log; the detector's stdout is not the source of truth for credits.

For authoritative billing, use the AWF proxy token log / agent_usage.json (or the engine's own logs, uploaded as the detection log artifact) together with gh-aw's logs tooling.

Released binary

The threat-detect binary is published as GitHub Release assets for Linux and macOS on amd64 and arm64 alongside a shared checksums.txt. Download the asset matching your runner platform and run it directly:

# Pick the asset for your operating system and architecture.
case "$(uname -s)/$(uname -m)" in
  Linux/x86_64|Linux/amd64)  asset=threat-detect-linux-amd64 ;;
  Linux/aarch64|Linux/arm64) asset=threat-detect-linux-arm64 ;;
  Darwin/x86_64)             asset=threat-detect-darwin-x64 ;;
  Darwin/arm64)              asset=threat-detect-darwin-arm64 ;;
  *) echo "unsupported platform" >&2; exit 1 ;;
esac
gh release download --repo github/gh-aw-threat-detection \
  --pattern "$asset" --pattern checksums.txt
awk -v asset="$asset" '$2 == asset' checksums.txt |
  if command -v sha256sum >/dev/null; then sha256sum --check; else shasum -a 256 --check; fi
install -m 0755 "$asset" ./threat-detect
./threat-detect /path/to/artifacts

Omitting a tag downloads the latest stable (promoted) release. Production AI-backed detection requires the selected engine CLI and its authentication to be available on the runner where the binary runs.

The macOS binaries are not code-signed or notarized. The gh-aw installer checksum-verifies CI downloads before execution. Browser downloads may be quarantined by Gatekeeper; prefer the installer, or verify the checksum before removing quarantine.

Input (Artifacts Directory)

<artifacts-dir>/
├── aw-prompts/
│   ├── prompt.txt          # Expanded workflow prompt file
│   ├── prompt-template.txt # Pre-expansion prompt template
│   └── prompt-import-tree.json # Runtime-import provenance
├── agent_output.json       # Agent structured output
├── aw_info.json            # Bounded activation context (optional, consumed as untrusted)
├── aw-*.patch              # Git format-patch files (optional)
├── aw-*.bundle             # Git bundle files (optional)
├── experiments/            # Experiment assignment/state files (optional, inventoried only)
└── comment-memory/         # Agent comment memory (optional, inventoried only)
    └── *.md

Integrated hosts must stage all three files under aw-prompts/. Direct callers may omit the template or import tree, but the detector emits an ERR_VALIDATION warning because trusted-vs-untrusted prompt analysis is then degraded. Empty or unreadable analysis files produce the same warning.

aw-prompts/prompt.txt and agent_output.json are the required detection inputs, as is at least one aw-*.patch / aw-*.bundle when the host sets HAS_PATCH=true. When one of them is missing, empty, or unusable the detector follows the host's continue-on-error policy: by default it warns and analyzes whatever was staged, and with GH_AW_DETECTION_CONTINUE_ON_ERROR=false it reports each finding as an error and exits 2 (config_error) before the engine runs. Findings about other artifacts stay advisory warnings in both modes.

Every file below the artifacts directory is recorded with its size and consumed status in the JSONL artifacts_loaded event and, when a step summary path is configured (--step-summary, defaulting to GITHUB_STEP_SUMMARY), in the Actions step summary. A step summary that cannot be written is reported as a warning and never fails detection. Only an allowlisted, size-bounded subset of aw_info.json is added to the detection prompt, and all of its values are explicitly treated as untrusted runtime data.

Output (JSON)

{
  "prompt_injection": false,
  "secret_leak": false,
  "malicious_patch": false,
  "reasons": []
}

Replay workflow

Maintainers can manually run Replay Threat Detection from the Actions tab to rerun detection against artifacts from a prior workflow run. Provide the source repository and run ID; the workflow downloads the agent, activation, optional experiment, and optional original detection artifacts, normalizes them into the CLI input contract above, runs threat-detect, and uploads a sanitized replay-detection-<run_id> artifact with the manifest, file inventory, free-form replay log, replay result, and original-result comparison. Detectors that support structured logging also produce detection-runlog.jsonl; when available, the source run's structured log is retained separately as original-detection-runlog.jsonl.

Replay uses the dispatching repository's GITHUB_TOKEN; no extra replay token is required. The selected source run must be accessible to that token.

Common dispatch examples:

• Current checkout, direct CLI replay: set run_id, leave detector_source=current, engine=copilot, and use_awf=false.
• Released detector replay: set detector_source=release and detector_ref to a release tag such as v0.0.2. The workflow downloads the release asset matching the runner architecture (threat-detect-linux-amd64 or threat-detect-linux-arm64) and runs it on the host so the selected engine CLI can be installed there.
• Model comparison: set model to the engine-specific model name to pass through --model.
• Additional detection instructions: set custom_prompt; it is passed as CUSTOM_PROMPT and appended to the default detector prompt.
• AWF mode: set use_awf=true only on a runner image that already provides the awf CLI. Direct mode is the default.

The run_attempt input is only safe for the latest attempt of a source run because GitHub artifact downloads are not attempt-scoped. The workflow fails with a clear error if an older attempt is requested.

Stage Status and Decisions

The extraction staging model is:

• Stage 1: standalone repository
• Stage 2: published release-asset binary
• Stage 3: github/gh-aw integration

Stage 1 is functionally represented in this repository. The standalone Go CLI, artifact reader, prompt builder, result parser, engine abstraction, W3C-style specification, unit tests, CI, and release workflow are present. Remaining work involves integration with github/gh-aw and production hardening in Stage 2/3, not additional JavaScript porting in this repository.

Decisions for the unresolved extraction questions:

• JavaScript scripts: detection setup and result parsing are implemented in Go here; the old GitHub Actions JavaScript scripts should not be needed once gh-aw switches to the released-binary contract.
• Engine CLIs: do not bundle Copilot, Claude, or Codex CLIs into the detector binary. The detector invokes the selected engine CLI from PATH and forwards the --model value. Production gh-aw integration should install or provide the selected engine CLI in the detection job, then run the pinned detector binary downloaded from the GitHub Release in that same runner/AWF environment. This keeps the binary small, avoids runtime installation, and reuses the existing engine installation/authentication path.
• Custom steps: custom threat-detection.steps remain orchestrator-owned. They should run before or after the detector in the gh-aw job rather than being passed into the detector as arbitrary scripts.
• Backward compatibility: do not ship a long-lived dual-mode compatibility window. Stage 3 should switch gh-aw to the pinned detector binary path after Stage 4 validation passes; users that need inline detection can pin an older gh-aw release. A temporary internal fallback is acceptable during implementation only, but should not become a documented public feature flag unless Stage 4 exposes a blocking compatibility issue.
• Ollama/LlamaGuard: keep this as a custom-step pattern unless a dedicated detector variant is explicitly required.
• Version coupling: use strict, semver-compatible release tags and have gh-aw pin a specific DefaultThreatDetectionVersion, matching the firewall pattern.
• Isolation: the detector should run in the standard detection job initially. Running the detector itself inside an additional firewall/isolation layer can be evaluated later.

Release Asset Setup

The repository can remain private while publishing release assets. The release workflow builds Linux and macOS binaries for amd64 and arm64, records each asset's sha256 in the release notes, and attaches them (plus a shared checksums.txt) to a GitHub prerelease using the automatic GITHUB_TOKEN with contents: write. release-targets.txt is the canonical build matrix for both tagged and rolling releases. The scheduled Release Platform Parity workflow compares its asset names with the platforms supported by gh-aw's installer.

Maintainers need to configure the following before the binary is consumed by gh-aw:

1. Keep Actions enabled for this private repository.
2. Grant the consuming github/gh-aw repository (or its GITHUB_TOKEN) contents: read access to download the release asset from this repository.
3. Keep the release-publish and release-promote environments if manual approval is desired; otherwise update the environment protection rules in repository settings.
4. Tag releases with semantic versions such as v0.0.2. The release workflow publishes the version-tagged prerelease; the promote workflow verifies the recorded asset sha256 and marks the release Latest (stable).

No additional secrets are required for unit tests, make build, make test, or the binary smoke test. Engine authentication is only needed when running real AI-backed detection:

Variable	Required when	Notes
COPILOT_GITHUB_TOKEN	Running --engine copilot in an environment that needs explicit token-based Copilot authentication	Use a fine-grained PAT owned by a user account with Account permissions → Copilot Requests: Read. GITHUB_TOKEN is not sufficient for Copilot inference.
ANTHROPIC_API_KEY	Running --engine claude with the Claude CLI	Not used by unit tests.
OPENAI_API_KEY	Running --engine codex with the Codex CLI	Not used by unit tests.
WORKFLOW_NAME	Optional local runs	Included in the generated prompt. Overridable with --workflow-name.
WORKFLOW_DESCRIPTION	Optional local runs	Included in the generated prompt. Overridable with --workflow-description.
CUSTOM_PROMPT	Optional local runs	Appended to the default detection prompt. Overridable with --custom-prompt / --custom-prompt-file.
GH_AW_DETECTION_CONTINUE_ON_ERROR	Optional, host-integrated runs	Anything other than "false" is warn mode; the value is compared case-insensitively, so "False" also selects strict mode. Strict mode makes a degraded required input a config_error (exit 2), and is also honored by conclude.
HAS_PATCH	Optional, host-integrated runs	"true" declares that the agent job produced a patch, so a missing aw-*.patch / aw-*.bundle is reported as a degraded required input.

Development

Prerequisites

• Go 1.26+

AW Smoke Workflows

This repository includes three Agentic Workflows smoke tests, one per engine:

• .github/workflows/smoke-copilot-standalone.md
• .github/workflows/smoke-claude-standalone.md
• .github/workflows/smoke-codex-standalone.md

Each runs daily and by workflow_dispatch. The top-level Smoke workflow can be dispatched manually with a scope input — standard (the three pinned *-standalone smokes), standard+latest (also their *-standalone-latest counterparts), or latest (only the latest smokes). The matching .lock.yml files are the compiled AW workflows. The *-standalone variants set features: gh-aw-detection: true, so gh-aw natively downloads this repo's released binary matching the runner platform (pinned to a promoted release tag), runs it under AWF, and reads the structured detection_result.json via threat-detect conclude. Each also has a smoke-<engine>-standalone-latest.md counterpart that tests the newest detector build — see Testing the Latest Detector Under AWF.

Detection-only Workflow

.github/workflows/detection-only.yml is a manual iteration workflow for the generated detection job. It keeps the copied detection job body aligned with the smoke-copilot-standalone smoke workflow — it installs the released threat-detect binary, runs threat-detect --engine copilot --output detection_result.json under AWF, and concludes from the structured detection_result.json via conclude_threat_detection.sh — while replacing prior activation and agent jobs with stubs that upload local fixtures from testdata/detection-only/ as the agent artifact.

Testing the Latest Detector Under AWF

Production gh-aw hard-pins the threat-detect binary version as a compile-time Go constant (constants.DefaultThreatDetectVersion). That makes the scheduled *-standalone smokes faithful to production, but they can never exercise a newer detector build — bumping the version requires a new gh-aw release. There is no frontmatter, repo-variable, or custom-step hook to override it.

To close that gap without maintaining a parallel non-AWF code path, the repo keeps a latest counterpart of each smoke — smoke-<engine>-standalone-latest.{md,lock.yml} — whose .lock.yml is compiled by a gh-aw whose detector constant has been patched to the newest detector build. Everything else matches production, so detection still runs through the real native gh-aw + AWF path.

The compiled workflow locks fall into three version categories:

Category	Lock filename pattern	gh-aw version	detector version
standard	e.g. detection-failure-monitor.lock.yml	latest stable github/gh-aw release	gh-aw's built-in default
standalone smoke	*-standalone.lock.yml	latest github/gh-aw release or prerelease	gh-aw's built-in default
standalone latest	*-standalone-latest.lock.yml	latest github/gh-aw (pre)release	latest github/gh-aw-threat-detection (pre)release

Keeping the locks current. The .github/workflows/gh-aw-version-check.yml workflow runs daily (and on demand). It is read-only — it builds and compiles nothing. It reads the versions already baked into each .lock.yml, compares them against the targets for that category, and, when any lock is stale, opens (or updates) a single tracking issue listing every workflow that needs regenerating and the target versions. When everything is in sync it closes that issue.

Regenerating the locks is a separate, manual, human-reviewed step because pushing changes under .github/workflows/ requires a token with the workflows permission, which the built-in GITHUB_TOKEN lacks. Follow the update-workflow-versions skill: recompile the affected sources with the target gh-aw version (building a detector-patched compiler from source for the *-standalone-latest locks), then open a PR.

The smoke-<engine>-standalone-latest workflows themselves are dispatch-only plus a push trigger scoped to their own .lock.yml on main: merging a regeneration PR updates a lock, which triggers that engine's latest smoke automatically. They never run on a schedule, so the pinned *-standalone smokes' steady-state behaviour is unchanged.

Tag → test → promote loop:

1. Cut a release tag (create-release-tag.yml); release.yml publishes a version-tagged prerelease with the recorded asset sha256. The next gh-aw-version-check.yml run (or a manual dispatch) flags that the latest locks are behind the new detector tag.
2. Regenerate the latest locks per the update-workflow-versions skill and open a PR.
3. Review and merge the PR, then confirm every smoke-<engine>-standalone-latest run is green.
4. Promote with promote-release.yml; it re-verifies the asset sha256 and marks the release Latest (stable). The pinned *-standalone smokes continue to run against the promoted tag.

You can also start the latest smokes from the top-level Smoke workflow by dispatching it with scope: latest (or scope: standard+latest to run both alongside the pinned smokes).

Note

gh-aw-version-check.yml only needs contents: read and issues: write — it detects drift and files an issue, but never pushes. Regenerating the *.lock.yml files (via the update-workflow-versions skill) is done by a maintainer/agent whose credentials carry the workflows permission.

The smoke-<engine>-standalone-latest.lock.yml files must not be regenerated by a plain gh aw compile — running the normal compiler over their .md would revert the patched detector version. Build a detector-patched compiler from source as the update-workflow-versions skill describes.

Secret	Required for	Notes
COPILOT_GITHUB_TOKEN	Copilot smoke workflow and Copilot detection	Use a fine-grained PAT owned by a user account with Account permissions → Copilot Requests: Read.
ANTHROPIC_API_KEY	Claude smoke workflow and Claude detection	Used by the Claude CLI.
OPENAI_API_KEY or CODEX_API_KEY	Codex smoke workflow and Codex detection	Configure whichever token your Codex CLI setup expects.
GH_AW_GITHUB_TOKEN	Recommended for GitHub MCP access, safe outputs, and release-asset downloads	The generated workflows fall back to GITHUB_TOKEN where possible.
GH_AW_GITHUB_MCP_SERVER_TOKEN	Optional GitHub MCP override	Falls back to GITHUB_TOKEN in the compiled workflows.

Optional Actions variables:

Variable	Purpose
GH_AW_MODEL_AGENT_COPILOT, GH_AW_MODEL_AGENT_CLAUDE, GH_AW_MODEL_AGENT_CODEX	Override the agent model for each smoke workflow.
GH_AW_MODEL_DETECTION_COPILOT, GH_AW_MODEL_DETECTION_CLAUDE, GH_AW_MODEL_DETECTION_CODEX	Override the detection model for each engine. When --model is not passed, the detector reads the variable matching the selected engine; if it is unset, it falls back to the engine CLI's native model env var (COPILOT_MODEL for copilot, ANTHROPIC_MODEL for claude).
GH_AW_THREAT_DETECTION_VERSION	Detector release tag downloaded by detection-only.yml (defaults to the latest promoted release when unset). The scheduled *-standalone smoke workflows instead pin a specific promoted tag at compile time for reproducibility, and the *-standalone-latest variants pin whatever they were last regenerated against — the newest gh-aw / detector version release, prerelease or stable (see the update-workflow-versions skill).

Build

make build

Test

make test

Lint

make lint

Smoke

Build the binary and run a --version smoke check:

make smoke

Architecture

cmd/threat-detect/     CLI entry point
pkg/detector/          Core detection logic (prompt building, result parsing)
pkg/engine/            AI engine abstraction (copilot, claude, codex)
pkg/artifacts/         Artifact reading and validation
pkg/detector/prompts/  Embedded AI prompt template
specs/                 W3C-style specifications (detection behavior + usage)

Integration with gh-aw

gh-aw references this component via:

const DefaultThreatDetectionRepo    = "github/gh-aw-threat-detection"
const DefaultThreatDetectionVersion = "v0.0.2"

The detection job in compiled workflows downloads the pinned threat-detect release asset matching the runner operating system and architecture and runs it instead of inline AI engine invocation.

Specification

See specs/threat-detection-spec.md for the full W3C-style specification of detection behavior, and specs/usage-spec.md for the W3C-style usage specification covering how a host acquires, invokes, and concludes a detection run.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

Maintainers

See CODEOWNERS for maintainers.

Support

See SUPPORT.md for help, issue reporting, and support scope.

Code of Conduct

See CODE_OF_CONDUCT.md.

Security

See SECURITY.md for vulnerability reporting instructions.

License

See LICENSE for details.