mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-15 14:31:21 +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.
89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# Configuration
|
|
|
|
## Scope
|
|
- Configuration spans frontend build settings, runtime feed paths, workflow triggers, and skill metadata contracts.
|
|
- Most runtime-sensitive controls are environment variables prefixed with `CLAWSEC_` or `OPENCLAW_`.
|
|
- Path normalization is security-sensitive and intentionally rejects unresolved home-token literals.
|
|
|
|
## Core Runtime Variables
|
|
| Variable | Default | Used By |
|
|
| --- | --- | --- |
|
|
| `CLAWSEC_FEED_URL` | Hosted advisory URL | Suite hook and guarded installer feed loading. |
|
|
| `CLAWSEC_FEED_SIG_URL` | `<feed>.sig` | Detached signature source. |
|
|
| `CLAWSEC_FEED_CHECKSUMS_URL` | `checksums.json` near feed URL | Optional checksum-manifest source. |
|
|
| `CLAWSEC_FEED_PUBLIC_KEY` | Suite-local PEM file | Feed signature verification. |
|
|
| `CLAWSEC_ALLOW_UNSIGNED_FEED` | `0` | Temporary migration bypass flag. |
|
|
| `CLAWSEC_VERIFY_CHECKSUM_MANIFEST` | `1` | Enables checksum-manifest verification. |
|
|
| `CLAWSEC_HOOK_INTERVAL_SECONDS` | `300` | Advisory hook scan throttle. |
|
|
|
|
## Path Resolution Rules
|
|
| Rule | Behavior | Enforcement Location |
|
|
| --- | --- | --- |
|
|
| `~` expansion | Resolved to detected home directory | Shared path utility functions in suite/watchdog scripts. |
|
|
| `$HOME` / `${HOME}` expansion | Resolved when unescaped | Same utilities. |
|
|
| Windows home tokens | `%USERPROFILE%`, `$env:USERPROFILE` normalized | Same utilities. |
|
|
| Escaped tokens (`\$HOME`) | Rejected with explicit error | Prevents accidental literal directory creation. |
|
|
| Invalid explicit path | Can fallback to default path with warning | `resolveConfiguredPath` helpers. |
|
|
|
|
## Frontend and Build Configuration
|
|
- `vite.config.ts` defines port (`3000`), host (`0.0.0.0`), and path alias (`@`).
|
|
- `index.html` provides Tailwind runtime config, custom fonts, and base color tokens.
|
|
- `tsconfig.json` uses bundler module resolution, `noEmit`, and JSX runtime configuration.
|
|
- `eslint.config.js` applies TS, React, hooks, and script-specific lint rules.
|
|
|
|
## Skill Metadata Configuration
|
|
| Field Group | Location | Function |
|
|
| --- | --- | --- |
|
|
| Core skill identity | `skills/*/skill.json` | Name/version/author/license/description metadata. |
|
|
| SBOM file list | `skill.json -> sbom.files` | Declares release-required artifacts. |
|
|
| Platform metadata | `openclaw` or `nanoclaw` blocks | CLI requirements, triggers, platform capability hints. |
|
|
| Suite catalog metadata | `skills/clawsec-suite/skill.json -> catalog` | Integrated/default/consent behavior for suite members. |
|
|
|
|
## Workflow Configuration
|
|
- Schedule configuration exists in workflow `cron` entries (`poll-nvd-cves`, `codeql`, `scorecard`).
|
|
- Release workflow expects tag naming pattern `<skill>-v<semver>`.
|
|
- Deployment workflow is triggered by successful CI/release `workflow_run` events and manual dispatch.
|
|
- Composite signing action requires private key inputs and verifies signatures immediately after signing.
|
|
|
|
## Example Snippets
|
|
```bash
|
|
# run guarded install with explicit local signed feed paths
|
|
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
|
|
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
|
|
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
|
|
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
|
|
```
|
|
|
|
```json
|
|
{
|
|
"name": "example-skill",
|
|
"version": "1.2.3",
|
|
"sbom": {
|
|
"files": [
|
|
{ "path": "SKILL.md", "required": true, "description": "Install docs" }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Operational Notes
|
|
- Keep signing keys outside the repository and inject via GitHub Secrets only.
|
|
- Prefer absolute paths or unescaped home expressions in local environment variable overrides.
|
|
- Treat unsigned feed mode as temporary migration support, not normal operation.
|
|
- Re-run release-link validation when editing `SKILL.md` URLs to avoid broken artifact references.
|
|
|
|
## Source References
|
|
- vite.config.ts
|
|
- index.html
|
|
- tsconfig.json
|
|
- eslint.config.js
|
|
- skills/clawsec-suite/skill.json
|
|
- skills/clawsec-nanoclaw/skill.json
|
|
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/utils.mjs
|
|
- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
|
|
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
|
|
- scripts/validate-release-links.sh
|
|
- .github/workflows/poll-nvd-cves.yml
|
|
- .github/workflows/skill-release.yml
|
|
- .github/actions/sign-and-verify/action.yml
|