diff --git a/skills/devsecops/secrets-management/SKILL.md b/skills/devsecops/secrets-management/SKILL.md index cc9c5ead..cd210e05 100644 --- a/skills/devsecops/secrets-management/SKILL.md +++ b/skills/devsecops/secrets-management/SKILL.md @@ -6,14 +6,15 @@ description: > Key Management). Auto-invoked when reviewing secret handling patterns, vault configurations, .env files, or credential rotation policies. Produces a secrets management assessment covering detection patterns, rotation automation, vault - integration, and agent-specific credential handling. -tags: [devsecops, secrets, vault, rotation] + integration, brokered agent credentials, canary tokens, and live-validation + safety. +tags: [devsecops, secrets, vault, rotation, agent-security] role: [security-engineer, devsecops] phase: [build, operate] frameworks: [OWASP-Secrets-Management, NIST-SP-800-57-Part1-Rev5] difficulty: intermediate time_estimate: "20-40min" -version: "1.0.1" +version: "1.0.2" author: unitoneai license: MIT allowed-tools: Read, Grep, Glob @@ -23,7 +24,7 @@ argument-hint: "[target-file-or-directory]" # Secrets Management Review -A structured, repeatable process for evaluating secrets management practices against the OWASP Secrets Management Cheat Sheet and NIST SP 800-57 Part 1 Rev 5 (Recommendation for Key Management). This skill covers secret detection patterns, rotation automation, vault and cloud secrets manager integration, agent-specific credential handling, .env file exposure, and git history secret leaks. All findings reference framework controls with severity ratings and actionable remediation. +A structured, repeatable process for evaluating secrets management practices against the OWASP Secrets Management Cheat Sheet and NIST SP 800-57 Part 1 Rev 5 (Recommendation for Key Management). This skill covers secret detection patterns, rotation automation, vault and cloud secrets manager integration, agent-specific credential handling, brokered credential access, approved canary tokens, live-validation scanner safety, .env file exposure, and git history secret leaks. All findings reference framework controls with severity ratings and actionable remediation. **Important:** This skill analyzes detection patterns and configuration practices. It never extracts, logs, or displays actual secret values. All regex patterns shown are for detection tooling configuration, not for secret extraction. @@ -44,7 +45,7 @@ If a target is provided via arguments, focus the review on: $ARGUMENTS ## Context -OWASP identifies hardcoded secrets as a persistent, high-impact vulnerability. The OWASP Secrets Management Cheat Sheet defines secrets as "digital authentication credentials that grant access to systems or data," including API keys, passwords, certificates, and encryption keys. NIST SP 800-57 Part 1 Rev 5 Section 5.3 establishes cryptoperiods -- the time span during which a specific key is authorized for use. Secrets that exceed their cryptoperiod without rotation represent both a compliance gap and an operational risk. In agentic and automated environments, the challenge intensifies: autonomous agents require credential access but should never hold long-lived secrets. +OWASP identifies hardcoded secrets as a persistent, high-impact vulnerability. The OWASP Secrets Management Cheat Sheet defines secrets as "digital authentication credentials that grant access to systems or data," including API keys, passwords, certificates, and encryption keys. NIST SP 800-57 Part 1 Rev 5 Section 5.3 establishes cryptoperiods -- the time span during which a specific key is authorized for use. Secrets that exceed their cryptoperiod without rotation represent both a compliance gap and an operational risk. In agentic and automated environments, the challenge intensifies: autonomous agents require credential access, but they should not be able to read, print, or exfiltrate real provider secrets when a brokered token, tool gateway, or capability handle can perform the operation at a trusted boundary. --- @@ -166,12 +167,13 @@ Before flagging a detected string as a hardcoded secret, apply these verificatio 1. **Verify the value is a real secret, not a placeholder or example.** Strings like `your-api-key-here`, `CHANGEME`, `TODO`, `xxx`, `example`, `test`, `dummy`, `fake`, ``, or `replace-me` are placeholder values, not leaked secrets. Do NOT flag these. 2. **Check entropy.** Real secrets (API keys, tokens, passwords) have high entropy — they appear random. Low-entropy strings like `password`, `admin`, `root`, `mysecret`, or dictionary words in config comments are not actual secrets. Only flag password assignments where the value appears to be a real credential (high-entropy, non-dictionary string of 8+ characters). 3. **Recognize known secret prefixes.** When a string matches a known secret format (e.g., `AKIA*` for AWS, `sk-*` for Stripe/OpenAI, `ghp_*`/`gho_*`/`ghu_*` for GitHub, `xox[bpors]-*` for Slack, `glpat-*` for GitLab, `eyJ*` for JWTs), it is likely a real secret and should be flagged. -4. **Distinguish secrets findings from architectural observations.** This skill should focus on **finding actual secrets in code and configuration**. The following are NOT secrets findings and should be excluded from the findings count: +4. **Classify approved canary or honey tokens before severity assignment.** A live-looking token can be an intentional monitored canary. Treat it as a control artifact, not a production leak, only when owner, account/project, no-production-privilege evidence, alert destination, expiry, and periodic revalidation are documented. Never print the token value. +5. **Distinguish secrets findings from architectural observations.** This skill should focus on **finding actual secrets in code and configuration**. The following are NOT secrets findings and should be excluded from the findings count: - Absence of secret detection tooling (note in the Detection Tooling Status table, not as a finding) - Absence of a centralized secrets manager (note in recommendations, not as a finding) - Missing rotation automation (note in recommendations, not as a finding) - Infrastructure misconfigurations unrelated to secrets (e.g., public S3 buckets, debug mode, public database endpoints) — these belong to other skills -5. **Scope to the skill's domain.** Only report findings where a secret (credential, key, token, certificate) is actually present in the file. General security misconfigurations, missing best practices, and architectural gaps should be noted in the Prioritized Remediation Plan section, not as numbered findings. +6. **Scope to the skill's domain.** Only report findings where a secret (credential, key, token, certificate) is actually present in the file. General security misconfigurations, missing best practices, and architectural gaps should be noted in the Prioritized Remediation Plan section, not as numbered findings. #### 2.3 Detection Tool Configuration Review @@ -196,6 +198,33 @@ Verify that at least one secret detection tool is configured and integrated: --- +#### 2.4 Canary Tokens and Live-Validation Safety + +Secret scanners may intentionally discover canary or honey tokens, and some scanners perform live validation against providers. Review both cases without weakening production-secret handling. + +**Canary/honey token evidence:** + +| Evidence Field | What to Verify | +|----------------|----------------| +| Account/project identity | Token belongs to a dedicated canary account, tenant, or project, not a production account | +| Production privilege | Token has no production data, write, deploy, billing, admin, or customer-impacting privilege | +| Owner and approval | Security owner, approval ticket, and reason are recorded | +| Alert route | Use of the token triggers a monitored SOC/webhook/on-call alert | +| Expiry and rotation | Expiry date and revalidation cadence are documented | +| Allowlist scope | Suppression is scoped to exact path, token alias, account, and expiry; no broad regex bypass | + +**Live-validation scanner evidence:** + +- Validators use read-only or metadata-only probes and do not trigger privileged side effects. +- Validation logs redact token values and sensitive account identifiers. +- Canary accounts are explicitly classified before live checks generate production-leak tickets. +- Provider calls are rate-limited and separated from automatic revocation or destructive remediation. +- Validation evidence records tool, provider, check type, timestamp, and reviewer, but never the secret value. + +**Finding classification:** Unclassified live token with production privilege is **Critical**. Approved canary token missing owner, alert route, expiry, or no-production-privilege evidence is **Medium**. Live validation that calls privileged APIs, logs values, or triggers side effects is **High**. + +--- + ### Step 3: .env File and Git History Exposure (OWASP Secrets Management Cheat Sheet) #### 3.1 .env File Exposure @@ -316,6 +345,41 @@ For agentic systems (AI agents, automation bots, CI/CD agents), evaluate credent - Vault AppRole or Kubernetes service account token injection is preferred over static API keys. - Credentials should be revoked or expire automatically after task completion. +#### 5.3 Agent Credential Exposure Model + +For agents that process untrusted repository files, issues, web pages, documents, tool output, or user-supplied prompts, record what the agent can actually see. + +| Exposure Model | Review Decision | +|----------------|-----------------| +| Raw long-lived secret in agent environment | High or Critical depending on privilege and exposure | +| Short-lived real secret in agent environment | Medium or High; acceptable only with tight TTL, scope, and no untrusted content path to disclosure | +| Broker token or placeholder visible to agent | Preferred when broker enforces host/path/method and injects real secret outside the agent runtime | +| Tool capability handle | Preferred when the tool gateway exposes narrow operations instead of any reusable credential | + +**Evidence to collect:** + +- Agent name, trust boundary, prompt/content sources, and outbound tool/network targets. +- Whether the real upstream credential is ever present in environment variables, process memory visible to the agent, logs, traces, prompts, tool results, or browser/session state. +- Credential TTL, scope, revocation path, and fallback behavior. +- Egress policy: default-deny network access, allowed hosts, and blocked private/metadata/internal ranges where applicable. +- Prompt-injection exposure: whether untrusted content can cause the agent to print, transform, browse to, or submit credential-bearing data. + +#### 5.4 Credential Broker and Capability Gateway Evidence + +Brokered credentials only reduce exfiltration risk when the broker enforces where and how the secret can be used. + +| Broker Evidence | Required Detail | +|-----------------|-----------------| +| Host binding | Exact upstream hosts or service identifiers; no wildcard injection | +| Path/method binding | Allowed API paths, methods, and operation classes | +| Identity binding | Agent, workflow, repository, branch, environment, and human approver if applicable | +| Default-deny egress | Unlisted destinations are blocked before credential injection | +| Upstream secret custody | Real provider secret remains server-side and is never returned to the agent | +| Audit log | Agent, tool, upstream service, request class, credential alias, decision, and timestamp; no secret values | +| Fallback mode | Broker outage does not silently inject long-lived provider secrets into the agent runtime | + +**Finding classification:** Broker injects upstream credentials for any host/path or uses default-allow egress is **High**. Real provider secret is visible to an agent that consumes untrusted content is **High** or **Critical** if broad write/admin production privilege exists. Missing broker audit logs or fallback evidence is **Medium**. + **Patterns to check:** ```yaml @@ -348,7 +412,7 @@ spec: kind: SecretStore ``` -**Finding classification:** Agents using long-lived static credentials is **High**. No JIT credential mechanism for automated systems is **Medium**. Token TTL exceeding 10x task duration is **Medium**. +**Finding classification:** Agents using long-lived static credentials is **High**. No JIT credential mechanism for automated systems is **Medium**. Token TTL exceeding 10x task duration is **Medium**. Brokered or capability-scoped access with host/path/method binding, default-deny egress, and value-free audit logs is preferred. --- @@ -357,8 +421,8 @@ spec: | Severity | Definition | |----------|-----------| | **Critical** | Committed secrets in current codebase or git history (unrotated); no secret detection tooling; .env with production credentials committed. | -| **High** | No centralized secrets manager; no rotation automation; long-lived static credentials for agents; secrets in CI logs; no git history scanning; audit logging disabled on vault. | -| **Medium** | Detection in CI only (no pre-commit); manual rotation process; excessive detection allowlists; token TTL mismatch; rotation not monitored; plaintext secrets in environment variables (vs. vault injection). | +| **High** | No centralized secrets manager; no rotation automation; long-lived static credentials for agents; real provider secrets exposed to untrusted agent contexts; broker with wildcard host/path injection; live validation with privileged side effects; secrets in CI logs; no git history scanning; audit logging disabled on vault. | +| **Medium** | Detection in CI only (no pre-commit); manual rotation process; excessive detection allowlists; approved canary tokens missing owner/expiry/alert proof; token TTL mismatch; missing broker audit/fallback evidence; rotation not monitored; plaintext secrets in environment variables (vs. vault injection). | | **Low** | Missing secret type documentation; secret naming convention inconsistencies; development-only secrets in non-.gitignored example files. | --- @@ -381,6 +445,22 @@ spec: | Gitleaks | Yes/No | Yes/No | Yes/No | Yes/No | Yes/No | | detect-secrets | Yes/No | Yes/No | Yes/No | N/A | Yes/No | +### Canary Token and Live Validation Review + +| Token Alias / Finding ID | Classification | Owner | No Production Privilege Evidence | Alert Route | Expiry | Decision | +|--------------------------|----------------|-------|----------------------------------|-------------|--------|----------| +| canary-aws-01 | Canary control / production leak / unknown | security-eng | Yes/No | soc-webhook | 2026-09-30 | Accept / rotate / investigate | + +| Scanner | Live Validation Enabled | Read-Only Probe | Values Redacted | Side-Effect Review | Rate Limit | Decision | +|---------|-------------------------|-----------------|-----------------|--------------------|------------|----------| +| TruffleHog | Yes/No | Yes/No | Yes/No | Yes/No | Yes/No | Accept / restrict / disable | + +### Agent Credential Exposure Review + +| Agent / Workflow | Content Sources | Exposure Model | Real Secret Visible to Agent | Broker Policy Evidence | Egress Policy | Decision | +|------------------|-----------------|----------------|------------------------------|------------------------|---------------|----------| +| repo-maintenance-agent | issues, repo files | broker token / raw secret / capability handle | Yes/No | host + path + method + audit | default-deny / default-allow | Accept / restrict / redesign | + ### Secrets Inventory (by type, NOT values) | Secret Type | Storage Method | Rotation Period | Automated | Last Rotated | @@ -442,6 +522,12 @@ spec: 4. **Ignoring secret sprawl across multiple secrets managers.** Large organizations often have Vault, AWS Secrets Manager, Azure Key Vault, and application-specific secret stores running simultaneously. Without a unified inventory, secrets expire unmonitored and rotation gaps emerge. Maintain a single source of truth for secret metadata (type, owner, rotation schedule, storage location). +5. **Treating short-lived real secrets as safe for prompt-exposed agents.** A 10-minute token can still be exfiltrated or abused if an agent can read untrusted content and make arbitrary outbound calls. Prefer broker tokens or capability handles where the real credential never enters the agent-visible context. + +6. **Allowlisting honeytokens without control evidence.** Canary tokens are useful only when ownership, alert routing, no-production-privilege evidence, expiry, and periodic revalidation are current. A broad allowlist with no evidence can hide a real leak. + +7. **Running live validation without safety boundaries.** Live checks should be read-only, redacted, rate-limited, and side-effect reviewed. Do not let validation tooling become a privileged credential-use path. + --- ## Prompt Injection Safety Notice @@ -466,10 +552,12 @@ This skill processes configuration files and code that may contain secret values - detect-secrets: https://github.com/Yelp/detect-secrets - HashiCorp Vault Documentation: https://developer.hashicorp.com/vault/docs - External Secrets Operator: https://external-secrets.io/ +- MongoDB Kingfisher - secret scanning and validation patterns: https://github.com/mongodb/kingfisher --- ## Changelog +- **1.0.2** -- Add brokered agent credential evidence, canary/honey token classification, and live-validation scanner safety gates. - **1.0.1** -- Add false positive filtering guidance: distinguish real secrets from placeholders/examples, verify entropy, scope findings to actual secrets (not architectural gaps). - **1.0.0** -- Initial release. Full coverage of OWASP Secrets Management Cheat Sheet and NIST SP 800-57 Part 1 Rev 5 for secrets management review.