mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-14 22:11:22 +03:00
davida-ps
cbc484faf3
- Introduced glossary for key terms and definitions related to security advisories, skill packaging, and CI/CD processes. - Documented the Automation and Release Pipelines module, detailing responsibilities, key files, public interfaces, and configuration. - Added ClawSec Suite Core module documentation, outlining its responsibilities, key files, public interfaces, and configuration. - Created Frontend Web App module documentation, covering responsibilities, key files, public interfaces, and configuration. - Added Local Validation and Packaging Tools module documentation, detailing responsibilities, key files, public interfaces, and configuration. - Documented NanoClaw Integration module, including responsibilities, key files, public interfaces, and configuration. - Introduced an overview of ClawSec, including purpose, repo layout, entry points, key artifacts, and workflows. - Added a Security section outlining the security model, cryptographic controls, runtime enforcement, and incident playbooks. - Created a Testing section detailing the testing strategy, verification layers, CI workflow coverage, and local testing commands. - Documented the Workflow section, covering the end-to-end lifecycle, primary workflow map, local operator workflow, and operational risks.
3.4 KiB
3.4 KiB
Workflow
End-to-End Lifecycle
- Development starts with local coding + local data population for realistic UI preview.
- PR CI validates quality/security and skill test suites.
- Tag-driven release workflow packages and signs skill artifacts.
- Pages deploy workflow mirrors release/advisory artifacts and publishes the static site.
- Scheduled workflows continuously enrich advisory feed and supply-chain visibility.
Primary Workflow Map
| Workflow | Trigger | Main Steps |
|---|---|---|
| CI | PR/push to main |
Lint, typecheck, build, Python checks, security scans, skill tests. |
| Poll NVD CVEs | Daily cron + manual dispatch | Fetch CVEs, transform/dedupe, update feed, sign artifacts, PR changes. |
| Process Community Advisory | Issue label advisory-approved |
Parse issue form, create advisory, sign feed, open PR, comment issue. |
| Skill Release | Tag <skill>-v* |
Validate versions, package SBOM files, sign checksums, publish release. |
| Deploy Pages | Successful CI/Release or manual dispatch | Discover releases, mirror assets, sign public advisories/checksums, deploy site. |
Local Operator Workflow
| Step | Command | Outcome |
|---|---|---|
| Install deps | npm install |
Ready local environment. |
| Populate local catalog | ./scripts/populate-local-skills.sh |
public/skills/index.json and file checksums. |
| Populate local feed | ./scripts/populate-local-feed.sh --days 120 |
Updated local advisory feed copy. |
| Run local gate | ./scripts/prepare-to-push.sh |
CI-like pass/fail signal. |
| Start dev UI | npm run dev |
Browser preview at local Vite endpoint. |
Release Workflow Details
- Version bump and docs parity are enforced for PR/tag paths.
- Skill packaging includes SBOM-declared files and integrity manifests.
checksums.jsonis signed and immediately verified in workflow execution.- Optional publish-to-ClawHub job runs after successful GitHub release when configured.
- Older releases within same major line can be superseded/deleted by automation.
Advisory Workflow Details
- NVD workflow determines incremental window from previous feed
updatedtimestamp. - Transform phase maps CVE metrics to severity/type and normalizes affected targets.
- Community advisory workflow creates deterministic IDs (
CLAW-YYYY-NNNN) from issue metadata. - Both advisory workflows update skill feed copies and signature companions.
Example Snippets
# manual release prep for a skill
./scripts/release-skill.sh clawsec-feed 0.0.5
# then push tag if running in release branch mode
# pages deploy depends on successful upstream workflow run
on:
workflow_run:
workflows: ["CI", "Skill Release"]
types: [completed]
Operational Risks
- Workflow permissions and secret scope misconfiguration can block signing/publishing.
- NVD/API transient failures may delay advisory freshness.
- Invalid tag naming or version mismatches halt release automation.
- Local scripts and CI can diverge if operator machine lacks expected binaries (
jq,openssl,clawhub).
Source References
- scripts/release-skill.sh
- scripts/prepare-to-push.sh
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- .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/codeql.yml
- .github/workflows/scorecard.yml
- .github/actions/sign-and-verify/action.yml