mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 21:48:03 +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.
97 lines
5.4 KiB
Markdown
97 lines
5.4 KiB
Markdown
# Module: ClawSec Suite Core
|
|
|
|
## Responsibilities
|
|
- Act as the main skill-of-skills security bundle for OpenClaw-style agents.
|
|
- Verify advisory feed authenticity (Ed25519 signatures and optional checksum manifests).
|
|
- Detect advisory matches against installed skills and emit actionable runtime alerts.
|
|
- Enforce two-step confirmation for risky skill installations.
|
|
|
|
## Key Files
|
|
- `skills/clawsec-suite/skill.json`: suite metadata, embedded components, catalog defaults.
|
|
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`: runtime event handler.
|
|
- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs`: signed feed loading/parsing.
|
|
- `skills/clawsec-suite/hooks/.../lib/matching.ts`: advisory-to-skill matching logic.
|
|
- `skills/clawsec-suite/hooks/.../lib/state.ts`: scan state persistence.
|
|
- `skills/clawsec-suite/hooks/.../lib/suppression.mjs`: allowlist-based suppression loader.
|
|
- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`: advisory-gated installer wrapper.
|
|
- `skills/clawsec-suite/scripts/discover_skill_catalog.mjs`: remote/fallback catalog discovery.
|
|
|
|
## Public Interfaces
|
|
| Interface | Consumer | Behavior |
|
|
| --- | --- | --- |
|
|
| Hook handler default export | OpenClaw hook runtime | Handles `agent:bootstrap` and `command:new` events. |
|
|
| `guarded_skill_install.mjs` CLI | Operators/automation | Blocks on advisory matches unless `--confirm-advisory`. |
|
|
| `discover_skill_catalog.mjs` CLI | Suite docs/automation | Lists installable skills with fallback metadata. |
|
|
| `feed.mjs` functions | Suite scripts and tests | Feed load, signature verification, checksum manifest checks. |
|
|
| Exit code contract | External wrappers | `42` indicates explicit second confirmation required. |
|
|
|
|
## Inputs and Outputs
|
|
Inputs/outputs are summarized in the table below.
|
|
|
|
| Type | Name | Location | Description |
|
|
| --- | --- | --- | --- |
|
|
| Input | Advisory feed + signatures | Remote URLs or local `advisories/` files | Risk intelligence source for hook and installer. |
|
|
| Input | Installed skill metadata | Skill directories under install root | Matcher compares installed versions to advisory affected specs. |
|
|
| Input | Suppression config | `OPENCLAW_AUDIT_CONFIG` or default config paths | Selective suppression by check and skill name. |
|
|
| Output | Runtime alert messages | Hook event `messages[]` | Advisories and recommended user actions. |
|
|
| Output | Persistent state | `~/.openclaw/clawsec-suite-feed-state.json` | De-dup alerts, track scan windows. |
|
|
| Output | CLI gating exit codes | Installer process status | Ensures deliberate user confirmation on risk. |
|
|
|
|
## Configuration
|
|
| Variable | Default | Module Effect |
|
|
| --- | --- | --- |
|
|
| `CLAWSEC_FEED_URL` | Hosted advisory URL | Chooses primary remote feed endpoint. |
|
|
| `CLAWSEC_LOCAL_FEED*` vars | Suite-local advisories directory | Configures local signed fallback artifacts. |
|
|
| `CLAWSEC_FEED_PUBLIC_KEY` | `advisories/feed-signing-public.pem` | Verification key path. |
|
|
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | Enables temporary migration bypass mode. |
|
|
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | Enables checksum manifest verification layer. |
|
|
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | Controls event-driven scan throttling. |
|
|
|
|
## Example Snippets
|
|
```ts
|
|
// hook only handles selected events
|
|
function shouldHandleEvent(event: HookEvent): boolean {
|
|
const eventName = toEventName(event);
|
|
return eventName === 'agent:bootstrap' || eventName === 'command:new';
|
|
}
|
|
```
|
|
|
|
```js
|
|
// guarded installer confirmation contract
|
|
if (matches.length > 0 && !args.confirmAdvisory) {
|
|
process.stdout.write('Re-run with --confirm-advisory to proceed.\n');
|
|
process.exit(EXIT_CONFIRM_REQUIRED); // 42
|
|
}
|
|
```
|
|
|
|
## Edge Cases
|
|
- Missing/malformed feed signatures force remote rejection and local fallback attempts.
|
|
- Ambiguous checksum manifest basename collisions are treated as errors.
|
|
- Unknown skill versions are treated conservatively in version matching logic.
|
|
- Suppression is disabled unless config includes the pipeline sentinel (`enabledFor`).
|
|
- Invalid environment path tokens are rejected to avoid accidental literal path usage.
|
|
|
|
## Tests
|
|
| Test File | Focus |
|
|
| --- | --- |
|
|
| `skills/clawsec-suite/test/feed_verification.test.mjs` | Signature/checksum verification and fail-closed behavior. |
|
|
| `skills/clawsec-suite/test/guarded_install.test.mjs` | Confirmation gating and match semantics. |
|
|
| `skills/clawsec-suite/test/path_resolution.test.mjs` | Home/path expansion and invalid token handling. |
|
|
| `skills/clawsec-suite/test/advisory_suppression.test.mjs` | Suppression config parsing and matching. |
|
|
| `skills/clawsec-suite/test/skill_catalog_discovery.test.mjs` | Remote index and fallback merge behavior. |
|
|
|
|
## Source References
|
|
- skills/clawsec-suite/skill.json
|
|
- skills/clawsec-suite/SKILL.md
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/matching.ts
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/state.ts
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/version.mjs
|
|
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
|
|
- skills/clawsec-suite/scripts/discover_skill_catalog.mjs
|
|
- skills/clawsec-suite/test/feed_verification.test.mjs
|
|
- skills/clawsec-suite/test/guarded_install.test.mjs
|
|
- skills/clawsec-suite/test/path_resolution.test.mjs
|