From ec0e728bc8f6c4d88b9ef40ea5e9190b342722b1 Mon Sep 17 00:00:00 2001 From: kamalsrini <6233046+kamalsrini@users.noreply.github.com> Date: Mon, 15 Jun 2026 18:26:32 -0700 Subject: [PATCH] docs: define security fixer policy --- SKILL_TEMPLATE.md | 4 +- docs/fixer-policy.md | 100 +++++++++++++++++++ skills/appsec/api-security/SKILL.md | 2 + skills/appsec/dependency-scanning/SKILL.md | 2 + skills/appsec/secure-code-review/SKILL.md | 2 + skills/cloud/container-security/SKILL.md | 2 + skills/cloud/iac-security/SKILL.md | 2 + skills/devsecops/dast-config/SKILL.md | 2 + skills/devsecops/pipeline-security/SKILL.md | 2 + skills/devsecops/sast-config/SKILL.md | 2 + skills/devsecops/secrets-management/SKILL.md | 2 + 11 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 docs/fixer-policy.md diff --git a/SKILL_TEMPLATE.md b/SKILL_TEMPLATE.md index de3edded..8b4f1f4a 100644 --- a/SKILL_TEMPLATE.md +++ b/SKILL_TEMPLATE.md @@ -64,7 +64,9 @@ Hard rules only — falsifiable and enforceable. No "consider" / "may" language. ## 4. Remediation What the agent emits or changes when this fires. Keep complex logic in a -reference/script file (§7), not inline. +reference/script file (§7), not inline. If this skill can modify code or +configuration, classify each remediation path using the repo-level +`docs/fixer-policy.md` before applying changes. **Before (vulnerable):** ``` diff --git a/docs/fixer-policy.md b/docs/fixer-policy.md new file mode 100644 index 00000000..a149787c --- /dev/null +++ b/docs/fixer-policy.md @@ -0,0 +1,100 @@ +# Security Fixer Policy + +This policy classifies security findings by how an agent may remediate them. Fixer-capable skills must use this policy before changing files, generating patches, or recommending an automated remediation path. + +## Categories + +### Auto-fix + +The agent may apply the fix directly when the finding is high-confidence, the change is narrow, and the expected behavior is mechanically verifiable. + +Criteria: +- The vulnerable pattern and target file are unambiguous. +- The fix is deterministic and follows an existing project convention or a well-known safe default. +- The change has low blast radius and does not alter public APIs, authorization semantics, data models, deployment topology, or runtime trust boundaries. +- The agent can run or define a concrete verification step. + +Examples: +- Add missing security headers in a local framework configuration using the project's existing middleware pattern. +- Replace string-built SQL with parameter binding when the query shape and parameters are clear. +- Pin a container image tag or GitHub Action version when the intended version is known from lock files, release metadata, or existing repository conventions. +- Add a `.dockerignore` or `.gitignore` entry for `.env` files without removing or exposing secret values. + +### Assisted-fix + +The agent may prepare a patch or exact commands, but the user or repository owner must confirm context, run environment-specific checks, or choose among valid alternatives before merge. + +Criteria: +- The finding is valid, but the best remediation depends on application behavior, deployment constraints, ownership boundaries, or compatibility requirements. +- Multiple safe remediation options exist. +- The change is moderate in scope or requires coordinated validation outside the local workspace. +- The agent can reduce the work to a reviewable patch, migration plan, configuration diff, or decision list. + +Examples: +- Add authorization middleware to an endpoint when the correct role or ownership predicate needs product confirmation. +- Upgrade a vulnerable dependency across a major version boundary. +- Tighten CI permissions where release, package, or deployment jobs may need specific write scopes. +- Add Kubernetes `NetworkPolicy` rules where service communication requirements must be confirmed. + +### Guidance-only + +The agent must not modify files. It should explain the finding, risk, and recommended remediation path. + +Criteria: +- The remediation requires organizational policy, architecture changes, vendor configuration, legal review, procurement, or manual operational work. +- The agent lacks access to the system that must be changed. +- The change cannot be represented safely as a local patch. + +Examples: +- Adopt a centralized secrets manager across teams. +- Establish a vulnerability management SLA. +- Change cloud account guardrails, identity provider policy, or production firewall rules outside the repository. +- Resolve license obligations for GPL, AGPL, commercial, unknown, or no-license dependencies. + +### Human-review-required + +The agent must stop short of applying a fix and explicitly request human review before remediation proceeds. + +Criteria: +- A hard gate below applies. +- The finding involves sensitive credentials, production access, destructive operations, legal/compliance interpretation, or security-critical logic. +- The agent cannot confidently preserve intended behavior. +- The evidence is incomplete or the finding may be a false positive with material operational impact. + +Examples: +- Rotate leaked credentials or revoke certificates. +- Change authentication, authorization, cryptography, payment, medical, safety, or tenant-isolation logic. +- Modify production deployment, incident response, or containment procedures. +- Apply a remediation that deletes data, removes audit evidence, weakens controls, or accepts risk. + +## Decision Criteria + +Classify each finding using the most restrictive category that applies. + +1. Confirm the finding is in scope for the skill and supported by concrete evidence. +2. Determine whether any hard gate forces human review. +3. Estimate blast radius: local config or code path, cross-cutting application behavior, infrastructure, production operations, or organizational policy. +4. Check remediation confidence: deterministic patch, multiple valid options, missing context, or uncertain behavior. +5. Check verification: automated test or scan, manual validation, external approval, or no reliable verification available. +6. Choose the category: + - Use auto-fix only when evidence, scope, remediation, and verification are all strong. + - Use assisted-fix when a patch is useful but context or approval is required. + - Use guidance-only when local code changes are not the right remediation vehicle. + - Use human-review-required whenever a hard gate applies or safe behavior preservation is uncertain. + +## Hard Gates for Human Review + +Any of these conditions forces `human-review-required`: + +- Secret exposure requiring credential rotation, revocation, certificate replacement, or git history rewriting. +- Authentication, authorization, session management, cryptographic, payment, tenant isolation, or safety-critical logic changes. +- Production infrastructure, network, identity, IAM, deployment, incident response, or data retention changes. +- Destructive or irreversible actions, including deleting data, rewriting history, disabling audit logs, removing evidence, or changing backups. +- Legal, compliance, privacy, or license-risk decisions. +- Changes requiring owner-specific business rules, threat model assumptions, regulatory interpretation, or risk acceptance. +- Unclear ownership, missing tests for a high-impact path, conflicting framework guidance, or evidence that the finding may be a false positive. +- Any remediation that would weaken an existing security control to make a tool pass. + +## Skill Usage + +Fixer-capable skills must reference this policy when producing remediation guidance or patches. The policy classifies the remediation path only; it does not change finding schemas or require new output fields. diff --git a/skills/appsec/api-security/SKILL.md b/skills/appsec/api-security/SKILL.md index 1dc3c886..b45916ee 100644 --- a/skills/appsec/api-security/SKILL.md +++ b/skills/appsec/api-security/SKILL.md @@ -53,6 +53,8 @@ For detailed checklist items with vulnerable code patterns, remediation examples ## Findings Classification +Before applying or proposing patches, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + Each finding produced by this review must include the following fields: | Field | Description | diff --git a/skills/appsec/dependency-scanning/SKILL.md b/skills/appsec/dependency-scanning/SKILL.md index 4e29704f..504b7820 100644 --- a/skills/appsec/dependency-scanning/SKILL.md +++ b/skills/appsec/dependency-scanning/SKILL.md @@ -183,6 +183,8 @@ Typosquatting (also called dependency confusion or combosquatting) is a supply c ## Assessment Output Template +Before applying or proposing dependency changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + When performing a dependency scan, produce findings in the following structure: ``` diff --git a/skills/appsec/secure-code-review/SKILL.md b/skills/appsec/secure-code-review/SKILL.md index 9ee60491..68fab7d0 100644 --- a/skills/appsec/secure-code-review/SKILL.md +++ b/skills/appsec/secure-code-review/SKILL.md @@ -408,6 +408,8 @@ Remediation: Validate the URL scheme (allow only `https`), resolve the hostname ## Findings Classification +Before applying or proposing patches, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + Each finding produced by this review must include the following fields: | Field | Description | diff --git a/skills/cloud/container-security/SKILL.md b/skills/cloud/container-security/SKILL.md index 13583e4b..7f8edad3 100644 --- a/skills/cloud/container-security/SKILL.md +++ b/skills/cloud/container-security/SKILL.md @@ -124,6 +124,8 @@ Produce the final report using the structure defined in the Output Format sectio ## Findings Classification +Before applying or proposing container or Kubernetes changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + | Severity | Definition | Examples | |----------|-----------|----------| | **Critical** | Container escape, cluster compromise, or credential exposure | Privileged containers, Docker socket mounts, cluster-admin bound to application SA, secrets in plaintext manifests, `hostPID`/`hostNetwork` on app pods | diff --git a/skills/cloud/iac-security/SKILL.md b/skills/cloud/iac-security/SKILL.md index ccf5552d..53825c75 100644 --- a/skills/cloud/iac-security/SKILL.md +++ b/skills/cloud/iac-security/SKILL.md @@ -109,6 +109,8 @@ Produce the final report using the structure defined in the Output Format sectio ## Findings Classification +Before applying or proposing infrastructure changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + | Severity | Definition | Examples | |----------|-----------|----------| | **Critical** | Immediate exploitability, data exposure, or credential compromise | Hardcoded secrets, public S3 buckets with data, unrestricted ingress on all ports, `*:*` IAM policies, public database endpoints | diff --git a/skills/devsecops/dast-config/SKILL.md b/skills/devsecops/dast-config/SKILL.md index 6644a59d..0d820433 100644 --- a/skills/devsecops/dast-config/SKILL.md +++ b/skills/devsecops/dast-config/SKILL.md @@ -479,6 +479,8 @@ DAST tools report findings per-URL, producing hundreds of duplicate alerts for t ## Findings Classification +Before applying or proposing configuration changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + | Severity | Definition | |----------|-----------| | **Critical** | No authenticated scanning; active scanning targeting production; injection scan rules disabled; no scope restrictions. | diff --git a/skills/devsecops/pipeline-security/SKILL.md b/skills/devsecops/pipeline-security/SKILL.md index 1e464675..6681bcfb 100644 --- a/skills/devsecops/pipeline-security/SKILL.md +++ b/skills/devsecops/pipeline-security/SKILL.md @@ -492,6 +492,8 @@ Produce the final report using the following structure: ### Prioritized Remediation Plan +Before applying or proposing pipeline changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + 1. **[Critical]** -- 2. **[High]** -- 3. ... diff --git a/skills/devsecops/sast-config/SKILL.md b/skills/devsecops/sast-config/SKILL.md index 60845438..464ac27e 100644 --- a/skills/devsecops/sast-config/SKILL.md +++ b/skills/devsecops/sast-config/SKILL.md @@ -437,6 +437,8 @@ jobs: ## Findings Classification +Before applying or proposing configuration changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + | Severity | Definition | |----------|-----------| | **Critical** | No SAST tooling deployed; CWE Top 5 weaknesses with zero rule coverage for languages in active use. | diff --git a/skills/devsecops/secrets-management/SKILL.md b/skills/devsecops/secrets-management/SKILL.md index 40530637..845fed97 100644 --- a/skills/devsecops/secrets-management/SKILL.md +++ b/skills/devsecops/secrets-management/SKILL.md @@ -354,6 +354,8 @@ spec: ## Findings Classification +Before applying or proposing fixes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). + | Severity | Definition | |----------|-----------| | **Critical** | Committed secrets in current codebase or git history (unrotated); no secret detection tooling; .env with production credentials committed. |