clawlock 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. clawlock-1.0.0/LICENSE +82 -0
  2. clawlock-1.0.0/PKG-INFO +212 -0
  3. clawlock-1.0.0/README.md +183 -0
  4. clawlock-1.0.0/clawlock/__init__.py +5 -0
  5. clawlock-1.0.0/clawlock/__main__.py +368 -0
  6. clawlock-1.0.0/clawlock/adapters/__init__.py +94 -0
  7. clawlock-1.0.0/clawlock/hardening/__init__.py +102 -0
  8. clawlock-1.0.0/clawlock/integrations/__init__.py +308 -0
  9. clawlock-1.0.0/clawlock/integrations/promptfoo.py +53 -0
  10. clawlock-1.0.0/clawlock/reporters/__init__.py +134 -0
  11. clawlock-1.0.0/clawlock/scanners/__init__.py +587 -0
  12. clawlock-1.0.0/clawlock/scanners/agent_scan.py +522 -0
  13. clawlock-1.0.0/clawlock/scanners/mcp_deep.py +487 -0
  14. clawlock-1.0.0/clawlock/utils/__init__.py +269 -0
  15. clawlock-1.0.0/clawlock.egg-info/PKG-INFO +212 -0
  16. clawlock-1.0.0/clawlock.egg-info/SOURCES.txt +20 -0
  17. clawlock-1.0.0/clawlock.egg-info/dependency_links.txt +1 -0
  18. clawlock-1.0.0/clawlock.egg-info/entry_points.txt +2 -0
  19. clawlock-1.0.0/clawlock.egg-info/requires.txt +12 -0
  20. clawlock-1.0.0/clawlock.egg-info/top_level.txt +1 -0
  21. clawlock-1.0.0/pyproject.toml +36 -0
  22. clawlock-1.0.0/setup.cfg +4 -0
