Docs

Capabilities & Use Cases

How teams run STAR in a pipeline, and what it handles automatically underneath the scan → fix → validate loop described in Intro.

Use cases

Four ways to trigger STAR in a pipeline. These aren't separate products or install modes — the same binary is triggered differently and scoped differently depending on the event. All four share the same PR/branch reaction: verified fixes committed to the branch, a sticky summary comment, and a commit status.

Pull-Request Gate

Triggered on pull_request (or merge_request_event on GitLab). STAR traces the diff to the HTTP endpoints it affects — both endpoints whose own handler changed and endpoints that reach changed shared code (services, models, middleware) — and tests only those. A PR with no code changes (docs-only, config-only) exits before the application is built.

On completion, STAR commits any verified fixes to the PR branch, posts a summary comment, and sets a status check — "Marked Safe by Bright Agent" when nothing is left open.

Configuration: scoping is automatic (SCAN_SCOPE=auto); see Run Modes & Scan Scope. Platform setup in Running STAR in CI.

Continuous Scanning on the Default Branch

Triggered on push to the default branch. STAR diffs the commit against the previous one and scans only the endpoints reached by that diff, rather than the whole application.

Configuration: trigger on push to your default branch, with DIFF_BASE pointed at the previous commit (or leave SCAN_SCOPE=auto and let STAR resolve it from the ref history).

Full Application Baseline

Triggered on schedule or workflow_dispatch/manual run. STAR scans every registered endpoint with no diff scoping.

Configuration: set SCAN_SCOPE=full to force a full-repo scan regardless of branch — this is the recommended default for schedule/manual triggers.

SAST Validation

Set RUN_MODE=validation and SARIF_PATH=<path-to-sarif>. STAR replays each finding in the SARIF file against the running application and marks it confirmed or dismissed, instead of running the fix loop.

See the ready-made GitHub Actions CodeQL validation workflow for a complete example.

Capabilities

What STAR handles on its own during a run.

Autonomous workflow

Analyze → Build → Scan → Fix → Validate, in a loop of up to 5 passes, exiting early once the app is clean.

Auth detection

Finds JWT, API keys, sessions, and OAuth flows in your code, and configures multistep login automatically — no manually recorded login sequence required. Auth-dependent tests (broken access control, BOLA, brute-force login, etc.) are automatically excluded when no auth is configured.

Per-endpoint test selection

The agent picks the relevant security tests for each endpoint based on its technology, parameters, and purpose — rather than running every test against every endpoint.

Function-harness fallback

When the application cannot be fully started on the CI runner, STAR falls back to function harness mode instead of stopping the run. This happens automatically in the default RUN_MODE=full when build/startup fails (after a partial-boot retry that strips non-essential Compose services). Set RUN_MODE=function to use harness mode directly, or RUN_MODE=dynamic to disable the fallback and fail if startup does not succeed.

Typical cases where full startup fails and harness mode is used:

  • External runtime dependencies that cannot be mocked or replaced locally (proprietary APIs, cloud-only services, hardware-bound integrations).
  • Applications that are only fully functional when deployed to a specific cloud or PaaS environment, not from a local CI checkout.
  • Complex startup where essential services cannot be brought up on the runner.

What harness mode does:

  1. Starts minimal infrastructure only (e.g. database, Redis) — not the full application stack.
  2. Identifies security-critical functions in the codebase (SQL queries, file I/O, command execution, and similar).
  3. Generates a lightweight HTTP harness that exposes those functions as testable endpoints.
  4. Runs dynamic scans against the harness surface instead of the application's normal HTTP API.

Limitations compared to a full-app scan: the harness tests individual functions, not multi-step flows or the full routing/auth layer; auth-dependent tests are skipped; functions that require a full framework boot (tier-3 targets in the agent) are excluded. See Run Modes & Scan Scope.

Fix validation & self-healing

Every fix is applied, the app is restarted, and the fix is re-scanned to confirm it actually closes the hole. If a fix breaks the app, STAR detects it and repairs or reverts automatically rather than leaving a broken build behind.

Static-finding (SAST) validation

Replays CodeQL/SARIF findings against the live application and confirms or dismisses each one — see SAST Validation above.

Run memory (BRIGHT_STAR.md)

On a successful run, STAR writes known-good startup, auth, and scan-prep configuration to BRIGHT_STAR.md in your repository. A later run reloads it to skip rediscovery, making repeat scans faster and cheaper.

Inference provider support

Works with OpenAI, GitHub Models, Ollama, or any OpenAI-compatible endpoint. AI_MODEL accepts a comma-separated escalation chain that switches to the next model in the list if a phase fails on the current one — see AI / Inference Providers.

Supported security tests

STAR selects tests per endpoint based on its technology, parameters, and purpose. All vulnerability tests listed in the Vulnerabilities Index are supported.

STAR is language-agnostic — it detects the stack from the repository and builds/runs the application on the CI runner. The runner must have Docker and Docker Compose available (Podman is not supported yet).