config-resolver

Config Resolver

Overview

Resolve the active configuration for the security coding agent by merging config file settings with per-invocation overrides, then validating governance constraints.

Resolution Order (highest priority wins)

1. Per-invocation override — extracted from the user's prompt (e.g., "only scan with Snyk", "fix GHAS alerts only")
2. Directory mapping — from .security-agent.json directoryMapping, matched against the current file/directory
3. Auto-detection — from the scanner-detection skill (repo artifacts, config files, CI workflows)
4. Config defaults — defaults.scanner from .security-agent.json
5. Plugin defaults — security-coding-agent/defaults.md

Guardrails Handoff Check

Before running any governance checks, inspect the workspace root for .guardrails-agent.json.

If .guardrails-agent.json exists:

• Set internal flag guardrailsActive: true
• Skip the entire Governance section below — those checks are now handled by the policy-enforcement skill via the agent's adapter skill.
• Continue with: scanner detection, guidelines path resolution, and LSP startup only.

If .guardrails-agent.json does not exist:

• guardrailsActive: false
• Proceed with all sections below as normal (backwards-compatible mode).

Process

1. Read config file:

   • Look for .security-agent.json in the workspace root
   • If not found, skip to auto-detection (step 3)
   • Validate against JSON Schema at schemas/security-agent.schema.json

2. Check per-invocation override:

   • Parse the user's prompt for scanner/feature mentions
   • Supported patterns: "fix CodeQL alerts", "run Snyk scan", "check Wiz findings", "SonarQube issues only"
   • If found, these take highest priority

3. Check directory mapping:

   • If the current file path matches a key in directoryMapping, use those scanners
   • Match is prefix-based: file at infra/terraform/vpc/main.tf matches infra/terraform/
   • Multiple scanners per directory: "src/": "ghas,sonarqube,snyk" → all three active

4. Run auto-detection (if enabled):

   • Delegate to scanner-detection skill
   • Returns detected scanners based on repo artifacts

5. Apply config defaults:

   • If no scanner resolved yet, use defaults.scanner from config

6. Resolve per-scanner config:

   • For each active scanner, read its entry from scanners.<name> in config
   • Resolve features, guidelines path, API endpoints
   • If no config entry, use scanner module defaults

7. Governance validation:

   • If governance.approvedScanners is set and a resolved scanner is NOT in the list → STOP. Surface error.
   • If governance.mandatoryGuidelines is true and a scanner's guidelines file is missing → STOP. Surface error.
   • If governance.enforceLsp is true and LSP is not available → STOP. Surface error.

8. Fetch org policy (if configured):

   • If governance.orgPolicyEndpoint is set:
     • GET <endpoint>/security-policy?namespace=<org-namespace>
     • On 200 OK: merge response into governance config (remote overrides local)
     • On timeout (>5s) / 5xx: fail-closed — STOP with error
     • On 4xx: log warning, proceed with local governance
     • Network unreachable: fail-closed

9. Return resolved config:

   • Active scanners list, per-scanner features, guidelines paths, auto-fix policy, severity threshold, ignore patterns, deny list

Output Format

After resolution, state the resolved config clearly:

Resolved config:
- Active scanners: [list]
- Severity threshold: <threshold>
- Auto-fix policy: P0=<action>, P1=<action>, P2=<action>, P3=<action>
- Compliance frameworks: [list]
- Ignore patterns: [list]
- Auto-fix deny list: [list]
- Source: <which resolution level determined the scanners>
- Governance: <local / remote policy endpoint>