clawlock-1.0.0/LICENSE ADDED
@@ -0,0 +1,82 @@
1
+ ClawLock is dual-licensed under Apache License 2.0 and MIT License.
2
+ You may choose either license at your option.
3
+
4
+ ================================================================================
5
+ Apache License, Version 2.0
6
+ ================================================================================
7
+
8
+ Version 2.0, January 2004
9
+ http://www.apache.org/licenses/
10
+
11
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
12
+
13
+ 1. Definitions.
14
+ "License" shall mean the terms and conditions for use, reproduction, and
15
+ distribution as defined by Sections 1 through 9 of this document.
16
+ "Licensor" shall mean the copyright owner or entity authorized by the
17
+ copyright owner that is granting the License.
18
+ "You" (or "Your") shall mean an individual or Legal Entity exercising
19
+ permissions granted by this License.
20
+ "Work" shall mean the work of authorship made available under the License.
21
+ "Derivative Works" shall mean any work that is based on the Work.
22
+ "Contribution" shall mean any work of authorship submitted to the Licensor
23
+ for inclusion in the Work.
24
+
25
+ 2. Grant of Copyright License. Each Contributor hereby grants to You a
26
+ perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
27
+ copyright license to reproduce, prepare Derivative Works of, publicly
28
+ display, publicly perform, sublicense, and distribute the Work and such
29
+ Derivative Works in Source or Object form.
30
+
31
+ 3. Grant of Patent License. Each Contributor hereby grants to You a perpetual,
32
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent
33
+ license to make, have made, use, offer to sell, sell, import, and otherwise
34
+ transfer the Work.
35
+
36
+ 4. Redistribution. You may reproduce and distribute copies of the Work or
37
+ Derivative Works thereof in any medium, with or without modifications,
38
+ provided that You meet the following conditions:
39
+ (a) You must give any other recipients a copy of this License; and
40
+ (b) You must cause any modified files to carry prominent notices; and
41
+ (c) You must retain all copyright, patent, trademark, and attribution
42
+ notices from the Source form of the Work.
43
+
44
+ 5. Submission of Contributions. Unless You explicitly state otherwise, any
45
+ Contribution submitted for inclusion in the Work shall be under the terms
46
+ of this License.
47
+
48
+ 6. Trademarks. This License does not grant permission to use the trade names,
49
+ trademarks, service marks, or product names of the Licensor.
50
+
51
+ 7. Disclaimer of Warranty. The Work is provided on an "AS IS" BASIS, WITHOUT
52
+ WARRANTIES OR CONDITIONS OF ANY KIND.
53
+
54
+ 8. Limitation of Liability. In no event shall any Contributor be liable to You
55
+ for damages.
56
+
57
+ 9. Accepting Warranty or Additional Liability. You may choose to offer
58
+ acceptance of support, warranty, indemnity, or other liability obligations.
59
+
60
+ ================================================================================
61
+ MIT License
62
+ ================================================================================
63
+
64
+ Copyright (c) 2026 g1at
65
+
66
+ Permission is hereby granted, free of charge, to any person obtaining a copy
67
+ of this software and associated documentation files (the "Software"), to deal
68
+ in the Software without restriction, including without limitation the rights
69
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
70
+ copies of the Software, and to permit persons to whom the Software is
71
+ furnished to do so, subject to the following conditions:
72
+
73
+ The above copyright notice and this permission notice shall be included in all
74
+ copies or substantial portions of the Software.
75
+
76
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
77
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
78
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
79
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
80
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
81
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
82
+ SOFTWARE.
clawlock-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,212 @@
1
+ Metadata-Version: 2.4
2
+ Name: clawlock
3
+ Version: 1.0.0
4
+ Summary: Comprehensive security scanner, red-teamer & hardening toolkit for Claw-based AI agent deployments
5
+ Author: g1at
6
+ License: Apache-2.0 OR MIT
7
+ Project-URL: Homepage, https://github.com/g1at/clawlock
8
+ Project-URL: Repository, https://github.com/g1at/clawlock
9
+ Keywords: security,ai-agent,openclaw,zeroclaw,claude-code,mcp,red-team,hardening,llm-security,prompt-injection,supply-chain,tool-poisoning
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: License :: OSI Approved :: Apache Software License
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Security
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: typer>=0.12
19
+ Requires-Dist: rich>=13.0
20
+ Requires-Dist: pyyaml>=6.0
21
+ Requires-Dist: httpx>=0.25
22
+ Provides-Extra: redteam
23
+ Requires-Dist: promptfoo>=0.80; extra == "redteam"
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest>=7.0; extra == "dev"
26
+ Requires-Dist: ruff>=0.3; extra == "dev"
27
+ Requires-Dist: mypy>=1.8; extra == "dev"
28
+ Dynamic: license-file
29
+
30
+ # 🔒 ClawLock
31
+
32
+ #### [Documentation](https://github.com/g1at/clawlock#quick-start) | [中文](README_ZH.md)
33
+
34
+ [![PyPI](https://img.shields.io/pypi/v/clawlock.svg)](https://pypi.org/project/clawlock/)
35
+ [![License](https://img.shields.io/badge/License-Apache_2.0_OR_MIT-blue.svg)](LICENSE)
36
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
37
+ [![Tests](https://img.shields.io/badge/tests-59%2F59-brightgreen.svg)]()
38
+ [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Android-lightgrey.svg)]()
39
+
40
+ **ClawLock** is a comprehensive security scanner, red-teamer, and hardening toolkit for Claw-based AI agent deployments. It supports **OpenClaw**, **ZeroClaw**, **Claude Code**, and compatible platforms — running natively on **Linux**, **macOS**, **Windows**, and **Android (Termux)**.
41
+
42
+ Built for both security teams and individual developers — install with one command, scan in seconds, harden interactively.
43
+
44
+ ## Highlights
45
+
46
+ - **75+ detection rules** across 9 scan steps covering config, supply chain, prompt injection, MCP tool poisoning, CVE, credential audit, cost analysis, and more
47
+ - **Built-in MCP deep scan engine** — 28+ patterns across 14 risk categories + Python AST taint tracking, zero external dependency
48
+ - **Built-in OWASP ASI 14 Agent-Scan** — 4-layer detection (config + code patterns + optional LLM assessment + optional active probing)
49
+ - **14 CLI commands** — from full scan to single-skill audit to remote instance probing
50
+ - **4 platform adapters** — auto-detects OpenClaw, ZeroClaw, Claude Code, or falls back to generic
51
+ - **Cross-OS support** — runs on Linux, macOS, Windows, and Android (Termux) with zero platform-specific setup
52
+ - **Interactive hardening** with UX impact disclosure — dangerous changes require explicit confirmation
53
+ - **Zero required dependencies** beyond Python — everything works out of the box
54
+
55
+ ## Quick Start
56
+
57
+ ```bash
58
+ pip install clawlock
59
+
60
+ clawlock scan # Full 9-step security scan
61
+ clawlock discover # Find all Claw installations
62
+ clawlock probe http://your-server:3000 # Remote instance probe
63
+ clawlock precheck ./new-skill/SKILL.md # Pre-check new skill
64
+ clawlock skill /path/to/skill # Single skill audit
65
+ clawlock soul # SOUL.md + memory drift
66
+ clawlock harden --auto-fix # Auto-fix safe items
67
+ clawlock mcp-scan ./mcp-server/src # MCP Server source code deep scan
68
+ clawlock agent-scan --code ./agent/src # OWASP ASI 14-category Agent-Scan
69
+ clawlock scan --format html -o report.html # HTML report
70
+ ```
71
+
72
+ ## Scan Pipeline
73
+
74
+ | Step | Check | What It Does |
75
+ |------|-------|-------------|
76
+ | 1 | Config audit + risky env vars | Per-adapter rules + NODE_OPTIONS/LD_PRELOAD detection |
77
+ | 2 | Process detection + port exposure | Running processes + 0.0.0.0 listeners |
78
+ | 3 | Credential directory audit | File/directory permissions on credential stores |
79
+ | 4 | Skill supply chain (46 patterns) | Reverse shells, credential exfil, prompt injection, DNS exfil, zero-width chars |
80
+ | 5 | SOUL.md + memory file drift | SHA-256 baseline comparison for SOUL/CLAUDE/HEARTBEAT/MEMORY.md |
81
+ | 6 | MCP exposure + 6 tool poisoning | Parameter tampering, function hijacking, rug pull, tool shadowing |
82
+ | 7 | CVE matching | Cloud vulnerability intelligence (589+ CVEs, 43 AI frameworks) |
83
+ | 8 | Cost analysis | Expensive models, high-frequency heartbeats |
84
+ | 9 | LLM red-team (optional) | 9 plugins × 8 strategies via promptfoo |
85
+
86
+ ## Dependencies: Three Tiers
87
+
88
+ ClawLock is designed with a clear dependency philosophy: **most users need nothing beyond `pip install clawlock`**. Advanced capabilities are available for professional users who install optional tools.
89
+
90
+ ### Tier 1: Zero-Dependency (covers 90%+ use cases)
91
+
92
+ Everything below works with just `pip install clawlock` — no Node.js, no external binaries, no API keys:
93
+
94
+ - Full 9-step scan (config, processes, credentials, supply chain, SOUL.md drift, MCP exposure, CVE, cost)
95
+ - MCP Server source code deep scan (`clawlock mcp-scan`) — built-in Python regex + AST taint tracking engine
96
+ - OWASP ASI 14 Agent-Scan (`clawlock agent-scan --code`) — built-in static config + code pattern analysis
97
+ - Skill audit, pre-check, hardening, discovery, history, watch mode
98
+ - Remote instance probing, React2Shell detection
99
+
100
+ ### Tier 2: LLM-Enhanced (needs API key only)
101
+
102
+ With an Anthropic or OpenAI API key, unlock semantic-level analysis on top of the built-in engine:
103
+
104
+ ```bash
105
+ export ANTHROPIC_API_KEY=sk-ant-...
106
+ clawlock agent-scan --code ./src --llm # Add LLM semantic assessment layer
107
+ clawlock agent-scan http://x:3000 --probe --llm # Full 4-layer scan
108
+ ```
109
+
110
+ No external binary needed — ClawLock calls the LLM API directly via Python.
111
+
112
+ ### Tier 3: Professional (optional external tools)
113
+
114
+ For security professionals who want maximum coverage, two excellent open-source projects can be installed to enhance ClawLock's capabilities. **ClawLock auto-detects their presence and uses them when available — no configuration needed.**
115
+
116
+ | Tool | What It Adds | Install | When You Need It |
117
+ |------|-------------|---------|-----------------|
118
+ | **[promptfoo](https://github.com/promptfoo/promptfoo)** | LLM red-team testing: 50+ vulnerability plugins, adaptive jailbreak attacks (tree search, crescendo, multi-turn), OWASP/NIST/MITRE compliance mapping, visual attack dashboard | `npm install -g promptfoo` | Systematic red-team testing of a live agent endpoint with comprehensive attack coverage |
119
+ | **[AI-Infra-Guard](https://github.com/Tencent/AI-Infra-Guard)** | ReAct agent-driven MCP code analysis (cross-function semantic reasoning, multi-language), 6-sub-agent collaborative Agent-Scan, multi-turn dialogue attack simulation | [Download binary](https://github.com/Tencent/AI-Infra-Guard/releases) | LLM-powered deep semantic analysis of MCP Server source code beyond pattern matching |
120
+
121
+ **How it works:** When `mcp-scan` or `agent-scan` runs, the built-in engine always executes first. If `ai-infra-guard` is installed AND `--model`/`--token` are provided, ClawLock automatically invokes it as an enhancement layer. Similarly, `clawlock redteam` delegates to `promptfoo` when available. No special flags needed — just install the tools and ClawLock uses them.
122
+
123
+ ### What's the difference?
124
+
125
+ | Dimension | ClawLock Built-in | + AI-Infra-Guard | + promptfoo |
126
+ |-----------|:-:|:-:|:-:|
127
+ | **Cost** | Free | LLM API tokens | LLM API tokens |
128
+ | **Speed** | <1 second | 5-15 minutes | 5-15 minutes |
129
+ | **Determinism** | 100% reproducible | Non-deterministic (LLM) | Non-deterministic (LLM) |
130
+ | **Language coverage** | Python + JS/TS | Any language | N/A (tests endpoints) |
131
+ | **Analysis depth** | Pattern matching + AST | Cross-function semantic reasoning | Adaptive multi-turn attacks |
132
+ | **CI/CD friendly** | ✅ Zero-config | Needs API key | Needs Node.js + API key |
133
+ | **Offline capable** | ✅ (with `--no-cve`) | ❌ | ❌ |
134
+
135
+ ## Multi-Platform Support
136
+
137
+ | Feature | Linux | macOS | Windows | Android (Termux) |
138
+ |---------|:-----:|:-----:|:-------:|:-----------------:|
139
+ | Full scan pipeline | ✅ | ✅ | ✅ | ✅ |
140
+ | Process detection | `ps aux` | `ps aux` | `tasklist` | `ps -e` |
141
+ | Port exposure check | `ss`/`netstat` | `lsof -iTCP` | `netstat -ano` | `ss`/`netstat` |
142
+ | Credential permission audit | Unix `stat` | Unix `stat` | `icacls` ACL | Unix `stat` |
143
+ | Permission auto-fix | `chmod` | `chmod` | `icacls` | `chmod` |
144
+
145
+ ## Hardening
146
+
147
+ 10 hardening measures with UX impact disclosure. Measures that affect functionality require explicit `y` confirmation. Use `--auto-fix` to automatically apply non-breaking fixes.
148
+
149
+ ## Acknowledgements
150
+
151
+ We are deeply grateful to these open-source projects whose work inspires and enhances ClawLock:
152
+
153
+ - **[promptfoo](https://github.com/promptfoo/promptfoo)** — The foundation of ClawLock's red-team capabilities. promptfoo's declarative config system, comprehensive jailbreak/injection testing framework, and OWASP compliance mapping are best-in-class. Thank you to the promptfoo team for building such a versatile LLM evaluation platform.
154
+ - **[AI-Infra-Guard](https://github.com/Tencent/AI-Infra-Guard)** by Tencent Zhuque Lab — ClawLock integrates AI-Infra-Guard's CVE advisory API (589+ vulnerabilities across 43 AI frameworks). Our MCP implicit tool poisoning detection patterns are informed by the MCP-ITP research (arXiv:2601.07395). Thank you for pioneering work in AI infrastructure security.
155
+
156
+ ## Use as a Claw Skill
157
+
158
+ Copy `skill/SKILL.md` into your Claw skills directory, then say "security scan" in your Agent conversation. When used as a Skill, all Tier 1 features work out of the box.
159
+
160
+ ```bash
161
+ mkdir -p ~/.openclaw/skills/clawlock && cp skill/SKILL.md ~/.openclaw/skills/clawlock/
162
+ ```
163
+
164
+ ## Architecture
165
+
166
+ ```
167
+ clawlock/
168
+ ├── scanners/
169
+ │ ├── __init__.py # 75 detection rules across 9 scan categories
170
+ │ ├── mcp_deep.py # Built-in MCP deep scan engine (28+ patterns + AST)
171
+ │ └── agent_scan.py # Built-in OWASP ASI 14 engine (4 layers)
172
+ ├── integrations/
173
+ │ ├── __init__.py # Cloud intel, remote probe, cost, React2Shell, optional enhancers
174
+ │ └── promptfoo.py # LLM red-team wrapper (9 plugins × 8 strategies)
175
+ ├── adapters/ # Platform abstraction (4 Claw adapters)
176
+ ├── hardening/ # 10 measures with UX impact disclosure
177
+ ├── reporters/ # Rich terminal + JSON + HTML
178
+ ├── utils/ # Cross-platform abstraction (Windows/Mac/Linux/Android)
179
+ └── __main__.py # Typer CLI (14 commands)
180
+ ```
181
+
182
+ ## CI/CD Integration
183
+
184
+ ```yaml
185
+ - name: ClawLock security gate
186
+ run: |
187
+ pip install clawlock
188
+ clawlock scan --no-cve --no-redteam --format json --mode enforce > report.json
189
+ ```
190
+
191
+ ## Development
192
+
193
+ ```bash
194
+ git clone https://github.com/g1at/clawlock.git
195
+ cd clawlock
196
+ pip install -e ".[dev]"
197
+ pytest tests/ -v # 59 tests
198
+ ```
199
+
200
+ ## Contributing
201
+
202
+ Contributions welcome! See areas of interest:
203
+
204
+ - New detection patterns → `scanners/__init__.py`
205
+ - MCP scan patterns → `scanners/mcp_deep.py`
206
+ - ASI detection rules → `scanners/agent_scan.py`
207
+ - New platform adapters → `adapters/__init__.py`
208
+ - New hardening measures → `hardening/__init__.py`
209
+
210
+ ## License
211
+
212
+ ClawLock is dual-licensed under [Apache License 2.0](LICENSE) and [MIT License](LICENSE). You may choose either license at your option.
clawlock-1.0.0/README.md ADDED
@@ -0,0 +1,183 @@
1
+ # 🔒 ClawLock
2
+
3
+ #### [Documentation](https://github.com/g1at/clawlock#quick-start) | [中文](README_ZH.md)
4
+
5
+ [![PyPI](https://img.shields.io/pypi/v/clawlock.svg)](https://pypi.org/project/clawlock/)
6
+ [![License](https://img.shields.io/badge/License-Apache_2.0_OR_MIT-blue.svg)](LICENSE)
7
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
8
+ [![Tests](https://img.shields.io/badge/tests-59%2F59-brightgreen.svg)]()
9
+ [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Android-lightgrey.svg)]()
10
+
11
+ **ClawLock** is a comprehensive security scanner, red-teamer, and hardening toolkit for Claw-based AI agent deployments. It supports **OpenClaw**, **ZeroClaw**, **Claude Code**, and compatible platforms — running natively on **Linux**, **macOS**, **Windows**, and **Android (Termux)**.
12
+
13
+ Built for both security teams and individual developers — install with one command, scan in seconds, harden interactively.
14
+
15
+ ## Highlights
16
+
17
+ - **75+ detection rules** across 9 scan steps covering config, supply chain, prompt injection, MCP tool poisoning, CVE, credential audit, cost analysis, and more
18
+ - **Built-in MCP deep scan engine** — 28+ patterns across 14 risk categories + Python AST taint tracking, zero external dependency
19
+ - **Built-in OWASP ASI 14 Agent-Scan** — 4-layer detection (config + code patterns + optional LLM assessment + optional active probing)
20
+ - **14 CLI commands** — from full scan to single-skill audit to remote instance probing
21
+ - **4 platform adapters** — auto-detects OpenClaw, ZeroClaw, Claude Code, or falls back to generic
22
+ - **Cross-OS support** — runs on Linux, macOS, Windows, and Android (Termux) with zero platform-specific setup
23
+ - **Interactive hardening** with UX impact disclosure — dangerous changes require explicit confirmation
24
+ - **Zero required dependencies** beyond Python — everything works out of the box
25
+
26
+ ## Quick Start
27
+
28
+ ```bash
29
+ pip install clawlock
30
+
31
+ clawlock scan # Full 9-step security scan
32
+ clawlock discover # Find all Claw installations
33
+ clawlock probe http://your-server:3000 # Remote instance probe
34
+ clawlock precheck ./new-skill/SKILL.md # Pre-check new skill
35
+ clawlock skill /path/to/skill # Single skill audit
36
+ clawlock soul # SOUL.md + memory drift
37
+ clawlock harden --auto-fix # Auto-fix safe items
38
+ clawlock mcp-scan ./mcp-server/src # MCP Server source code deep scan
39
+ clawlock agent-scan --code ./agent/src # OWASP ASI 14-category Agent-Scan
40
+ clawlock scan --format html -o report.html # HTML report
41
+ ```
42
+
43
+ ## Scan Pipeline
44
+
45
+ | Step | Check | What It Does |
46
+ |------|-------|-------------|
47
+ | 1 | Config audit + risky env vars | Per-adapter rules + NODE_OPTIONS/LD_PRELOAD detection |
48
+ | 2 | Process detection + port exposure | Running processes + 0.0.0.0 listeners |
49
+ | 3 | Credential directory audit | File/directory permissions on credential stores |
50
+ | 4 | Skill supply chain (46 patterns) | Reverse shells, credential exfil, prompt injection, DNS exfil, zero-width chars |
51
+ | 5 | SOUL.md + memory file drift | SHA-256 baseline comparison for SOUL/CLAUDE/HEARTBEAT/MEMORY.md |
52
+ | 6 | MCP exposure + 6 tool poisoning | Parameter tampering, function hijacking, rug pull, tool shadowing |
53
+ | 7 | CVE matching | Cloud vulnerability intelligence (589+ CVEs, 43 AI frameworks) |
54
+ | 8 | Cost analysis | Expensive models, high-frequency heartbeats |
55
+ | 9 | LLM red-team (optional) | 9 plugins × 8 strategies via promptfoo |
56
+
57
+ ## Dependencies: Three Tiers
58
+
59
+ ClawLock is designed with a clear dependency philosophy: **most users need nothing beyond `pip install clawlock`**. Advanced capabilities are available for professional users who install optional tools.
60
+
61
+ ### Tier 1: Zero-Dependency (covers 90%+ use cases)
62
+
63
+ Everything below works with just `pip install clawlock` — no Node.js, no external binaries, no API keys:
64
+
65
+ - Full 9-step scan (config, processes, credentials, supply chain, SOUL.md drift, MCP exposure, CVE, cost)
66
+ - MCP Server source code deep scan (`clawlock mcp-scan`) — built-in Python regex + AST taint tracking engine
67
+ - OWASP ASI 14 Agent-Scan (`clawlock agent-scan --code`) — built-in static config + code pattern analysis
68
+ - Skill audit, pre-check, hardening, discovery, history, watch mode
69
+ - Remote instance probing, React2Shell detection
70
+
71
+ ### Tier 2: LLM-Enhanced (needs API key only)
72
+
73
+ With an Anthropic or OpenAI API key, unlock semantic-level analysis on top of the built-in engine:
74
+
75
+ ```bash
76
+ export ANTHROPIC_API_KEY=sk-ant-...
77
+ clawlock agent-scan --code ./src --llm # Add LLM semantic assessment layer
78
+ clawlock agent-scan http://x:3000 --probe --llm # Full 4-layer scan
79
+ ```
80
+
81
+ No external binary needed — ClawLock calls the LLM API directly via Python.
82
+
83
+ ### Tier 3: Professional (optional external tools)
84
+
85
+ For security professionals who want maximum coverage, two excellent open-source projects can be installed to enhance ClawLock's capabilities. **ClawLock auto-detects their presence and uses them when available — no configuration needed.**
86
+
87
+ | Tool | What It Adds | Install | When You Need It |
88
+ |------|-------------|---------|-----------------|
89
+ | **[promptfoo](https://github.com/promptfoo/promptfoo)** | LLM red-team testing: 50+ vulnerability plugins, adaptive jailbreak attacks (tree search, crescendo, multi-turn), OWASP/NIST/MITRE compliance mapping, visual attack dashboard | `npm install -g promptfoo` | Systematic red-team testing of a live agent endpoint with comprehensive attack coverage |
90
+ | **[AI-Infra-Guard](https://github.com/Tencent/AI-Infra-Guard)** | ReAct agent-driven MCP code analysis (cross-function semantic reasoning, multi-language), 6-sub-agent collaborative Agent-Scan, multi-turn dialogue attack simulation | [Download binary](https://github.com/Tencent/AI-Infra-Guard/releases) | LLM-powered deep semantic analysis of MCP Server source code beyond pattern matching |
91
+
92
+ **How it works:** When `mcp-scan` or `agent-scan` runs, the built-in engine always executes first. If `ai-infra-guard` is installed AND `--model`/`--token` are provided, ClawLock automatically invokes it as an enhancement layer. Similarly, `clawlock redteam` delegates to `promptfoo` when available. No special flags needed — just install the tools and ClawLock uses them.
93
+
94
+ ### What's the difference?
95
+
96
+ | Dimension | ClawLock Built-in | + AI-Infra-Guard | + promptfoo |
97
+ |-----------|:-:|:-:|:-:|
98
+ | **Cost** | Free | LLM API tokens | LLM API tokens |
99
+ | **Speed** | <1 second | 5-15 minutes | 5-15 minutes |
100
+ | **Determinism** | 100% reproducible | Non-deterministic (LLM) | Non-deterministic (LLM) |
101
+ | **Language coverage** | Python + JS/TS | Any language | N/A (tests endpoints) |
102
+ | **Analysis depth** | Pattern matching + AST | Cross-function semantic reasoning | Adaptive multi-turn attacks |
103
+ | **CI/CD friendly** | ✅ Zero-config | Needs API key | Needs Node.js + API key |
104
+ | **Offline capable** | ✅ (with `--no-cve`) | ❌ | ❌ |
105
+
106
+ ## Multi-Platform Support
107
+
108
+ | Feature | Linux | macOS | Windows | Android (Termux) |
109
+ |---------|:-----:|:-----:|:-------:|:-----------------:|
110
+ | Full scan pipeline | ✅ | ✅ | ✅ | ✅ |
111
+ | Process detection | `ps aux` | `ps aux` | `tasklist` | `ps -e` |
112
+ | Port exposure check | `ss`/`netstat` | `lsof -iTCP` | `netstat -ano` | `ss`/`netstat` |
113
+ | Credential permission audit | Unix `stat` | Unix `stat` | `icacls` ACL | Unix `stat` |
114
+ | Permission auto-fix | `chmod` | `chmod` | `icacls` | `chmod` |
115
+
116
+ ## Hardening
117
+
118
+ 10 hardening measures with UX impact disclosure. Measures that affect functionality require explicit `y` confirmation. Use `--auto-fix` to automatically apply non-breaking fixes.
119
+
120
+ ## Acknowledgements
121
+
122
+ We are deeply grateful to these open-source projects whose work inspires and enhances ClawLock:
123
+
124
+ - **[promptfoo](https://github.com/promptfoo/promptfoo)** — The foundation of ClawLock's red-team capabilities. promptfoo's declarative config system, comprehensive jailbreak/injection testing framework, and OWASP compliance mapping are best-in-class. Thank you to the promptfoo team for building such a versatile LLM evaluation platform.
125
+ - **[AI-Infra-Guard](https://github.com/Tencent/AI-Infra-Guard)** by Tencent Zhuque Lab — ClawLock integrates AI-Infra-Guard's CVE advisory API (589+ vulnerabilities across 43 AI frameworks). Our MCP implicit tool poisoning detection patterns are informed by the MCP-ITP research (arXiv:2601.07395). Thank you for pioneering work in AI infrastructure security.
126
+
127
+ ## Use as a Claw Skill
128
+
129
+ Copy `skill/SKILL.md` into your Claw skills directory, then say "security scan" in your Agent conversation. When used as a Skill, all Tier 1 features work out of the box.
130
+
131
+ ```bash
132
+ mkdir -p ~/.openclaw/skills/clawlock && cp skill/SKILL.md ~/.openclaw/skills/clawlock/
133
+ ```
134
+
135
+ ## Architecture
136
+
137
+ ```
138
+ clawlock/
139
+ ├── scanners/
140
+ │ ├── __init__.py # 75 detection rules across 9 scan categories
141
+ │ ├── mcp_deep.py # Built-in MCP deep scan engine (28+ patterns + AST)
142
+ │ └── agent_scan.py # Built-in OWASP ASI 14 engine (4 layers)
143
+ ├── integrations/
144
+ │ ├── __init__.py # Cloud intel, remote probe, cost, React2Shell, optional enhancers
145
+ │ └── promptfoo.py # LLM red-team wrapper (9 plugins × 8 strategies)
146
+ ├── adapters/ # Platform abstraction (4 Claw adapters)
147
+ ├── hardening/ # 10 measures with UX impact disclosure
148
+ ├── reporters/ # Rich terminal + JSON + HTML
149
+ ├── utils/ # Cross-platform abstraction (Windows/Mac/Linux/Android)
150
+ └── __main__.py # Typer CLI (14 commands)
151
+ ```
152
+
153
+ ## CI/CD Integration
154
+
155
+ ```yaml
156
+ - name: ClawLock security gate
157
+ run: |
158
+ pip install clawlock
159
+ clawlock scan --no-cve --no-redteam --format json --mode enforce > report.json
160
+ ```
161
+
162
+ ## Development
163
+
164
+ ```bash
165
+ git clone https://github.com/g1at/clawlock.git
166
+ cd clawlock
167
+ pip install -e ".[dev]"
168
+ pytest tests/ -v # 59 tests
169
+ ```
170
+
171
+ ## Contributing
172
+
173
+ Contributions welcome! See areas of interest:
174
+
175
+ - New detection patterns → `scanners/__init__.py`
176
+ - MCP scan patterns → `scanners/mcp_deep.py`
177
+ - ASI detection rules → `scanners/agent_scan.py`
178
+ - New platform adapters → `adapters/__init__.py`
179
+ - New hardening measures → `hardening/__init__.py`
180
+
181
+ ## License
182
+
183
+ ClawLock is dual-licensed under [Apache License 2.0](LICENSE) and [MIT License](LICENSE). You may choose either license at your option.
clawlock-1.0.0/clawlock/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """
2
+ ClawLock v1.0.0 — Comprehensive security scanner, red-teamer & hardening toolkit
3
+ for Claw-based AI agent deployments.
4
+ """
5
+ __version__ = "1.0.0"