Capabilities & Use Cases

How STAR exercises an application, how teams trigger it in a pipeline, and what it handles automatically underneath the scan → fix → validate loop described in Intro.

Run modes

How STAR exercises your application. Start with Function Harness.

Function Harness

RUN_MODE=function. STAR identifies the security-critical functions in your codebase (SQL queries, file I/O, command execution, and similar), generates a lightweight HTTP harness that exposes them as testable endpoints, and runs dynamic tests against that surface. Only minimal infrastructure is started, for example a database or Redis, so a run does not wait on the full application stack.

Start here: it asks the least of your CI environment and returns security results on the first run.

Scope: individual functions, rather than multi-step flows or the full routing and auth layer. Auth-dependent tests are not run, and functions that require a full framework boot (tier-3 targets in the agent) are excluded.

Full Application

RUN_MODE=full (the default). STAR builds and starts the application with Docker/Docker Compose and tests its real HTTP API, which reaches multi-step flows, the routing layer, and authenticated surface. It falls back to Function Harness mode on two failures:

• The application can't start. After a partial-boot retry that strips non-essential Compose services, STAR continues in Function Harness mode. Applications that need external runtime services, cloud-only dependencies, or a specific PaaS environment often can't be fully started on a CI runner.
• Authentication can't be configured. STAR first tries auth stubbing and falls back to the function harness only if that also fails.

RUN_MODE=dynamic is the strict variant: it requires the app to start and auth to be configured, never stubs authentication, and aborts instead of falling back to the harness.

Fuzzing

RUN_MODE=fuzzing. A self-contained mode that hunts a different class of bug: crashes, hangs, out-of-memory, native memory-safety faults, and resource-amplification DoS reached past input validation, rather than the OWASP payload classes DAST covers. Like Function Harness mode it wraps individual functions, but instead of HTTP-scanning them it drives a standalone evolutionary, coverage-guided fuzzer against LLM-generated per-function harnesses in Docker, with no app startup, no cloud scan, and no auth. Use it as a second, orthogonal pass scheduled alongside your DAST runs. See Fuzzing Mode.

See Run Modes & Scan Scope for the full RUN_MODE reference.

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 such as services, models, and 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, with 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.

Auth stubbing

When STAR can't configure a real login, most often because the application authenticates only through an external identity provider such as Okta, Google, or SAML, it can stub authentication and still test the authenticated surface. BRIGHT_AUTH_STUB sets the behavior:

• auto (default): a fallback. STAR tries a real login first and stubs only if that fails.
• on: STAR stubs authentication directly, without trying a real login. Use it when you already know the login can't be configured, for example with external-IdP-only auth. It also skips the failure detection that auto relies on.
• off: never stub.

The stub is always tried before the function harness, so on the full-application auth path the order is real login → stub → function harness.

STAR finds the code on a protected route that reads the request credential and patches it temporarily. A request carrying a secret per-run header, X-Bright-Principal, is then treated as coming from a logged-in real, most-privileged user that already exists in the application's data store. STAR registers that header with Bright as an auth object and scans signed in. Only authentication is stubbed. Authorization checks (roles, ownership, tenancy, scope) stay untouched, so broken access control and BOLA findings remain real.

STAR verifies the patch before trusting it. It probes the protected route three ways and requires the correct header to be granted while a missing header and a wrong secret are both denied. The per-run secret is redacted from logs, and the patch is reverted when the run ends and never committed to any fix branch or PR.

Stubbing re-enables the auth-dependent tests (broken access control, BOLA, and everything behind a login) that are otherwise excluded when no auth is configured. It runs only on the full-application path (RUN_MODE=full). RUN_MODE=dynamic forces it off, because the strict mode fails rather than silently bypassing authentication, and function, fuzzing, and validation never reach it. It needs a buildable checkout of the application source, so STAR can patch and rebuild it, and a protected route with a real user to authenticate as. Where neither is available, prepare a Bright auth object in advance and reference it by ID in BRIGHT_STAR.md. Runs with stubbed authentication are labeled as such in the summary and PR report.

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.

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).