FAQ

Overview

What is the STAR Plugin?

A native package for your AI coding tool that wires Bright's orchestration agents and skills to the Bright MCP server. You ask an agent in chat to scan the app you're working on; it analyzes the repository, reaches the target, registers the attack surface, and runs dynamic security tests through Bright's scan engine.

How is it different from STAR in CI?

Same engine, different place in the workflow. STAR in CI is a binary triggered by a PR, push, or schedule and runs fully autonomously; see STAR Harness. The plugin is interactive and lives in your editor — you drive it, you see each step, and you can redirect it mid-run. The side-by-side comparison is on the STAR Plugin overview page. Nothing stops you from using both: the plugin during development, STAR as the pipeline gate.

How is it different from just configuring the Bright MCP server?

The MCP server gives your assistant the raw tools — runScan, addEntrypoint, createRepeater, and so on. It doesn't tell it how to use them well. The plugin adds the missing part: which endpoints are safe to fuzz, how to build a request body that actually exercises a handler, which tests to pick for what a route does, how to verify auth before saving it, and how to prove a fix by re-running the same scan. Raw MCP is the right choice when you're building your own integration.

Which tools are supported?

Cursor, Claude Code, Codex, GitHub Copilot, Antigravity CLI, and Devin — see Installation. Every package ships the same agents and skills; only the install mechanics differ. Devin has no dedicated package because its loader reads Claude plugin manifests, so it installs the claude-code package as-is — see Devin (Desktop & CLI).

Do I need my own AI model or inference token?

No. The plugin runs inside the AI coding tool you already use, on whatever model that tool is configured with. Unlike STAR in CI, there is no separate inference provider to configure — the only credentials are BRIGHT_HOSTNAME and BRIGHT_TOKEN.

Does my application have to be deployed somewhere?

No. If you give the agent a URL it health-checks it and scans that. If you don't, it works out how to start the app locally — Docker Compose, a Dockerfile, a Makefile target, a package.json script, or a framework command — starts it, tells you which method it picked, and scans what it started. It only stops to ask when the repository offers no way to start the application at all, or when it holds several deployable services and which one is under test is genuinely ambiguous. If your app comes up some other way, say so and the agent follows that instead (see Scenario 5).

Does the AI decide what counts as a vulnerability?

No. Findings come from the Bright Dynamic Security Scanner sending real attack traffic at the running target. The agent's job is orchestration: read the code, register a realistic attack surface, pick relevant tests, and interpret the results against your source. The verdict on whether an endpoint is exploitable is the engine's.

Agents and workflow

Which agent should I use?

bright-application-testing when you want to know what's exposed — it scans and reports and never touches your code. bright-remediation-loop when you want it fixed and the fix proved — it edits code, gets the change into the running target, and re-scans. Detailed comparison in Agents & Skills.

How many fix attempts does the remediation loop make?

Up to 5 rounds. Each round groups findings by root cause, applies the smallest fix that removes the issue, gets that change into the running target — a restart, or a rebuild-and-redeploy where the target runs a built artifact — confirms the target really carries it, and re-runs the same scan configuration. Findings that disappear are reported as fixed; findings that survive stay in the open set for the next round. Whatever is still open when the limit is reached is reported as open, not as fixed.

What if the agent can't restart or redeploy my app?

Depends on how the target got there. If the agent started the app itself, it can restart it and nothing is needed from you. If you handed it a URL for an environment it can't deploy to, it can write fixes but never prove them — so it stops before the baseline scan rather than discovering the problem after a round has already been spent, and offers four ways forward: give it a rebuild-and-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 code changes. See Can the loop close?.

Can I get fixes without validation, knowingly?

Yes — that's the third option above. Worth understanding what you give up: no finding is ever confirmed fixed, rounds after the first have nothing to compare against, so the run is effectively one scan plus patches. Those patches are reported as unverified and listed separately from validated fixes, never mixed in.

Can I run the individual skills myself instead of a whole agent?

In tools that expose skills directly, yes. Codex invokes them as $run-scan, Devin as /bright-security:run-scan, and other tools call them on their own when relevant. It's useful when you only need one piece — set up auth, or re-run a scan you already configured. The skills table lists what each one does.

Do I have to name the agent explicitly?

