Security Workflow

Updated on Oct 1, 2026

frg sec audits your project's open findings from a configured Static Application Security Testing (SAST) scanner, writes a remediation proposal for one finding, and answers security questions. Use it to prioritize scanner findings and plan fixes; it produces reports and proposals for human review, not deployed fixes.

Prerequisites

• A valid Telerik license. See Licensing.
• A supported coding agent, installed and authenticated. Check it with frg status.
• A security scanner configured in .forge/config/toolchain.toml. Every frg sec subcommand requires it; without it, Forge reports Security scanner not configured. See Configure the scanner.
• Scanner credentials in the environment that runs Forge.
• For frg sec patch only: an Issue ID whose issue references the finding. Without it, Forge reports Security patch requires an issue context.

Subcommands at a glance

Subcommand	What it does	Typical inputs	Outputs	Default role
audit	Audits the project using the scanner's open SAST findings	Scanner findings	.forge/work/<job_id>/security/audit_report.md	security_analyst
patch	Generates a remediation proposal for one finding	Issue with a finding reference (CWE-…, CVE-…, GHSA-…), scanner details	.forge/work/job_<issue_id>/security/patch_proposal.md	security_analyst
ask	Answers questions about findings and remediation	Question, audit_report.md, patch_proposal.md, scanner	.forge/work/<job_id>/answer.md	security_analyst

Typical flow

text

audit ──► pick a finding ──► set-issue ──► patch ──► patch --edit ──► ask ──► implement ──► re-scan
 (audit_report.md) (patch_proposal.md)

1. Audit the open findings:

bash

frg sec audit

2. Create or pick an issue that references one finding (for example CWE-89), and set it:

bash

frg config set-issue 278

3. Generate the remediation proposal and refine it:

bash

frg sec patch
frg sec patch --edit "Prefer parameterized queries over input escaping"

4. Clarify trade-offs:

bash

frg sec ask "Does the proposed fix also cover the batch import endpoint?"

5. Implement the proposal after a security review, for example with your code workflow:

bash

frg code create --fix "Implement .forge/work/job_278/security/patch_proposal.md"

6. Run your security and regression tests, then confirm the finding is closed in the scanner.

Configure the scanner

Add a [security_scanner] entry to .forge/config/toolchain.toml, or pass --scanner to frg config init:

bash

frg config init --issues github_issues --code github --scanner polaris

toml

[security_scanner]
name = "polaris" # or "github_sast"
type = "built-in"
method = "api"

Built-in scanner	Product	Credential
polaris	Black Duck Polaris	POLARIS_ACCESS_TOKEN
github_sast	GitHub Advanced Security	GITHUB_TOKEN (or FORGE_SECURITY_TOKEN)

Validation rules:

• For type = "built-in", name must be a built-in scanner.
• method can be cli, mcp, or api. local is rejected for security scanners.
• A custom scanner (type = "custom") must provide a description.

Keep tokens in the environment or your CI secret store, never in toolchain.toml, issues, prompts, or reports. For all toolchain fields, see Toolchain Configuration.

Options shared by all subcommands

Every frg sec subcommand accepts these options.

Option	Description	Default
-a, --agent <NAME>	Coding agent for this run: claude_code, github_copilot, or opencode.	Agent in agents.toml
-r, --role <ROLE>	Overrides the default role: product_manager, software_engineer, software_architect, technical_writer, security_analyst, sre. Cannot be combined with --custom-agent.	security_analyst
--custom-agent <NAME>	Selects a custom agent configuration inside your coding agent. Cannot be combined with --role.	None
-m, --model <MODEL>	Overrides the model configured in agents.toml.	Model in agents.toml
-c, --context-file <FILE>	Adds a file path as context. Repeatable.	None
--context-dir <DIR>	Adds a directory as context. Repeatable. Up to 100 files per directory and 1 MB per file.	None
--clear	Clears the existing agent session and starts fresh.	Off
--retry [<INSTRUCTIONS>]	Continues the previous session to complete missing outputs. Requires an existing session; cannot be combined with --clear.	Off
--auto-retry	Retries once automatically when expected outputs are missing. Cannot be combined with --clear.	Off
--print-prompt	Prints the compiled prompt without running the agent.	Off
--bypass-safety-checks	Skips prompt-injection validation. Bypasses are logged.	Off
-q, --quiet	Suppresses all output except errors.	Off

frg sec audit

Retrieves the open findings from the scanner, groups them by vulnerability class (for example a CWE category), and prioritizes them by severity, exploitability, and business impact.

text

frg sec audit [OPTIONS]

No additional options.

bash

frg sec audit

Output: .forge/work/<job_id>/security/audit_report.md, including a breakdown by severity, detailed analysis of critical and high findings, possible false positives, and defensive recommendations.

Notes:

• audit does not require an Issue ID.

frg sec patch

Reads the issue in the current context, retrieves the referenced finding from the scanner, analyzes the vulnerable code, and writes a remediation proposal.

text

frg sec patch [OPTIONS]

Option	Description
--edit [<INSTRUCTIONS>]	Refines the existing proposal with your instructions, given inline or in edit.md.

bash

frg config set-issue 278
frg sec patch
frg sec patch --edit "Add a regression test to the proposal"

Output: .forge/work/job_<issue_id>/security/patch_proposal.md.

Notes:

• The issue must contain a finding reference, such as CWE-XXX, CVE-YYYY-ZZZZ, GHSA-xxxx, or a scanner-specific ID.
• With --edit, if no patch_proposal.md exists, Forge generates a new proposal from the issue and the scanner findings.
• Have a qualified reviewer examine the proposal. Commit instructions are enabled for sec patch by default; see Commit Behavior.

frg sec ask

Answers a question about findings, vulnerabilities, or remediation. It reads security/audit_report.md and security/patch_proposal.md when they exist and retrieves a specific finding from the scanner if needed. It does not change code or reports.

text

frg sec ask [OPTIONS] [QUESTION]

No additional options.

bash

frg sec ask "Which findings are most likely false positives?"

Output: .forge/work/<job_id>/answer.md.

Secret masking

Forge masks detected secrets in agent output before writing trace files or showing output with frg --tail. Audit reports and patch proposals can still describe vulnerable code, so restrict who can read them. See Secret Masking.

Troubleshooting

Security scanner not configured

Cause: .forge/config/toolchain.toml has no [security_scanner] entry.

Solution:

1. Add the scanner: frg config init --issues github_issues --code github --scanner polaris --force (--force replaces the existing toolchain.toml), or edit toolchain.toml as shown in Configure the scanner.
2. Use cli, mcp, or api for method.

Verify: frg config validate

Security patch requires an issue context

Cause: frg sec patch runs without an Issue ID.

Solution:

1. Set the issue: frg config set-issue <issue_id>.
2. Run frg sec patch again.

The patch cannot identify a finding

Cause: The issue does not contain a scanner finding reference.

Solution:

1. Add the finding ID (CWE, CVE, GHSA, or scanner-specific) to the issue.
2. Run frg sec patch again.

Scanner authentication fails

Cause: The scanner returns 401 Unauthorized, 403 Forbidden, or an invalid or expired token.

Solution:

1. Check that the credential for your scanner (for example POLARIS_ACCESS_TOKEN) is set in the environment that runs Forge.
2. Check the token's scan permissions and expiration.
3. Check that method matches how the scanner is accessed.

See Also

• Toolchain Configuration: scanner, issue tracker, and code platform settings.
• Issue Management: the issue context for frg sec patch.
• Code Operations and Pull Requests: implementing and shipping the fix.
• Secret Masking and Prompt Safety.
• Command Reference.