Metadata-Version: 2.4
Name: clawlock
Version: 2.6.1
Summary: Comprehensive security scanner, red-teamer & hardening toolkit for Claw-based AI agent deployments
Author: g0at
License: Apache-2.0 OR MIT
Project-URL: Homepage, https://github.com/g1at/ClawLock/
Project-URL: Repository, https://github.com/g1at/ClawLock/
Keywords: security,ai-agent,openclaw,zeroclaw,claude-code,mcp,red-team,hardening,llm-security,prompt-injection,supply-chain,tool-poisoning
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.25
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: redteam
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff==0.16.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# ClawLock

[![PyPI](https://img.shields.io/pypi/v/clawlock.svg)](https://pypi.org/project/clawlock/)
[![License](https://img.shields.io/badge/License-Apache_2.0_OR_MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Android%20(Termux)-lightgrey.svg)]()

**ClawLock** is a security scanner, hardening wizard, MCP source auditor, and ASI compatibility-profile agent scanner for Claw-family AI agent deployments. It supports **OpenClaw**, **ZeroClaw**, **Claude Code**, and compatible environments.

It is designed for both professional security users and everyday operators:

- Local-first static analysis with built-in engines
- Optional online CVE / skill intelligence
- Optional external-tool and LLM enhancement when you want deeper coverage

## Highlights

- **16 CLI commands** covering full scan, single-skill audit, hardening, history, watch mode, MCP, supply-chain, runtime, and dynamic analysis
- **8 concurrent core security domains** in `clawlock scan`, plus an optional red-team stage
- **Detection Core v2** with project-level multi-label dataflow, evidence paths, capability-chain correlation, and fail-closed incomplete states
- **Artifact-aware Skill inspection** for archives, nested archives, OOXML documents, wheels/JARs, and `.pyc`, backed by a bounded evidence ledger
- **Built-in MCP deep and live engines** for source audit, protocol inventory, trusted snapshots, and rug-pull drift detection
- **Structured supply-chain analysis** for manifests, lockfiles, install hooks, external instruction graphs, SBOMs, and SLSA provenance
- **Container/runtime coverage** for Dockerfile, Compose, Kubernetes, and explicitly authorized behavior analysis in a pinned read-only image
- **Built-in ClawLock ASI 14 compatibility profile** with adapter-scoped config analysis, code scanning, and optional LLM assessment
- **Interactive hardening** with 18 measures, platform-aware filtering, and explicit UX-impact disclosure
- **JSON, text, and HTML reports** for the full `scan` workflow
- **Global CLI language adaptation**:
  `CLAWLOCK_LANG=zh` uses Chinese, and every other case uses English
- **Cross-platform support** for Linux, macOS, Windows, and Android (Termux)

## Quick Start

```bash
pip install clawlock

clawlock --help                           # Show command help
clawlock scan                            # Full security scan
clawlock discover                        # Discover local Claw installations
clawlock precheck ./new-skill/SKILL.md   # Pre-check a new skill
clawlock skill /path/to/skill            # Audit one skill
clawlock soul                            # Check prompt + memory drift
clawlock harden                          # Interactive hardening wizard
clawlock harden --auto-fix               # Apply safe local auto-fixes
clawlock harden --from-scan --auto-fix   # Fix only issues found in last scan
clawlock harden --auto-fix --verify      # Auto-fix then verify the result
clawlock harden --rollback               # Undo the last auto-fix
clawlock mcp-scan ./mcp-server/src       # MCP source-code deep scan
clawlock mcp-live ./.mcp.json --server fs --execute --snapshot ./mcp.snapshot.json
clawlock supply-chain ./project          # Manifests, locks, instructions, SBOM, provenance
clawlock runtime-scan ./deploy           # Dockerfile, Compose, and Kubernetes audit
clawlock dynamic-scan ./skill --image analyzer@sha256:<digest> \
  --entrypoint-json '["--","python","/workspace/main.py"]' --execute
clawlock agent-scan --code ./agent/src   # Standalone ClawLock ASI compatibility scan
clawlock scan --format html -o report.html
```

Running `clawlock` with no subcommand prints the brand logo. Use `clawlock --help` for the command list.

## CLI Language

ClawLock uses one simple global rule:

- `CLAWLOCK_LANG=zh`: Chinese
- Any other value, or not set: English

Examples by platform:

Windows PowerShell:

```powershell
$env:CLAWLOCK_LANG='zh'
clawlock scan
```

Windows CMD:

```bat
set CLAWLOCK_LANG=zh
clawlock scan
```

Linux / macOS / Android (Termux):

```bash
export CLAWLOCK_LANG=zh
clawlock scan
```

This applies to:

- `--help`
- runtime progress and summaries
- hardening wizard output
- scan / skill / precheck / soul / redteam / MCP / supply-chain / runtime / dynamic / agent-scan text output

## Detection Core v2

Detection Core v2 correlates evidence instead of treating every suspicious token as an isolated hit:

- **Project-level multi-label dataflow** tracks untrusted input, secrets, file paths, network data, and downloaded content through aliases, assignments, arguments, returns, wrappers, and cross-file calls. Findings include source-to-sink evidence paths and confidence.
- **Artifact recovery with an evidence ledger** safely inspects ZIP/TAR/wheel/JAR/OOXML content, nested containers, and recoverable `.pyc` instructions under entry, byte, depth, ratio, and time budgets. Path traversal, links, encryption, duplicate names, magic/extension mismatch, and source/bytecode mismatch remain visible in the ledger.
- **Capability-chain correlation** joins events such as sensitive read → external write, download → execute, memory write → autorun, and untrusted path → write/execute. Structured dataflow evidence retains its severity and confidence; text-only associations are marked as unconfirmed, medium-severity findings for review. Parseable Python text uses separate lexical scopes and excludes comments and docstrings from correlation evidence.
- **Structured supply-chain checks** parse manifests and lockfiles, npm lifecycle hooks, Python build backends, mutable dependencies, SBOMs, recursive instruction references, pin/hash drift, and in-toto/SLSA statements. Remote instructions are recorded but not fetched by default. A DSSE signature is reported as present but is never called trusted without an independent verification policy.
- **Live and runtime evidence** can inventory an explicitly selected MCP server, compare a trusted snapshot for tool/prompt/resource drift, audit deployment definitions, or run bounded behavior analysis in a pinned container.

Every bounded traversal reports whether it completed. A budget limit, parser failure, unavailable explicitly requested tool, or refused active probe is **INCOMPLETE**, not a clean pass.

## Report Formats And Exit Modes

ClawLock uses three report formats for different workflows:

| Format | Best for | Notes |
|--------|----------|-------|
| `text` | Local terminal review | Default format for security operators |
| `json` | Automation, CI, skills, and secondary processing | Best choice when another system needs structured output |
| `html` | Review, sharing, and archived reports | `scan` writes a standalone report file and prints the saved path even if a browser cannot be opened automatically |

`scan` also uses two execution modes:

| Mode | Behavior | Best for |
|------|----------|----------|
| `monitor` (default) | Report only; does not fail the run on findings | Manual review and exploratory checks |
| `enforce` | Returns `1` on critical/high findings and `2` when a requested check is incomplete | CI gates and automated enforcement (pass `--mode enforce`) |

Security focus commands use the same machine-friendly exit contract: `0` means the requested analysis completed without critical/high findings, `1` means critical/high findings were reported, and `2` means the requested analysis was **INCOMPLETE**. Review JSON `status`, `complete`, and finding metadata instead of treating exit `2` as success.

Examples:

```bash
clawlock scan --format text
clawlock scan --format json --mode enforce -o report.json
clawlock scan --format html -o report.html
```

## Scan Pipeline

`clawlock scan` runs 8 core security domains in parallel, then optionally runs a red-team stage.

| Step | Check | What it does |
|------|-------|--------------|
| 1 | Config audit | Adapter-aware config checks plus risky environment-variable checks |
| 2 | Process exposure | Running processes and exposed listeners |
| 3 | Credential audit | Permission review for credential files and directories |
| 4 | Skill supply chain | Pattern, artifact-ledger, dataflow, capability-chain, package, and instruction-graph analysis |
| 5 | Prompt and memory | SOUL / prompt drift plus memory-file checks |
| 6 | MCP exposure | MCP config and poisoning-surface checks |
| 7 | CVE matching | Tencent cloud CVE intelligence lookup, enabled by default unless `--no-cve` |
| 8 | Agent security | Included in `scan` with adapter config ASI checks; use `agent-scan` for code-layer review |
| 9 | Red Team (optional) | Runs only when `--endpoint` is provided and `--no-redteam` is not used |

## Dependency Model

### 1. Built-in local engine

Works with just:

```bash
pip install clawlock
```

No Node.js, no external scanner binary, and no LLM API key are required for:

- full local scan pipeline except online CVE lookup
- skill audit and precheck
- prompt / memory drift checks
- hardening
- history and watch mode
- MCP deep scan
- artifact, capability-chain, structured supply-chain, and runtime-definition analysis
- `scan` includes the Agent-Scan config layer; use `agent-scan --code ...` for code-layer review

### 2. Online intelligence without API keys

These features are network-backed but do not require a user API key:

- `scan` CVE matching through the Tencent advisory endpoint
- optional skill cloud intelligence during `clawlock skill`

If you want a fully local run, use:

```bash
clawlock scan --no-cve --no-redteam
clawlock skill /path/to/skill --no-cloud
```

### 3. LLM-enhanced analysis

`agent-scan` can add an optional semantic layer with Anthropic or OpenAI-compatible APIs:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
clawlock agent-scan --code ./src --llm
```

When `--llm` is enabled, selected source/config snippets are redacted and truncated before being sent. A missing key, failed request, or unparseable response is reported as an incomplete requested check rather than a clean result. Prefer environment variables over `--token` so secrets do not enter shell history.

### 4. Optional external tools

ClawLock can optionally integrate with external tools, but only in the paths where code actually uses them:

| Tool | Current integration in ClawLock | When it is used |
|------|---------------------------------|-----------------|
| [promptfoo](https://github.com/promptfoo/promptfoo) | `clawlock redteam` / optional scan red-team stage | Requires an explicitly installed, preferably pinned `promptfoo` binary. ClawLock generates tests and evaluates them in separate steps with result sharing disabled; it never downloads `promptfoo@latest` through `npx`. |
| [OSV-Scanner](https://github.com/google/osv-scanner) | `clawlock supply-chain PATH --osv` | Runs only an already installed binary after explicit opt-in; an unavailable requested adapter is INCOMPLETE. |
| [Gitleaks](https://github.com/gitleaks/gitleaks) | `clawlock supply-chain PATH --gitleaks` | Runs only an already installed binary after explicit opt-in; reported secret material is redacted. |
| Docker or Podman | `clawlock dynamic-scan` | Requires `--execute`, a digest-pinned analyzer image, a JSON argv entrypoint, and a non-host network policy. There is no host-execution fallback. |

ClawLock never auto-downloads any of these tools. Live MCP stdio launch, remote MCP probing, trusted snapshot replacement, red-team traffic, and container execution require their corresponding explicit authorization flags. Static analysis remains local and passive.

## Command Overview

| Command | Purpose |
|---------|---------|
| `scan` | Run the full security scan |
| `discover` | Discover local Claw installations |
| `skill` | Audit one skill |
| `precheck` | Precheck a new skill before import |
| `soul` | Check prompt and memory drift |
| `harden` | Run the interactive hardening wizard |
| `redteam` | Run promptfoo red-team tests |
| `mcp-scan` | Deep-scan MCP server source code |
| `mcp-live` | Collect an authorized MCP inventory and detect trusted-snapshot drift |
| `supply-chain` | Audit dependencies, install hooks, instruction graphs, SBOMs, and SLSA provenance |
| `dynamic-scan` | Run bounded behavior analysis in a pinned read-only Docker/Podman container |
| `runtime-scan` | Audit Dockerfile, Compose, and Kubernetes security posture without deployment |
| `agent-scan` | Run the ClawLock ASI 14 compatibility profile |
| `history` | Show recent scan history |
| `watch` | Watch key checks for changes |
| `version` | Show version info |

## Hardening

ClawLock currently ships **18 hardening measures**.

- `clawlock harden`: interactive mode
- `clawlock harden --auto`: applies safe non-interactive actions and prints guidance for recommendation-only items
- `clawlock harden --auto-fix`: only performs real safe local auto-fixes
- `clawlock harden --from-scan`: show only measures relevant to the latest scan findings
- `clawlock harden --auto-fix --verify`: auto-fix then re-scan to confirm the fix worked
- `clawlock harden --rollback`: undo the last auto-fix action (restores from backup)

With `--verify`, configuration and credential checks run even when no changes were applied. Verification exits `0` when complete without critical/high findings, `1` when critical/high findings remain, and `2` if any check fails or is incomplete. Incomplete checks take precedence and are never shown as a successful verification.

Auto-fixable measures:

| ID | Measure | What it does |
|----|---------|--------------|
| H003 | Shorten session retention | Sets `sessionRetentionDays` to 7 in config files |
| H007 | Create prompt baseline | Records SHA-256 baselines for SOUL.md / CLAUDE.md / MEMORY.md |
| H008 | Enable approval mode | Sets `approvalMode` to `"always"` in config files |
| H009 | Tighten credential permissions | `chmod 600`/`700` or `icacls` on config dirs and credential files |

All config modifications are backed up to `~/.clawlock/backups/` before changes are made.

Config rollback checks each file against the exact bytes written by that action. Later edits are retained, with the journal and backup available for review. Older config journals without a written-content digest also require manual review; permission rollback remains supported.

Other behavior:

- The wizard groups measures into **Safe to apply now**, **Recommended only**, and **Needs confirmation**
- UX-impacting measures still require explicit confirmation in interactive mode
- Guidance-only measures are no longer reported as if they were applied

## Multi-Platform Support

| Feature | Linux | macOS | Windows | Android (Termux) |
|---------|:-----:|:-----:|:-------:|:----------------:|
| Full scan pipeline | Yes | Yes | Yes | Yes |
| Process detection | `ps aux` | `ps aux` | `tasklist` | `ps -e` |
| Port exposure check | `ss` / `netstat` | `lsof -iTCP` | `netstat -ano` | `ss` / `netstat` |
| Permission audit | Unix `stat` | Unix `stat` | `icacls` ACL | Unix `stat` |
| Permission auto-fix | `chmod` | `chmod` | `icacls` | `chmod` |
| Persistence detection | cron / user `systemd` | `LaunchAgents` / `launchctl` | `schtasks` / `RunOnce` | `.termux/boot` / `termux-job-scheduler` |
| Hardening guidance | Platform-aware | Platform-aware | Platform-aware | Platform-aware |

## Use as a Claw Skill

Copy `skill/SKILL.md` into your Claw skills directory, then trigger the security workflow from your Claw conversation.

Detailed guides:

- [skill/SKILL.md](skill/SKILL.md) (Chinese)
- [skill/SKILL_EN.md](skill/SKILL_EN.md) (English)

Example:

```bash
mkdir -p ~/.openclaw/skills/clawlock
cp skill/SKILL.md ~/.openclaw/skills/clawlock/
```

## CI/CD Example

```yaml
- name: ClawLock security gate
  run: |
    pip install clawlock
    clawlock scan --no-cve --no-redteam --format json --mode enforce > report.json
```

## Development

```bash
git clone https://github.com/g1at/clawlock.git
cd clawlock
pip install -e ".[dev]"
pytest tests/test_clawlock.py -v    # 110 tests
```

## Contributing

Useful areas to extend:

- `clawlock/scanners/__init__.py`
- `clawlock/scanners/mcp_deep.py`
- `clawlock/scanners/agent_scan.py`
- `clawlock/hardening/__init__.py`
- `clawlock/reporters/__init__.py`

## Acknowledgements

We are deeply grateful to these open-source projects whose work inspires and enhances ClawLock:

- **[promptfoo](https://github.com/promptfoo/promptfoo)** — A major inspiration behind ClawLock's red-team workflow. promptfoo's declarative configuration model, broad jailbreak and injection coverage, and OWASP-oriented evaluation approach helped shape how ClawLock thinks about endpoint red-team testing. Thank you to the promptfoo team for building such a versatile LLM evaluation platform.

## License

ClawLock is dual-licensed under [Apache License 2.0](LICENSE) and [MIT License](LICENSE). You may choose either license.