Usually not — describing the task is enough and the tool delegates. Naming the agent (or @-mentioning it, depending on the tool) guarantees which one runs. The per-tool README documents the exact syntax.

Credentials and projects

What credentials do I need?

Two environment variables: BRIGHT_TOKEN (a Bright API token) and BRIGHT_HOSTNAME (your cluster, e.g. app.brightsec.com). Both the MCP server and the Bright Repeater read them. See Installation.

Why do they have to be exported before I launch the tool?

Most tools read MCP configuration at startup, so a variable exported mid-session doesn't reach the already-registered server. The agents check both up front and stop with a clear message naming what's missing, rather than failing later as an opaque authentication or connection error. Put them in ~/.zshrc / ~/.bashrc and the question doesn't come up again.

Will the agent ask me to paste my token into the chat?

No, by design. A missing token is reported as an instruction to export it and restart the session. The token belongs in the environment or your tool's secret store, not in conversation history.

Personal, project, or organization token — which should I use?

A project-scoped token is the easiest to work with: there's exactly one project the run can reach, so the agent uses it and tells you which. With an org-wide token you name the project when you start, because the agent asks rather than guesses — guessing wrong writes your scan results into someone else's project. See Personal API Key Scopes.

Does everything land in one Bright project?

Yes. The Repeater, the auth object, the entrypoints, and every scan in a run are scoped to a single project, resolved once before anything is created. That's what makes the results reviewable in the Bright UI afterwards, and what makes a follow-up validation scan comparable to the baseline.

Can I use a self-hosted or EU cluster?

Yes — point BRIGHT_HOSTNAME at it (EU is eu.brightsec.com). Two tools need care: Codex doesn't interpolate ${VAR} in MCP config, and Antigravity's bundled config ships placeholders as a template. Both package READMEs cover how to register the server against a non-default cluster.

Repeater and network access

When do I need a Repeater?

Only for targets Bright's cloud can't reach on its own — anything on localhost, a private network, or behind a VPN. A publicly reachable staging URL is scanned directly with no Repeater involved.

Where does the Repeater run, and does it need inbound access?

It runs on your machine (or wherever the agent is executing) and connects outbound to Bright. Nothing needs to be exposed to the internet; the target only has to answer from where the Repeater runs — over the local network, a VPN, or a tunnel you already have up. See Repeater Prerequisites.

Do I have to create and clean up the Repeater myself?

No. The agent reuses a healthy Repeater scoped to the application if one exists, creates one otherwise, verifies Bright reports it as connected before scanning, and removes a Repeater it created for the session when the run finishes.

The Repeater process is running but the scan behaves as if it isn't there.

Almost always a cluster mismatch: the Repeater registered against one Bright cluster while the scan runs on another. Nothing errors — the scan simply never finds it. The Repeater has to start against the same host the MCP server is registered with, which is why the documented command passes $BRIGHT_HOSTNAME explicitly. Test it directly:

npx @brightsec/cli repeater --id <REPEATER_ID> --hostname "$BRIGHT_HOSTNAME" --token "$BRIGHT_TOKEN"

Authentication

Does the plugin handle applications behind a login?

Yes, and it matters more than it sounds: most of an API's surface sits behind auth, and an unauthenticated scan quietly tests almost none of it. The agent locates your login flow, builds a Bright auth object, verifies it against the real endpoint, and attaches it to the entrypoints that need it.

Where does it get test credentials?

From evidence in the repository — seed data, fixtures, .env.example, setup docs — or from wherever you point it. It doesn't invent credentials. Pointing it at the right file explicitly is the fastest path (see Scenario 3).

Will failed attempts leave broken auth objects in my project?

No. The auth payload is verified in unsaved form and only written to the project once it verifies, so a run that took several attempts to get the login right doesn't leave a trail of dead objects behind. If it can't get auth working within its retry budget, it stops and reports why instead of scanning an unauthenticated surface and calling it a result.

What happens if the session expires mid-scan?

The agent configures re-authentication on 401 and 403 responses, so an expiring session doesn't silently turn the rest of the run into noise. Registered endpoints that answer 401/403 are treated as an auth problem to fix, not as valid scan input.

Scanning

Which security tests does it run?

Whatever your Bright cluster currently supports and the endpoint group actually warrants. The agent queries the live test catalogue, drops deprecated and disabled tests, narrows by bucket to what the target is — an HTTP API draws on api and server_side, a rendered UI adds client_side, an MCP server adds mcp_attacks — and matches each remaining test against what the route does. See Test Buckets for the catalogue.

Reading it from the live catalogue rather than a fixed list is deliberate: Bright ships more tests than any hardcoded mapping would name and the catalogue changes between releases, so a static list silently narrows every scan.

Which vulnerabilities can it find?

Anything Bright can exercise and confirm at runtime against the target you point it at — the full Vulnerabilities Index. Coverage depends on how much of the surface the run actually reaches: an authenticated scan over well-formed request bodies covers far more than an unauthenticated one over empty payloads.

Will it destroy my data or fire off real emails?

It's built to avoid that. A scan sends many malformed and hostile requests to every registered endpoint, so the agent excludes endpoints whose effects you can't undo in that environment: irreversible state changes, out-of-band side effects like mail, SMS, payments, or third-party calls, and anything that would revoke the scan's own access. The judgment is made from what the handler does, not from the HTTP method — a DELETE over seeded, disposable data is an ordinary scan target, while one that removes a real tenant is not. When it isn't sure, it excludes the endpoint and tells you why.

Still, this is real attack traffic against a real application. Run it against an environment you can reset.

It excluded an endpoint I wanted scanned.

Tell it that endpoint is safe in this environment and it registers it. If the target runs on seeded data you can reset, say so up front — most of the irreversibility concern disappears and the retained surface gets noticeably wider.

Does it register endpoints manually or crawl the app?

Whichever fits. A small, well-understood route set is registered manually with realistic bodies, query values, and content types built from the code. A large or heavily generated surface is better served by Bright's discovery, which the agent runs against the same base URL and Repeater. Endpoints that answer 404 after registration are pruned before scanning.

How long does a scan take?

It scales with how many endpoints you register and how many tests each group draws — there's no fixed number. A focused run over a handful of endpoints on a new branch is quick; a full surface with the complete relevant test set is considerably longer. The agent monitors scans to completion and reports status as it goes.

Results

What do I get back?

From bright-application-testing: the detected stack and how the target was reached, the authenticated vs. unauthenticated surface, the Bright project and Repeater used, the scan groups and tests, findings grouped by severity and endpoint with method, URL and evidence, and any blockers that limited coverage. The remediation loop adds rounds completed, files changed, which findings disappeared after validation, and which stayed open. Full breakdown in Usage & Examples.

How do I know a fix actually worked, rather than trusting the agent?

Because the claim isn't based on reading the patch. A finding counts as fixed only when the same scan — same entrypoints, same tests, same attack locations, same auth — stops reporting it. That baseline is recorded during the first scan specifically so the validation run can reproduce it, and both runs are visible in your Bright project, so you can check the comparison independently of what the agent tells you.

Are the findings kept in Bright?

Yes. Scans, entrypoints, and vulnerabilities are ordinary project objects, so everything a run produced stays reviewable in the Bright UI and through the API after the chat session is gone.

Safety and limitations

What am I allowed to scan?

Targets you own or are explicitly authorized to test — your local dev server, staging or QA, or another environment you're authorized to assess. The agents ask for confirmation before scanning a target that isn't obviously yours. DAST sends real attack traffic, so authorization is the operator's responsibility.

⚠️

Not built for production

The plugin is a development- and staging-time tool. Attack traffic against production, and automated code fixes applied to a live system, are not what this workflow is designed for.

Are there limitations I should know about before relying on it?

A few worth knowing up front:

• The remediation loop needs a running target it can refresh. No way to get edited code into the target means no validation, and it will say so rather than proceed.
• Codex and Antigravity have no separate agent type, so the two orchestration workflows ship as skills there. Same instructions, different invocation.
• Devin cloud sessions don't load plugin subagents. Skills and the MCP server work; the orchestration agents are local-only, in Devin Desktop and the CLI. See Surface limitations.
• Coverage is bounded by the surface the run reaches. Multi-step business flows and UI-driven paths that the agent can't reproduce as HTTP requests won't be exercised.

Should I use the plugin or STAR in CI?

Both, for different jobs. The plugin catches what a branch exposes while you're still writing it, with you in the loop. STAR in CI is the gate that runs on every PR whether anyone remembers to ask. Neither replaces the other — see STAR Harness for the CI side.