@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/gemini-cli/security-rebac-design/SKILL.md

@@ -0,0 +1,154 @@
+# Relationship-Based Access Control
+
+> Model authorization as a graph of relationships -- "User X is an editor of Document Y which belongs to Folder Z owned by Team W" -- enabling inherited permissions that follow resource hierarchies
+
+## When to Use
+
+- Building a document management, file sharing, or collaborative editing system
+- Resources have complex ownership hierarchies (org -> team -> project -> resource)
+- Access depends on the relationship between the user and the specific resource, not just the user's global role
+- You need to answer "who can access this document?" efficiently (permission listing)
+- Google Docs-style sharing is a product requirement
+- RBAC or ABAC cannot naturally express hierarchical resource ownership
+
+## Threat Context
+
+IDOR (Insecure Direct Object Reference) is the most common authorization vulnerability because most systems check "can this user type do this operation?" (role check) but not "does this user have a relationship to this specific resource?" (object-level check). The 2021 Parler data scrape exploited the absence of object-level authorization -- sequential post IDs with no ownership check allowed bulk download of every post, including deleted ones with geolocation metadata. The 2019 First American Financial data exposure leaked 885 million mortgage documents because the application checked authentication but not document-to-user relationships.
+
+Google designed Zanzibar specifically to solve this class of vulnerability at scale: every access check resolves relationships in a globally consistent graph, ensuring that revoking a team's access to a folder immediately revokes access to all documents in that folder for all team members -- no stale permissions, no orphaned grants, no race conditions between revocation and access.
+
+## Instructions
+
+1. **Model resources and relationships as a graph.** Define object types (user, team, org, document, folder, project) and relationship types (owner, editor, viewer, member, parent). Store relationships as tuples: `(object, relation, subject)`. Examples:
+   - `(document:readme, editor, user:alice)` -- Alice is an editor of the readme document
+   - `(folder:docs, parent, document:readme)` -- The readme document belongs to the docs folder
+   - `(team:engineering, member, user:alice)` -- Alice is a member of the engineering team
+   - `(folder:docs, viewer, team:engineering)` -- The engineering team has viewer access to the docs folder
+
+   The tuple store is the single source of truth for all authorization relationships. Every permission in the system derives from tuples and composition rules -- no permission exists outside this model.
+
+2. **Define permission rules using relationship composition.** Permissions are computed by traversing relationships through the graph. A user can view a document if they are a direct viewer, OR an editor (editors can view), OR an owner (owners can edit and view), OR a viewer of the document's parent folder (inherited permission). Express this as composition rules:
+
+   ```
+   document#viewer = document#viewer
+                   + document#editor
+                   + document#owner
+                   + document#parent->folder#viewer
+   ```
+
+   This composition allows permissions to flow through the resource hierarchy without denormalization. When a team is granted viewer access to a folder, every team member automatically gains viewer access to every document in that folder -- without writing individual tuples for each document-member combination.
+
+3. **Implement check, expand, and list APIs.** Three core operations that the ReBAC system must support:
+   - **Check:** "Can user:alice view document:readme?" Traverses the relationship graph starting from the resource, following composition rules, and returns a boolean. This is the authorization gate called on every API request that accesses a resource.
+   - **Expand:** "What relationships does user:alice have to document:readme?" Returns all matching relations with the traversal path (e.g., "viewer via team:engineering membership and folder:docs inheritance"). Used for debugging authorization issues and for UX (showing why a user has access in a sharing panel).
+   - **List:** "Who can view document:readme?" Returns all subjects with the computed viewer permission. Used for sharing panels, audit logs, compliance reporting, and answering "who has access to sensitive data?" Also supports the reverse: "What can user:alice access?" for user-centric audit.
+
+4. **Ensure consistency on revocation.** When a team is removed from a folder, all members of that team must immediately lose access to all documents in that folder. This requires the relationship graph to be strongly consistent: writes (adding/removing tuples) must be immediately visible to subsequent reads (check calls).
+
+   Zanzibar uses a Zookie (opaque consistency token returned on writes, passed on subsequent reads) to guarantee "read your writes" consistency. SpiceDB provides ZedTokens with equivalent semantics. OpenFGA provides consistency tokens via its API. Without consistency guarantees, there is a time window after revocation where access checks still return "allow" -- meaning "eventually consistent authorization" is equivalent to "temporarily insecure."
+
+5. **Design the schema before writing tuples.** Define the type system: which object types exist, which relations each type supports, how relations compose into permissions, and which subject types can appear in each relation. This schema is the authorization model -- in SpiceDB it is a `.zed` schema file, in OpenFGA it is a JSON authorization model.
+
+   Validate the schema against test scenarios before deploying: enumerate known-good access patterns (Alice should be able to view her own documents) and known-bad access patterns (Bob should not be able to view Alice's private documents). Schema errors produce permission leaks that are extremely difficult to detect at runtime because the system silently grants access it should not.
+
+6. **Integrate with your API layer.** Every API endpoint that accesses or modifies a resource must call the ReBAC check API before proceeding. The check call includes three parameters: subject (authenticated user), resource (object being accessed, identified by type and ID), and permission (operation being performed: view, edit, delete, share). If the check returns deny, return HTTP 403. Never check permissions after performing the operation -- check before, and fail closed. Treat a failed check call (network error, timeout) as deny, not as allow.
+
+## Details
+
+### Google Zanzibar Paper Summary
+
+Published at USENIX ATC 2019, the Zanzibar paper describes Google's global authorization system that processes over 10 million authorization checks per second across all Google products (Drive, YouTube, Cloud, Maps, Photos, Calendar). Key innovations:
+
+- **Global consistency via Zookies:** Each relationship write returns an opaque token (Zookie) encoding the write timestamp. Passing the Zookie on subsequent check calls guarantees the read reflects all writes up to that point. This solves the "new enemy" problem where a permission is revoked but a stale cache serves the old allow result.
+
+- **Leopard indexing:** A specialized index structure for efficient reverse lookups ("who can access resource X?"). Forward lookups (can user Y access resource X?) follow the graph from X through composition rules. Reverse lookups require traversing all possible paths to X, which leopard indexing pre-computes and maintains incrementally.
+
+- **Namespace configuration:** A schema language for defining object types, relations, and permission computations. Each Google product defines its own namespace (Drive uses document/folder/team types; YouTube uses video/channel/playlist types) but shares the global infrastructure and consistency guarantees.
+
+- **Tuple format:** `(namespace:object_id#relation@subject_namespace:subject_id)` became the de facto standard adopted by all major open-source implementations.
+
+### Open-Source Implementations
+
+| System   | Creator    | API Protocol | Schema Language          | Standout Feature                                                              |
+| -------- | ---------- | ------------ | ------------------------ | ----------------------------------------------------------------------------- |
+| SpiceDB  | AuthZed    | gRPC + HTTP  | `.zed` (rich, validated) | Most mature schema language, watch API, caveats for conditional relations     |
+| OpenFGA  | Auth0/Okta | HTTP (REST)  | JSON authorization model | Contextual tuples (dynamic attributes), simple API, managed service available |
+| Ory Keto | Ory        | gRPC + REST  | Namespace configuration  | Part of Ory identity ecosystem (Kratos, Hydra, Oathkeeper)                    |
+
+SpiceDB has the most mature schema language, the best developer tooling (interactive playground, schema validation, integration testing framework), and the closest adherence to the Zanzibar model including consistency tokens and the watch API for real-time change streams. OpenFGA has the simplest integration path for web applications and offers a managed service via Auth0. All three support the core Zanzibar model of tuple storage, relationship traversal, and consistency guarantees.
+
+### Worked Example -- Google Docs-Style Sharing
+
+**Type definitions:**
+
+- `user` -- an individual person
+- `group` -- a set of users (relation: `member`)
+- `folder` -- a container for documents (relations: `owner`, `editor`, `viewer`)
+- `document` -- a file within a folder (relations: `owner`, `editor`, `viewer`, `parent` pointing to folder)
+
+**Permission composition rules:**
+
+```
+document#viewer = document#viewer
+               + document#editor
+               + document#owner
+               + document#parent->folder#viewer
+               + document#parent->folder#editor
+               + document#parent->folder#owner
+
+folder#viewer = folder#viewer + folder#editor + folder#owner
+```
+
+**Scenario:** Share the "Engineering" folder with the "Backend Team" group as viewers.
+
+**Tuples written:**
+
+- `(group:backend-team, member, user:alice)`
+- `(group:backend-team, member, user:bob)`
+- `(folder:engineering, viewer, group:backend-team#member)`
+- `(document:api-spec, parent, folder:engineering)`
+- `(document:architecture, parent, folder:engineering)`
+
+**Check: Can user:alice view document:api-spec?**
+Traversal path: `document:api-spec` -> `parent` -> `folder:engineering` -> `viewer` -> `group:backend-team#member` -> `user:alice`. Result: ALLOW.
+
+**Revocation: Remove Backend Team from Engineering folder.**
+Delete single tuple: `(folder:engineering, viewer, group:backend-team#member)`. Immediately, both Alice and Bob lose access to both api-spec and architecture documents. One tuple deletion revokes access for all group members to all documents in the folder hierarchy -- this is the power of graph-based permission inheritance versus denormalized permission tables.
+
+### When to Choose ReBAC Over RBAC or ABAC
+
+Use this decision framework to select the right authorization model:
+
+- **RBAC** is sufficient when: access depends on the user's role, resources do not have individual ownership semantics, and the number of role combinations is manageable (under 20-30 distinct roles).
+
+- **ABAC** is the right choice when: access depends on multiple contextual attributes (time, location, classification level), the same user should have different access to different instances of the same resource type based on resource properties, and policy rules change frequently without code changes.
+
+- **ReBAC** is the right choice when: resources form hierarchies (folders containing documents, teams within organizations), access to a resource depends on the user's relationship to that specific resource instance, permission inheritance through resource hierarchies is a core requirement, and you need to efficiently answer "who can access this?" and "what can this user access?"
+
+Many production systems combine models: RBAC at the feature/module level ("engineers can access the code review tool"), ABAC for contextual constraints ("only during business hours from managed devices"), and ReBAC for resource-level authorization ("Alice can edit this document because she is a member of the owning team").
+
+### Performance and Scaling
+
+ReBAC checks require graph traversal, and deep or wide hierarchies create performance challenges that must be addressed:
+
+- **Depth limits:** Set a maximum traversal depth (typically 10-15 levels) to prevent runaway graph walks on pathological hierarchies. Most real-world resource hierarchies are 3-5 levels deep (org -> team -> project -> folder -> document).
+
+- **Caching:** Cache intermediate traversal results with short TTLs (seconds, not minutes). Authorization caches with long TTLs create security windows where revoked permissions are still granted. SpiceDB's watch API enables push-based cache invalidation when tuples change, allowing tighter cache consistency.
+
+- **Pre-computation:** For frequently checked permissions (e.g., "can this user access the dashboard?"), pre-compute the result and store it. Invalidate on tuple changes that affect the computation path. This trades storage and write-time computation for read-time speed.
+
+- **Sharding:** Shard the tuple store by namespace or object type. Documents and folders can be in separate shards with cross-shard lookups for hierarchy traversal. SpiceDB supports horizontal sharding with consistent hashing.
+
+- **Batching:** When rendering a list of documents, batch all permission checks into a single request (`BulkCheckPermission` in SpiceDB, batch check in OpenFGA) rather than issuing one check per document. A document listing page showing 50 items should make 1 batch check call, not 50 individual calls.
+
+## Anti-Patterns
+
+1. **Implementing ReBAC by querying a relational database with recursive CTEs.** While technically possible, recursive SQL queries for authorization graph traversal do not scale, cannot provide the consistency guarantees needed for real-time authorization, and are extremely difficult to reason about for correctness. A subtle error in a recursive CTE silently grants or denies access incorrectly. Use a purpose-built ReBAC engine that handles traversal, caching, and consistency natively.
+
+2. **No consistency guarantees on revocation.** If a relationship write (revoke team access to folder) is not immediately visible to subsequent check calls, there is a window where revoked users can still access resources. This is not a theoretical concern -- eventual consistency in authorization means "eventually secure," which means "currently insecure." Use consistency tokens (ZedTokens, Zookies) or ensure linearizable reads.
+
+3. **Over-flattening the hierarchy.** Storing direct permission tuples on every leaf document (`document:X, viewer, user:Y` for every document in every folder for every user) instead of modeling the folder hierarchy through parent relations. This denormalization makes granting easy (write one tuple) but makes revocation O(N) -- revoking folder access requires finding and deleting tuples from every document in the folder. The fundamental value of ReBAC is hierarchical inheritance through graph traversal.
+
+4. **No schema validation before deployment.** Writing ad-hoc tuples without a validated schema leads to inconsistent relationship names (is it "viewer" or "read" or "can_view"?), orphaned tuples referencing deleted objects, and permission composition rules that silently fail because the relation name in the rule does not match the relation name in the stored tuples. Define the schema first, validate it against test scenarios, and enforce it on every tuple write.
+
+5. **Ignoring the "list" and "expand" queries.** Many implementations focus solely on the "check" operation (can user X access resource Y?) but neglect "list" (who can access resource Y?) and "expand" (why can user X access resource Y?). Check is the authorization gate. List is essential for sharing UIs ("show me who has access"), compliance auditing ("who can access PII?"), and data governance. Expand is essential for support ("why does this contractor have access to production data?") and debugging. All three operations are required for a production-grade system.

package/dist/agents/skills/gemini-cli/security-rebac-design/skill.yaml

@@ -0,0 +1,39 @@
+name: security-rebac-design
+version: '1.0.0'
+description: Relationship-based access control using the Zanzibar model -- modeling authorization as a graph of relationships between subjects and resources
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-rbac-design
+  - security-abac-design
+  - security-capability-based-security
+  - owasp-idor-prevention
+  - owasp-auth-patterns
+stack_signals: []
+keywords:
+  - ReBAC
+  - relationship-based access control
+  - Zanzibar
+  - SpiceDB
+  - OpenFGA
+  - authorization graph
+  - permission model
+  - Google Zanzibar
+  - tuple-based authorization
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/security-sbom-provenance/SKILL.md

@@ -0,0 +1,157 @@
+# SBOM and Build Provenance
+
+> Know exactly what is in your software (SBOM) and prove how it was built (provenance) -- because
+> you cannot secure what you cannot inventory
+
+## When to Use
+
+- Responding to a new CVE and need to know which deployments include the affected library
+- Meeting regulatory requirements for software transparency (US Executive Order 14028, EU Cyber
+  Resilience Act)
+- Implementing SLSA (Supply-chain Levels for Software Artifacts) to harden the build pipeline
+- Publishing software to customers who require SBOMs as part of procurement
+- Auditing the software supply chain for compliance or security review
+- Investigating whether a compromised upstream dependency is present in your deployed artifacts
+
+## Threat Context
+
+The 2021 US Executive Order 14028 on Improving Cybersecurity requires SBOMs for software sold to
+the federal government. The EU Cyber Resilience Act extends similar requirements to all software
+sold in the EU market. Beyond compliance, SBOMs enable rapid vulnerability response: when
+Log4Shell (CVE-2021-44228) dropped in December 2021, organizations with SBOMs identified all
+affected applications in minutes. Organizations without SBOMs spent days to weeks manually
+searching codebases, build artifacts, and container images -- many discovered affected deployments
+only after active exploitation was detected.
+
+Build provenance addresses the SolarWinds-class attack: the SUNBURST backdoor was injected into
+a legitimate build artifact by compromising the build pipeline. The signed, "trusted" artifact
+contained malicious code. Code signing alone could not detect this because the signing happened
+after the injection. SLSA provenance proves that an artifact was built from a specific source
+commit, on a specific build system, using a specific build process. Without provenance, a
+compromised CI system can produce arbitrary artifacts and no consumer can detect the tampering.
+
+The combination of SBOM (what is in the artifact) and provenance (how the artifact was built)
+forms the foundation of software supply chain security. Neither alone is sufficient.
+
+## Instructions
+
+1. **Generate SBOMs as part of the build process.** Use SPDX or CycloneDX format -- both are ISO
+   standards with broad tooling support. Tools for SBOM generation: `syft` (Anchore, generates
+   SBOMs for containers and filesystems), `cdxgen` (CycloneDX generator supporting 20+
+   ecosystems), `spdx-sbom-generator` (SPDX native), `trivy sbom` (Aqua Security, combined
+   vulnerability scanning and SBOM generation). Generate the SBOM in CI at the same build step
+   that produces the artifact. Store the SBOM alongside the artifact -- they are a pair.
+
+2. **Include both direct and transitive dependencies.** An SBOM that lists only direct
+   dependencies misses approximately 90% of the dependency tree. A vulnerability in a transitive
+   dependency is just as exploitable as one in a direct dependency. Use tools that resolve the
+   full dependency graph. For each component include: package name, exact version, license,
+   supplier, and package URL (purl) for unambiguous identification across ecosystems.
+
+3. **Implement SLSA build provenance.** SLSA defines four levels of supply chain security. Level
+   1: the build process is documented. Level 2: the build service generates provenance
+   attestations automatically. Level 3: the build service is hardened and provenance is
+   unforgeable (the build service, not the developer, generates the attestation). Level 4: all
+   dependencies are recursively verified with hermetic, reproducible builds. Start with SLSA L1
+   (document the build process), move to L2 (use GitHub Actions with `slsa-github-generator` or
+   Sigstore to generate signed provenance), then plan for L3 (hardened build service with
+   non-falsifiable provenance).
+
+4. **Sign provenance attestations.** Use in-toto attestations (the CNCF standard for build
+   provenance) signed with Sigstore (keyless signing using OIDC identity). The attestation binds
+   the artifact (by cryptographic digest) to the source commit, builder identity, and build
+   parameters. Consumers verify the attestation to confirm the artifact was built from the
+   expected source by the expected builder. Without signing, provenance attestations can be
+   forged by anyone with write access to the artifact store.
+
+5. **Store and distribute SBOMs alongside artifacts.** Attach SBOMs to container images as OCI
+   artifacts using `oras`, `cosign attach sbom`, or `docker buildx` with attestation support.
+   Publish SBOMs to a central management platform (Dependency-Track, GUAC) for organization-wide
+   visibility. Make SBOMs available to customers and auditors upon request -- this is a
+   regulatory requirement in many jurisdictions, not a courtesy.
+
+6. **Use SBOMs for continuous vulnerability management.** Ingest SBOMs into a vulnerability
+   management tool (Dependency-Track, Grype, Trivy) that correlates SBOM components against
+   vulnerability databases (NVD, OSV, GitHub Advisory Database). When a new CVE is published,
+   immediately identify all affected artifacts across the organization and prioritize patching
+   based on exposure and severity. This turns vulnerability response from a manual search into an
+   automated query.
+
+7. **Verify provenance before deployment.** Integrate provenance verification into the deployment
+   pipeline. In Kubernetes, use Kyverno or Sigstore policy-controller to verify SLSA provenance
+   at admission time. Reject artifacts that lack provenance or whose provenance does not match
+   the expected builder identity and source repository. Generating provenance without verifying
+   it provides no security benefit.
+
+## Details
+
+- **SPDX vs CycloneDX comparison**: SPDX (Linux Foundation, ISO/IEC 5962:2021) is the more
+  mature format with strong license compliance features. It supports documents, packages, files,
+  and relationships. CycloneDX (OWASP) is newer and more security-focused, with native support
+  for vulnerability correlation, services, and formulation (build provenance). Both are valid
+  choices. For security-focused SBOM work, CycloneDX has better tooling integration. For license
+  compliance, SPDX is more established. Many organizations generate both formats from the same
+  source data.
+
+- **SLSA levels in practice**: Most organizations should target SLSA L2 immediately -- it
+  requires only that the build service generates signed provenance, which GitHub Actions and
+  Google Cloud Build support natively. SLSA L3 requires that the build service is hardened such
+  that insiders and project maintainers cannot influence the provenance generation -- this
+  typically requires using an isolated build service like Google Cloud Build or the SLSA GitHub
+  generator (which runs in a reusable workflow the project cannot modify). SLSA L4 (hermetic,
+  reproducible builds with recursive dependency verification) is aspirational for most
+  organizations and primarily relevant for critical infrastructure software.
+
+- **in-toto framework**: Defines a "supply chain layout" that specifies which steps are allowed,
+  who performs them, and what artifacts each step produces. Each step generates a "link"
+  attestation signed by the step's functionary. The final verification checks that all required
+  steps were performed by authorized actors and that artifact digests chain correctly from source
+  to final artifact. This provides end-to-end verification of the entire build process, not just
+  the final signing step.
+
+- **GUAC (Graph for Understanding Artifact Composition)**: An open-source project (Google-led)
+  that ingests SBOMs, SLSA attestations, and vulnerability data into a graph database. Enables
+  queries like "which of my deployed artifacts are affected by CVE-2021-44228?" and "what is the
+  full dependency chain from this artifact to the vulnerable library?" GUAC provides the
+  queryable intelligence layer on top of raw SBOM and provenance data.
+
+- **Package URL (purl) specification**: A standardized format for identifying software packages
+  across ecosystems: `pkg:npm/%40angular/core@16.0.0`, `pkg:pypi/requests@2.31.0`,
+  `pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1`. Using purls in SBOMs enables
+  unambiguous cross-ecosystem vulnerability correlation. Without purls, matching "lodash 4.17.21"
+  in an SBOM to a CVE advisory requires ecosystem-specific logic.
+
+## Anti-Patterns
+
+1. **Generating SBOMs only on demand.** An SBOM generated after a CVE is discovered requires
+   re-running the build analysis on the deployed version, which may not be reproducible weeks or
+   months later. Dependencies may have changed, lock files may have been updated, and the exact
+   build environment may no longer exist. Generate SBOMs in CI for every release and store them
+   as permanent artifacts alongside the build output.
+
+2. **SBOMs without version specificity.** An SBOM that lists "lodash" without a version, or
+   "log4j" without distinguishing between log4j-core and log4j-api, is useless for vulnerability
+   correlation. Every component must include an exact version and ideally a package URL (purl)
+   for unambiguous identification across vulnerability databases.
+
+3. **Provenance without verification.** Generating SLSA provenance but never verifying it before
+   deployment is security theater. The provenance exists, the compliance checkbox is checked, but
+   the deployment pipeline accepts any artifact regardless. Integrate provenance verification
+   into admission control so that unverified artifacts are rejected.
+
+4. **Treating SBOM as a one-time compliance artifact.** Generating an SBOM once per year for an
+   audit captures a snapshot that is stale within days. Vulnerability databases update daily with
+   newly disclosed CVEs. SBOMs should be generated for every build and continuously correlated
+   against current vulnerability data.
+
+5. **No SBOM for container base images.** The base image (Debian, Alpine, Ubuntu) often contains
+   more OS packages than the application layer. A vulnerability in a base image library (OpenSSL,
+   glibc, zlib) affects every application built on that image. Include base image components in
+   the SBOM, or layer the application SBOM on top of the base image SBOM. Tools like Syft and
+   Trivy scan the full container filesystem, capturing both layers.
+
+6. **Confusing SBOM with dependency lock files.** A lock file (package-lock.json, Pipfile.lock)
+   records direct and transitive dependency versions for reproducible builds. An SBOM is a
+   broader document that includes license information, supplier data, component relationships,
+   and can cover non-package components (OS libraries, configuration files, embedded firmware).
+   Lock files are a build tool input; SBOMs are a security and compliance output.

package/dist/agents/skills/gemini-cli/security-sbom-provenance/skill.yaml

@@ -0,0 +1,39 @@
+name: security-sbom-provenance
+version: '1.0.0'
+description: Software bill of materials, SLSA framework, and build provenance -- proving what went into your software and how it was built
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-dependency-auditing
+  - security-code-signing
+  - security-ci-security-testing
+  - owasp-dependency-security
+stack_signals: []
+keywords:
+  - SBOM
+  - software bill of materials
+  - SLSA
+  - build provenance
+  - supply chain security
+  - SPDX
+  - CycloneDX
+  - attestation
+  - in-toto
+  - artifact integrity
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/security-secrets-lifecycle/SKILL.md

@@ -0,0 +1,190 @@
+# Secrets Lifecycle
+
+> Secrets are born (generated), distributed (delivered to consumers), rotated (replaced on
+> schedule), and die (revoked and destroyed) -- manage every phase or the secret manages you
+
+## When to Use
+
+- Designing how an application retrieves database credentials, API keys, or encryption keys
+- Establishing a secret rotation policy for a production system
+- Responding to a secret exposure (leaked in logs, committed to Git, visible in error
+  messages)
+- Choosing between static secrets, dynamic secrets, and short-lived tokens
+- Auditing an existing system for secret management gaps
+- Evaluating secrets managers (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager)
+
+## Threat Context
+
+Exposed secrets are the most common initial access vector in cloud breaches. The attack
+surface is vast and the consequences are immediate:
+
+- **GitHub secret exposure scale**: GitHub's 2023 secret scanning report found 12+ million
+  secrets exposed in public repositories in a single year. Automated bots scan every public
+  commit within seconds of push -- the median time from commit to attacker exploitation of
+  an exposed AWS key is under 1 minute.
+- **Uber breach (2022)**: Began with hardcoded credentials discovered in a PowerShell script
+  on an internal network share. The attacker used these credentials to access Uber's AWS,
+  GCP, and internal Slack environments.
+- **CircleCI breach (2023)**: Attackers compromised CircleCI's secrets management
+  infrastructure itself, exposing customer secrets stored in the platform. This demonstrates
+  that even the secrets manager is a high-value target.
+- **Codecov supply chain attack (2021)**: Attackers modified a bash uploader script to
+  exfiltrate environment variables (containing secrets) from CI/CD environments to an
+  attacker-controlled server.
+
+Secrets have a lifecycle -- generation, distribution, usage, rotation, and revocation -- and
+failure at any single phase is a breach waiting to happen. A secret that is generated
+securely but never rotated accumulates exposure risk over time. A secret that is rotated
+regularly but distributed through insecure channels is exposed at every rotation.
+
+## Instructions
+
+1. **Generate secrets with sufficient entropy.** API keys, tokens, and passwords must
+   contain minimum 256 bits of randomness from a cryptographically secure pseudorandom
+   number generator (CSPRNG). Use `crypto.randomBytes(32)` in Node.js,
+   `secrets.token_hex(32)` in Python, `SecureRandom` in Java, or `/dev/urandom` on Unix.
+   Database passwords should be 32+ random characters (letters, digits, symbols). Encryption
+   keys must be generated using the crypto library's dedicated key generation function, not
+   by hashing a passphrase (unless using a proper KDF like Argon2id with appropriate
+   parameters -- see `security-credential-storage`).
+
+2. **Distribute secrets through a secrets manager, never through code or config files.** Use
+   HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or Kubernetes
+   Secrets (with envelope encryption via a KMS). Applications retrieve secrets at startup or
+   on-demand via authenticated API calls to the secrets manager. The application
+   authenticates to the secrets manager using platform identity (IAM roles, Kubernetes
+   service accounts, Vault AppRole) -- not with another static secret. Secrets must never be
+   committed to version control, embedded in Docker images, passed as build arguments, or
+   included in deployment manifests.
+
+3. **Use dynamic secrets when possible.** Instead of a static database password that lives
+   forever, use Vault's database secrets engine (or equivalent) to generate short-lived
+   credentials with a TTL of 1 hour per application instance. When the TTL expires, the
+   credential is automatically revoked at the database level. This eliminates long-lived
+   secrets entirely -- there is nothing to rotate because every credential is born with a
+   death date. Dynamic secrets are available for databases (PostgreSQL, MySQL, MongoDB),
+   cloud providers (AWS STS, GCP service account keys), and PKI certificates.
+
+4. **Rotate static secrets on a mandatory schedule.** When dynamic secrets are not feasible,
+   static secrets must be rotated periodically: 90 days maximum for high-sensitivity secrets
+   (database root credentials, encryption keys, signing keys), 365 days for low-sensitivity
+   secrets (monitoring API keys). Implement dual-read rotation to avoid downtime:
+   (a) generate new secret B while secret A is still active, (b) configure all consumers to
+   accept both A and B, (c) switch producers to emit B, (d) verify via audit logs that no
+   traffic uses A, (e) revoke A. Automate this process -- manual rotation is forgotten
+   rotation.
+
+5. **Revoke secrets immediately upon any exposure.** If a secret appears in a log file,
+   error message, Git commit, Slack message, support ticket, or any unintended location,
+   treat it as compromised. Do not assess whether "anyone noticed" -- assume the worst.
+   Revocation procedure: (a) revoke the secret at the source (delete the API key, change the
+   password, rotate the certificate), (b) generate a new secret and distribute it through
+   the secrets manager, (c) audit access logs from the moment of exposure to determine if
+   the secret was exploited, (d) investigate and fix the root cause of the exposure, (e) add
+   detection to prevent recurrence (pre-commit hooks, log scrubbing).
+
+6. **Audit all secret access.** The secrets manager must log every access event: who
+   requested the secret, when, from which IP/service, and whether the request was granted or
+   denied. Configure alerts for anomalies: access from unknown IP ranges, access frequency
+   spikes, access to secrets outside the caller's normal pattern, and any access to
+   high-sensitivity secrets (root credentials, encryption keys). Audit logs from the secrets
+   manager are themselves sensitive and must be stored in a tamper-evident,
+   access-controlled location (see `security-audit-log-design`).
+
+7. **Scope secrets to minimum blast radius.** Each service or application instance should
+   have its own credentials. Do not share a single database password across 10
+   microservices -- if one service is compromised, the attacker has access to the database
+   with the privileges of all 10 services. Service-specific credentials enable targeted
+   revocation: revoke the compromised service's credentials without disrupting the other 9.
+   Apply the principle of least privilege to secret scope: a service that only reads from the
+   database should have read-only credentials, not read-write.
+
+## Details
+
+- **The secret exposure cascade**: A leaked AWS access key committed to a public GitHub
+  repository triggers a predictable cascade. Automated bots (scanning every public commit
+  via GitHub's Events API) detect the key within seconds. The attacker uses the key to call
+  `sts:GetCallerIdentity` to identify the account, then `iam:ListUsers`,
+  `s3:ListBuckets`, and `ec2:DescribeInstances` to enumerate resources. Data is exfiltrated
+  from S3 buckets. EC2 instances are launched for cryptomining. The entire cascade can
+  complete within 10 minutes of the commit. Response must be: (1) revoke the key immediately
+  via `aws iam delete-access-key`, (2) audit CloudTrail for all API calls made with the key
+  since the commit timestamp, (3) rotate all credentials the leaked key could access,
+  (4) check for persistence mechanisms the attacker may have installed (new IAM users,
+  Lambda functions, EC2 instances), (5) add pre-commit hooks (truffleHog, git-secrets,
+  gitleaks) and enable GitHub push protection to prevent recurrence.
+
+- **Dual-read rotation pattern in practice**: Step 1: Generate new database password B.
+  Step 2: Execute `ALTER USER app_user SET PASSWORD = B` but also keep A valid (PostgreSQL
+  allows this via connection pooler configuration or multiple valid passwords in some
+  setups; alternatively, create a new database user with B and grant identical permissions).
+  Step 3: Update the secrets manager to serve B. Step 4: Applications pick up B on their
+  next secret refresh (within the refresh interval, typically 5-15 minutes). Step 5: Monitor
+  audit logs to confirm no connections use A. Step 6: Revoke A (drop the old user or change
+  the password). The critical principle: there must never be a moment when neither A nor B
+  is valid.
+
+- **Short-lived tokens vs static secrets -- a hierarchy of preference**: Prefer (from best
+  to worst): (1) Dynamic secrets with automatic TTL and revocation (Vault database secrets
+  engine, AWS STS temporary credentials), (2) OAuth2 access tokens with 1-hour TTL and
+  refresh tokens, (3) Platform-managed rotating credentials (AWS RDS IAM authentication,
+  GCP Cloud SQL IAM authentication), (4) Static secrets with automated rotation on a 90-day
+  schedule, (5) Static secrets with manual rotation (worst case, requires process
+  discipline). Each level down the hierarchy increases the window of opportunity for a
+  compromised credential.
+
+- **Pre-commit secret scanning**: Tools: truffleHog (entropy-based and regex-based
+  detection), git-secrets (AWS-focused patterns), gitleaks (broad pattern library), GitHub's
+  built-in push protection (blocks pushes containing known secret formats for supported
+  providers). Configure as both a local pre-commit hook (catches secrets before they reach
+  the remote) and a CI check (catches secrets that bypass local hooks). Block commits
+  containing high-entropy strings matching known secret patterns: AWS keys (prefix `AKIA`),
+  GitHub tokens (`ghp_`, `gho_`, `ghs_`), Slack tokens (`xoxb-`, `xoxp-`), private keys
+  (`-----BEGIN RSA PRIVATE KEY-----`). Maintain an allowlist for false positives (test
+  fixtures, documentation examples with dummy values).
+
+## Anti-Patterns
+
+1. **Secrets in source code or version control.** Once committed, a secret persists in Git
+   history even after deletion from HEAD. Every clone of the repository contains the secret
+   in its history. Removing it requires `git filter-repo` or BFG Repo Cleaner to rewrite
+   history, followed by force-pushing -- and even then, any existing clone or fork retains
+   the secret. Always treat a committed secret as compromised regardless of how quickly it
+   was removed.
+
+2. **Shared credentials across services and environments.** Production and staging sharing
+   the same database password. Multiple microservices using the same API key. A single
+   "admin" password for all team members. Compromise of any one consumer compromises all
+   consumers. Incident response requires rotating the shared credential and redeploying
+   every consumer simultaneously -- an operational nightmare that delays response.
+
+3. **Never-rotated secrets.** A database password created in 2019 and never rotated has had
+   5+ years of potential exposure windows: developer laptops, CI/CD logs, backup tapes,
+   departed employees' password managers. The longer a secret lives, the more opportunities
+   for undetected exposure. Establish rotation schedules, automate them, and alert on
+   overdue rotations.
+
+4. **Secrets in environment variables without a secrets manager.** Environment variables are
+   visible in process listings (`/proc/PID/environ` on Linux), crash dumps, debugging tools
+   (`docker inspect`), container orchestration dashboards, and CI/CD build logs. They are
+   better than hardcoding in source but far worse than a proper secrets manager. Use a
+   secrets manager to inject secrets directly into the application's memory at startup,
+   bypassing the environment entirely.
+
+5. **Logging secrets accidentally.** Application logs that include full HTTP request/response
+   bodies (containing Authorization headers or API keys), error messages that dump
+   configuration objects (containing database connection strings), and debug logging that
+   prints environment variables. Implement structured logging with explicit field selection
+   (log only what you intend), add log scrubbing for known secret patterns, and never log
+   request bodies containing authentication credentials.
+
+6. **Secrets in CI/CD pipeline definitions.** Storing secrets as plaintext variables in
+   GitHub Actions workflow files, Jenkins pipeline scripts, or GitLab CI YAML. Use the CI
+   platform's encrypted secrets feature (GitHub Actions secrets, GitLab CI/CD variables
+   marked as "masked" and "protected") and ensure secrets are not echoed in build logs.
+
+7. **Using the same secret for authentication and encryption.** An API key used for both
+   authenticating to a service and encrypting data at rest. If the authentication use case
+   exposes the key (via logs, network capture), the encryption is also compromised. Use
+   separate secrets for separate purposes -- key separation is a fundamental cryptographic
+   principle.

package/dist/agents/skills/gemini-cli/security-secrets-lifecycle/skill.yaml

@@ -0,0 +1,39 @@
+name: security-secrets-lifecycle
+version: "1.0.0"
+description: Secret rotation, distribution, revocation, and the principle that secrets must be ephemeral, auditable, and never embedded in code
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-vault-patterns
+  - security-environment-variable-risks
+  - security-credential-storage
+  - security-symmetric-encryption
+  - owasp-secrets-management
+stack_signals: []
+keywords:
+  - secrets management
+  - secret rotation
+  - API keys
+  - credentials
+  - vault
+  - KMS
+  - secret distribution
+  - revocation
+  - ephemeral secrets
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []