mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 05:28:02 +03:00
David Abutbul
26af277afd
* feat(hermes-attestation-guardian): release v0.0.2 hardening * docs(wiki): add v0.0.2 hardening update note * docs: add Hermes support coverage to README and compatibility report * fix(hermes-attestation-guardian): address baz review on crontab detection and doc dedup * feat(wiki): add PR-200 skill feature/platform matrix * docs(wiki): rewrite PR-200 matrix as narrative capability mapping * docs(readme): add skill feature matrix with requested headers * docs(readme): replace unknowns with mapped yes/no feature matrix * docs: move NanoClaw and CI/CD details from README to wiki modules * docs(readme): remove platform/suite sections and keep wiki module pointers * docs(readme): refresh project structure to match current repo * feat(hermes-attestation-guardian): add signed advisory feed verification pipeline * feat(hermes-attestation-guardian): add advisory-gated guarded skill verification * feat(hermes-attestation-guardian): add advisory scheduler helper and phase-3 parity docs * docs(wiki): expand hermes attestation guardian capability coverage * fix(pr-200): address Baz review findings across Hermes parity rollout * test(sandbox): extend Hermes regression to cover feed, guarded verify, and advisory scheduler * fix(pr-200): address Baz semver parsing and feed-state fallback visibility * fix(ci): suppress shellcheck false positives in sandbox inline docker script * fix(hermes-attestation-guardian): fail closed on unsupported advisory ranges * fix(hermes-attestation-guardian): restore safe install verdict in sandbox * fix(sandbox): capture guarded verify exit under set -e * fix(semver): fail closed on malformed affected specifiers * docs(readme): clarify hermes capability matrix wording * refactor(feed): share signed artifact verification flow * refactor(cron): share managed block helpers across setup scripts * fix(feed): require checksum manifest artifacts when enabled * chore(hermes-skill): relocate sandbox test, refresh docs, and add v0.1.0 release notes * chore(docs): remove remaining hermes parity plan file * chore(release): roll hermes-attestation-guardian to v0.1.0 * chore(release): remove standalone v0.1.0 release notes file * docs(hermes): update README status to v0.1.0 --------- Co-authored-by: David Abutbul <David.a@prompt.security>
142 lines
6.6 KiB
Markdown
142 lines
6.6 KiB
Markdown
# Module: Automation and Release Pipelines
|
|
|
|
## Responsibilities
|
|
- Enforce repository quality/security checks before merge and deployment.
|
|
- Generate and maintain advisory feed updates from automated and community sources.
|
|
- Package, sign, and publish skill release artifacts from tag events.
|
|
- Build and deploy static website outputs and mirrored release/advisory assets.
|
|
|
|
## CI/CD Summary (migrated from README)
|
|
|
|
### Automated workflows
|
|
The canonical CI/CD workflow matrix (triggers + responsibilities) is maintained in `CLAUDE.md` under "CI Workflows".
|
|
|
|
This module intentionally focuses on automation/release-specific workflow behavior and operational details. Additional module-relevant workflows not listed in the core matrix include:
|
|
- `pages-verify.yml` (PR-only Pages build/signing verification without publish)
|
|
- `wiki-sync.yml` (syncs repository `wiki/` content to GitHub Wiki)
|
|
|
|
### Skill release pipeline behavior
|
|
When a skill is tagged (for example, `soul-guardian-v1.0.0`), the pipeline:
|
|
1. Validates `skill.json` version/tag alignment.
|
|
2. Enforces signing-key consistency against canonical repo key material.
|
|
3. Generates `checksums.json` for SBOM files.
|
|
4. Signs and verifies release checksum artifacts.
|
|
5. Publishes GitHub Release assets.
|
|
6. Supersedes older releases within the same major version (tags remain).
|
|
7. Triggers website catalog refresh.
|
|
|
|
### Signing-key consistency guardrails
|
|
Guardrail script:
|
|
- `scripts/ci/verify_signing_key_consistency.sh`
|
|
|
|
Enforced in:
|
|
- `.github/workflows/skill-release.yml`
|
|
- `.github/workflows/deploy-pages.yml`
|
|
|
|
### Release versioning and superseding
|
|
- New patch/minor release: previous releases in same major line are removed.
|
|
- New major release: latest release from previous major line is retained for compatibility.
|
|
- Git tags are preserved and can be used to recreate releases when needed.
|
|
|
|
### Release artifacts
|
|
Each skill release includes:
|
|
- `checksums.json`
|
|
- `skill.json`
|
|
- `SKILL.md`
|
|
- Additional SBOM-scoped files
|
|
|
|
Operational docs:
|
|
- `wiki/security-signing-runbook.md`
|
|
- `wiki/migration-signed-feed.md`
|
|
|
|
## Key Files
|
|
- `.github/workflows/ci.yml`: lint/type/build/security/test matrix.
|
|
- `.github/workflows/pages-verify.yml`: PR-only Pages build/signing verification (no publish).
|
|
- `.github/workflows/poll-nvd-cves.yml`: daily NVD advisory ingestion.
|
|
- `.github/workflows/community-advisory.yml`: issue-label-driven advisory publishing.
|
|
- `.github/workflows/skill-release.yml`: release validation, packaging, signing, and publishing.
|
|
- `.github/workflows/deploy-pages.yml`: site build + asset mirroring to GitHub Pages.
|
|
- `.github/workflows/wiki-sync.yml`: syncs repository `wiki/` into GitHub Wiki.
|
|
- `.github/actions/sign-and-verify/action.yml`: shared Ed25519 sign/verify composite action.
|
|
- `scripts/prepare-to-push.sh`: local CI-like quality gate.
|
|
- `scripts/release-skill.sh`: manual helper for version bump + tag workflow.
|
|
|
|
## Public Interfaces
|
|
| Interface | Trigger | Outcome |
|
|
| --- | --- | --- |
|
|
| CI workflow | Push/PR on `main` | Fails fast on lint/type/build/test/security regressions. |
|
|
| Pages Verify workflow | PR on `main` | Validates Pages build/signing artifacts without production deploy. |
|
|
| NVD poll workflow | Cron + dispatch | Updates advisory feed with deduped, normalized CVEs. |
|
|
| Community advisory workflow | Issue labeled `advisory-approved` | Opens PR adding signed advisory records. |
|
|
| Skill release workflow | Metadata PR changes + tag `<skill>-v*` | PR dry-run/version checks and tagged release publishing. |
|
|
| Deploy pages workflow | Successful CI/release run | Publishes site + mirrored artifacts to Pages. |
|
|
| Sync wiki workflow | Push `wiki/**` on `main` | Publishes repository wiki content into GitHub Wiki remote. |
|
|
|
|
## Inputs and Outputs
|
|
Inputs/outputs are summarized in the table below.
|
|
|
|
| Type | Name | Location | Description |
|
|
| --- | --- | --- | --- |
|
|
| Input | Git refs/events | GitHub Actions event payloads | Determines which workflow path runs. |
|
|
| Input | Skill metadata/SBOM | `skills/*/skill.json` | Drives release asset assembly and validation. |
|
|
| Input | NVD API data | External API responses | Source CVEs for advisory feed generation. |
|
|
| Input | Signing secrets | GitHub Secrets | Private key material for signing artifacts. |
|
|
| Output | Signed advisories | `advisories/feed.json(.sig)` + mirrored public files | Consumable signed feed channel. |
|
|
| Output | Skill release assets | `release-assets/*` and GitHub release attachments | Installable and verifiable skill artifacts. |
|
|
| Output | Website build | `dist/` deployment artifact | Public web frontend and mirrors. |
|
|
|
|
## Configuration
|
|
| Config Point | Location | Notes |
|
|
| --- | --- | --- |
|
|
| Workflow schedules | `poll-nvd-cves.yml`, `codeql.yml`, `scorecard.yml` | Daily/weekly security automation cadence. |
|
|
| Concurrency groups | Workflow `concurrency` blocks | Prevents destructive overlap in key pipelines. |
|
|
| Signing key checks | `scripts/ci/verify_signing_key_consistency.sh` | Ensures docs and canonical PEM files align. |
|
|
| Local pre-push gating | `scripts/prepare-to-push.sh` | Mirrors CI checks with optional auto-fix. |
|
|
|
|
## Example Snippets
|
|
```yaml
|
|
# skill release trigger pattern
|
|
on:
|
|
push:
|
|
tags:
|
|
- '*-v[0-9]*.[0-9]*.[0-9]*'
|
|
```
|
|
|
|
```bash
|
|
# local all-in-one pre-push gate
|
|
./scripts/prepare-to-push.sh
|
|
# optional auto-fix
|
|
./scripts/prepare-to-push.sh --fix
|
|
```
|
|
|
|
## Edge Cases
|
|
- NVD API rate limiting (`403`/`429`) is handled with retry/backoff and can fail workflow on persistent errors.
|
|
- Release pipeline blocks on version mismatch between `skill.json` and `SKILL.md` frontmatter.
|
|
- Key fingerprint drift between canonical PEM files and docs hard-fails signing-related workflows.
|
|
- Deploy workflow intentionally allows unsigned legacy checksums for backward compatibility in some branches.
|
|
- Manual helper script has safety checks but includes destructive rollback logic in error branches; use carefully.
|
|
|
|
## Tests
|
|
| Validation Layer | Location |
|
|
| --- | --- |
|
|
| Workflow execution tests | CI jobs in `.github/workflows/ci.yml` |
|
|
| Skill-level unit/property tests | `skills/*/test/*.test.mjs` invoked by CI |
|
|
| Local deterministic checks | `scripts/prepare-to-push.sh` |
|
|
| Release link checks | `scripts/validate-release-links.sh` |
|
|
|
|
## Source References
|
|
- .github/workflows/ci.yml
|
|
- .github/workflows/poll-nvd-cves.yml
|
|
- .github/workflows/community-advisory.yml
|
|
- .github/workflows/skill-release.yml
|
|
- .github/workflows/deploy-pages.yml
|
|
- .github/workflows/pages-verify.yml
|
|
- .github/workflows/wiki-sync.yml
|
|
- .github/workflows/codeql.yml
|
|
- .github/workflows/scorecard.yml
|
|
- .github/actions/sign-and-verify/action.yml
|
|
- scripts/prepare-to-push.sh
|
|
- scripts/release-skill.sh
|
|
- scripts/validate-release-links.sh
|
|
- scripts/ci/verify_signing_key_consistency.sh
|