Agents & Skills

The STAR Plugin ships orchestration agents and reusable skills. The agents drive end-to-end workflows; the skills are the building blocks they call internally. You interact with agents; the skills run behind the scenes.

This page is the canonical inventory: the agents are listed below, the skills in the table further down. Other pages link here rather than repeating the list.

Agents

bright-application-testing

Scans the application and reports findings. Does not modify your code.

What it does:

1. Analyzes the repository: detects languages, frameworks, routes, and API specs.
2. Reaches the target: health-checks a URL if you supplied one, follows the startup or deploy method if you described one, and otherwise works the startup out from the repository, brings the app up locally, and tells you which method it picked, with the built frontend when the app serves one; if it can't, JavaScript is reported as a gap.
3. Configures Bright: resolves the project, creates or reuses a Repeater for private/local targets.
4. Maps every authentication mechanism the code enforces and configures a verified auth object for each one the scanned surface needs.
5. Registers the attack surface (entrypoints) safely with the register-entrypoints skill: excludes endpoints with irreversible side effects, derives parameter values from the code, deduplicates by operation, and checks the response Bright recorded for each entrypoint.
6. Runs dynamic scans and returns a structured findings report grouped by severity and endpoint.

Use when: you want to know what's exposed, during development, before a merge, or against a staging environment.

bright-remediation-loop

Scans, fixes, and proves the fix. Modifies your code.

What it does:

1. Runs the same preparation as bright-application-testing (analyze → reach → configure → register → scan), and establishes how a fix will reach the running target before scanning anything.
2. For each confirmed finding: traces the data flow to the vulnerable sink, applies the smallest fix, gets it into the running target (a restart, or a rebuild-and-redeploy where the target runs a built artifact), confirms the target actually carries the change, and re-runs the same scan.
3. Repeats up to 5 rounds until findings are gone or the round limit is reached.
4. Reports which findings were fixed (with proof), which fixes went unvalidated, and which findings remain open.

Use when: you want vulnerabilities fixed and the fix proved: not just a patch, but evidence that the same scan no longer reproduces the issue.

bright-discovery

Builds the endpoint list from your source code and registers the endpoints with code-grounded parameter values, using a crawl only as a fallback, and reports what it couldn't register and why. Does not scan, and does not modify your code.

What it does:

1. Analyzes the repository: detects languages, frameworks, routes, and API specs.
2. Reaches the target: health-checks a URL if you supplied one, follows the startup or deploy method if you described one, and otherwise works the startup out from the repository, brings the app up locally, and tells you which method it picked, with the built frontend when the app serves one; if it can't, JavaScript is reported as a gap.
3. Configures Bright: resolves the project, reuses an idle Repeater for the project when one exists, or creates a new one for private/local targets.
4. Resolves authentication as an auth map: reuses a caller-supplied authObjectId for the mechanism it verifies against, maps the application's other mechanisms from the code, and creates a verified auth object for each one, so discovery reaches every authenticated route group; a mechanism it can't cover is reported as a gap with the request it sent and the response.
5. Discovers entrypoints whitebox from the code (routes, handlers, DTOs, gRPC-gateway annotations) and registers each one directly. When the repository ships an OpenAPI/Swagger definition, the agent uses it for the endpoint list and for composing HAR files, with values still taken from the code and seed data; it never uploads the spec itself. When many routes remain for one credential, above all behind an auth object that logs in or fetches a token on every single registration, it composes them into a HAR file with the compose-har skill and registers them through one discovery, then reads them back and reconciles them entry by entry. It falls back to a crawl only for surface the code cannot show, with a stated reason, using the same register-entrypoints skill as the scanning agents.
6. Synthesizes parameter values from the code (enums, types, validation rules, DTO constraints, DB seeds) so entrypoints pass server-side validation and seed a later scan well.
7. Deduplicates by operation, so parameter variants or alternate transports of one handler become a single entrypoint, and skips static assets (CSS, images, fonts, source maps, manifests) while keeping JavaScript for scanning.
8. Registers each entrypoint with health checkpoints after the first of each kind and after destructive operations; checks the response Bright recorded, fixing values or recording a gap; runs destructive operations last against sacrificial objects, prunes unreachable entries, and builds its summary from a final read-back from Bright: the entrypoint count, each entrypoint's health, and the gaps found by diffing the code inventory against what's registered, plus the skills it loaded.

Use when: your targets are hard to crawl, you lack Swagger specs or HAR files, or you want the endpoints from your code registered and checked, with the gaps named, before running a scan.

When to use which

Can the loop close?

The remediation loop's product is a proved fix, which means the edited code has to reach the running target before the validation scan. The agent works out whether that's possible before spending the baseline scan:

When the loop can't close, the agent stops before the baseline scan, says validation will be skipped, and lets you choose: supply a redeploy command, point it at an instance you control, continue with fixes explicitly labelled unverified, or stop after the scan and take the findings without any code changes.

⚠️

Validation is never skipped silently. A finding that stopped appearing is only reported as fixed when the same scan ran against the fixed code; anything else is labelled unverified.

Skills

The agents compose their workflow from these skills:

Workflow diagram

flowchart TD
    A[analyze-codebase] --> B[setup-repeater]
    B --> C[setup-auth]
    C --> D[register-entrypoints]
    D -.->|many routes of one credential| R[compose-har]
    R -.-> D
    D --> M{Agent?}
    M -->|discovery| P[Done — attack surface mapped]
    M -->|application-testing / remediation-loop| E[run-scan]
    E --> F{Findings?}
    F -->|No| G[Done — clean]
    F -->|Yes, application-testing| H[Report findings]
    F -->|Yes, remediation-loop| I[fix-and-validate]
    I --> J{Re-scan clean?}
    J -->|Yes| K[Done — fixed & proved]
    J -->|No, rounds left| I
    J -->|No, limit reached| L[Report remaining]

How skills use MCP tools

The skills do their work through the Bright MCP server's MCP Tools: resolving the project, creating a Repeater, verifying and saving auth objects, registering entrypoints and reading them back, running discoveries and scans, and retrieving findings.

fix-and-validate additionally edits code through the IDE.

Safety

• Only targets the user owns or is explicitly authorized to test are scanned or crawled. Discovery sends real HTTP requests to reach the surface, so the same authorization rule applies.
• The scanning agents exclude endpoints whose effects can't be undone in the environment, including under fuzzing. The discovery agent excludes only endpoints the handler code shows are guaranteed to break the run's or scan's own access, or are irreversible, and registers endpoints that are dangerous only under fuzzing. Every agent lists the registered endpoints a fuzzed request could still turn against the run as scan-risk.
• The scanning and discovery agents are instructed not to edit or add files in your repository. Scratch files go to a temporary directory outside it; only the dependency installs and build outputs the project's own build writes there are allowed. At the end of a run each agent compares git status with the start, undoes only its own changes, and leaves changes you already had in place. The remediation agent keeps only the fix edits it reports. Model behavior can vary, so check git status after a run.
• The remediation agent keeps edits minimal: no broad refactors, no placeholder code.
• After each fix round the agent health-checks the target and re-verifies auth, so a change that breaks the application surfaces before the validation scan rather than being reported as a fix.
• Auth objects are verified in unsaved form and only written to the project once they work, so failed attempts leave nothing behind.
• Repeaters are reused when possible. The discovery agent keeps the Repeater record for follow-on scans. A Repeater created for other sessions is cleaned up when the run finishes.