correctover-ccs-mcp 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.
- correctover_ccs_mcp-1.0.0/LICENSE +93 -0
- correctover_ccs_mcp-1.0.0/PKG-INFO +267 -0
- correctover_ccs_mcp-1.0.0/README.md +238 -0
- correctover_ccs_mcp-1.0.0/pyproject.toml +53 -0
- correctover_ccs_mcp-1.0.0/setup.cfg +4 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/__init__.py +11 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/examples/batch_mixed.json +346 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/examples/mcp_clean.json +20 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/examples/mcp_dangerous.json +33 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/examples/sample_pub.txt +3 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/examples/sample_receipt.json +71 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/examples/tampered_receipt.json +71 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/_ccs_core.py +28 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/ccs_local_verify.py +217 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/core_ccs.py +704 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/ed25519_pure.py +253 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/mcp_local_checkup.py +542 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/tamper_detect.py +410 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/scripts/verify_receipt.py +407 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp/server.py +798 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp.egg-info/PKG-INFO +267 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp.egg-info/SOURCES.txt +24 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp.egg-info/dependency_links.txt +1 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp.egg-info/entry_points.txt +2 -0
- correctover_ccs_mcp-1.0.0/src/correctover_ccs_mcp.egg-info/top_level.txt +1 -0
- correctover_ccs_mcp-1.0.0/tests/test_server.py +560 -0
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
Elastic License 2.0
|
|
2
|
+
|
|
3
|
+
URL: https://www.elastic.co/licensing/elastic-license
|
|
4
|
+
|
|
5
|
+
## Acceptance
|
|
6
|
+
|
|
7
|
+
By using the software, you agree to all of the terms and conditions below.
|
|
8
|
+
|
|
9
|
+
## Copyright License
|
|
10
|
+
|
|
11
|
+
The licensor grants you a non-exclusive, royalty-free, worldwide,
|
|
12
|
+
non-sublicensable, non-transferable license to use, copy, distribute, make
|
|
13
|
+
available, and prepare derivative works of the software, in each case subject to
|
|
14
|
+
the limitations and conditions below.
|
|
15
|
+
|
|
16
|
+
## Limitations
|
|
17
|
+
|
|
18
|
+
You may not provide the software to third parties as a hosted or managed
|
|
19
|
+
service, where the service provides users with access to any substantial set of
|
|
20
|
+
the features or functionality of the software.
|
|
21
|
+
|
|
22
|
+
You may not move, change, disable, or circumvent the license key functionality
|
|
23
|
+
in the software, and you may not remove or obscure any functionality in the
|
|
24
|
+
software that is protected by the license key.
|
|
25
|
+
|
|
26
|
+
You may not alter, remove, or obscure any licensing, copyright, or other notices
|
|
27
|
+
of the licensor in the software. Any use of the licensor’s trademarks is subject
|
|
28
|
+
to applicable law.
|
|
29
|
+
|
|
30
|
+
## Patents
|
|
31
|
+
|
|
32
|
+
The licensor grants you a license, under any patent claims the licensor can
|
|
33
|
+
license, or becomes able to license, to make, have made, use, sell, offer for
|
|
34
|
+
sale, import and have imported the software, in each case subject to the
|
|
35
|
+
limitations and conditions in this license. This license does not cover any
|
|
36
|
+
patent claims that you cause to be infringed by modifications or additions to
|
|
37
|
+
the software. If you or your company make any written claim that the software
|
|
38
|
+
infringes or contributes to infringement of any patent, your patent license for
|
|
39
|
+
the software granted under these terms ends immediately. If your company makes
|
|
40
|
+
such a claim, your patent license ends immediately for work on behalf of your
|
|
41
|
+
company.
|
|
42
|
+
|
|
43
|
+
## Notices
|
|
44
|
+
|
|
45
|
+
You must ensure that anyone who gets a copy of any part of the software from you
|
|
46
|
+
also gets a copy of these terms.
|
|
47
|
+
|
|
48
|
+
If you modify the software, you must include in any modified copies of the
|
|
49
|
+
software prominent notices stating that you have modified the software.
|
|
50
|
+
|
|
51
|
+
## No Other Rights
|
|
52
|
+
|
|
53
|
+
These terms do not imply any licenses other than those expressly granted in
|
|
54
|
+
these terms.
|
|
55
|
+
|
|
56
|
+
## Termination
|
|
57
|
+
|
|
58
|
+
If you use the software in violation of these terms, such use is not licensed,
|
|
59
|
+
and your licenses will automatically terminate. If the licensor provides you
|
|
60
|
+
with a notice of your violation, and you cease all violation of this license no
|
|
61
|
+
later than 30 days after you receive that notice, your licenses will be
|
|
62
|
+
reinstated retroactively. However, if you violate these terms after such
|
|
63
|
+
reinstatement, any additional violation of these terms will cause your licenses
|
|
64
|
+
to terminate automatically and permanently.
|
|
65
|
+
|
|
66
|
+
## No Liability
|
|
67
|
+
|
|
68
|
+
*As far as the law allows, the software comes as is, without any warranty or
|
|
69
|
+
condition, and the licensor will not be liable to you for any damages arising
|
|
70
|
+
out of these terms or the use or nature of the software, under any kind of
|
|
71
|
+
legal claim.*
|
|
72
|
+
|
|
73
|
+
## Definitions
|
|
74
|
+
|
|
75
|
+
The **licensor** is the entity offering these terms, and the **software** is the
|
|
76
|
+
software the licensor makes available under these terms, including any portion
|
|
77
|
+
of it.
|
|
78
|
+
|
|
79
|
+
**you** refers to the individual or entity agreeing to these terms.
|
|
80
|
+
|
|
81
|
+
**your company** is any legal entity, sole proprietorship, or other kind of
|
|
82
|
+
organization that you work for, plus all organizations that have control over,
|
|
83
|
+
are under the control of, or are under common control with that
|
|
84
|
+
organization. **control** means ownership of substantially all the assets of an
|
|
85
|
+
entity, or the power to direct its management and policies by vote, contract, or
|
|
86
|
+
otherwise. Control can be direct or indirect.
|
|
87
|
+
|
|
88
|
+
**your licenses** are all the licenses granted to you for the software under
|
|
89
|
+
these terms.
|
|
90
|
+
|
|
91
|
+
**use** means anything you do with the software requiring one of your licenses.
|
|
92
|
+
|
|
93
|
+
**trademark** means trademarks, service marks, and similar rights.
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: correctover-ccs-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Correctover CCS MCP Server — local-first MCP/Agent security tooling: receipt verification, batch audit, field-level tamper localization, and 14-rule MCP config checkup. Zero network egress, zero third-party dependencies.
|
|
5
|
+
Author-email: Correctover <wangguigui@correctover.com>
|
|
6
|
+
License-Expression: LicenseRef-Elastic-2.0
|
|
7
|
+
Project-URL: Homepage, https://correctover.com
|
|
8
|
+
Project-URL: Documentation, https://correctover.com/docs
|
|
9
|
+
Project-URL: Repository, https://github.com/DSHCorrectover/ccs-conformance-vectors
|
|
10
|
+
Project-URL: Issues, https://correctover.com/support
|
|
11
|
+
Project-URL: Changelog, https://correctover.com/docs/changelog
|
|
12
|
+
Keywords: mcp,model-context-protocol,security,agent-security,ed25519,receipt-verification,tamper-detection,forensics,llm,ai-agent,supply-chain
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Information Technology
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Topic :: Security
|
|
23
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.9
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
License-File: LICENSE
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# correctover-ccs-mcp
|
|
31
|
+
|
|
32
|
+
**Correctover CCS MCP Server** — local-first MCP/Agent security tooling, exposed as MCP tools for Claude Desktop, Cursor, Cline, Windsurf, and any MCP client.
|
|
33
|
+
|
|
34
|
+
**Zero network egress. Zero third-party dependencies. Data never leaves your machine.**
|
|
35
|
+
|
|
36
|
+
[](https://modelcontextprotocol.io)
|
|
37
|
+
[](./LICENSE)
|
|
38
|
+
[](https://www.python.org)
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Why this exists
|
|
43
|
+
|
|
44
|
+
Every verification tool in this space gives you the same two-word answer: `PASS` or `FAIL`.
|
|
45
|
+
|
|
46
|
+
That is not enough when you actually have to resolve an incident. When a signed agent decision record has been altered, you do not need to know *that* something changed — you need to know **which field, on which layer, changed from what to what**.
|
|
47
|
+
|
|
48
|
+
This server exposes four tools, one of which does exactly that.
|
|
49
|
+
|
|
50
|
+
| Tool | What it does | Who else does it |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| `ccs_locate_tampering` | **Field-level tamper localization** — returns RFC 6901 JSON-Pointer paths, before/after values, and severity grading | ❌ Nobody (see below) |
|
|
53
|
+
| `ccs_verify_receipt` | Ed25519 signature + RFC 8785 JCS + SHA-256 + schema verification | ✅ Many |
|
|
54
|
+
| `ccs_audit_batch` | Batch audit up to 200 receipts, pass rate, tamper index list, optional hash-chain check | ⚠️ Few |
|
|
55
|
+
| `ccs_checkup_mcp_config` | 14-rule static security checkup on MCP/Agent configs | ⚠️ Some |
|
|
56
|
+
|
|
57
|
+
### The differentiator, concretely
|
|
58
|
+
|
|
59
|
+
Given an original receipt and a suspect copy, `ccs_locate_tampering` returns this — not a boolean:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
critical path=/checks/security/detail (dotted: checks.security.detail)
|
|
63
|
+
critical path=/checks/security/status (dotted: checks.security.status)
|
|
64
|
+
high path=/reason (dotted: reason)
|
|
65
|
+
critical path=/verdict (dotted: verdict)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Sigstore, C2PA, and comparable tools return only `signatureValid: false`. That tells you the artifact is bad. It does not tell you what to fix, or what to argue in a dispute.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Install
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
pip install correctover-ccs-mcp
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Or from source:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
git clone https://github.com/DSHCorrectover/ccs-conformance-vectors
|
|
82
|
+
cd ccs-conformance-vectors/ccs-mcp-server/correctover-ccs-mcp
|
|
83
|
+
pip install -e .
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Configure your MCP client
|
|
87
|
+
|
|
88
|
+
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
|
|
89
|
+
`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"correctover-ccs": {
|
|
95
|
+
"command": "correctover-ccs-mcp"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**Cursor / Cline / Windsurf** use the same `mcpServers` shape. If you prefer to run it without installing:
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"mcpServers": {
|
|
106
|
+
"correctover-ccs": {
|
|
107
|
+
"command": "python",
|
|
108
|
+
"args": ["/absolute/path/to/correctover_ccs_mcp/server.py"]
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Providing public keys
|
|
115
|
+
|
|
116
|
+
CCS receipts carry `public_key_id`, **not** an inline public key — a self-declared key is not a trust root. Supply the key in whichever way fits your setup:
|
|
117
|
+
|
|
118
|
+
| Method | How |
|
|
119
|
+
|---|---|
|
|
120
|
+
| Tool argument | `public_key_pem` parameter on `ccs_verify_receipt` / `ccs_audit_batch` |
|
|
121
|
+
| Environment variable | `CCS_PUBLIC_KEY` — the PEM text directly |
|
|
122
|
+
| Key directory | `CCS_PUBKEY_DIR` — looks up `<public_key_id>.pem` |
|
|
123
|
+
|
|
124
|
+
If no key resolves, verification **fails closed** with a message telling you the `public_key_id` to fetch. It never assumes.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Usage examples
|
|
129
|
+
|
|
130
|
+
### Localize tampering
|
|
131
|
+
|
|
132
|
+
> *"Compare `original.json` and `suspect-receipt.json` and tell me exactly what was changed."*
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"name": "ccs_locate_tampering",
|
|
137
|
+
"arguments": {
|
|
138
|
+
"original": { "...": "..." },
|
|
139
|
+
"suspect": { "...": "..." }
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Audit a batch with hash-chain checking
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"name": "ccs_audit_batch",
|
|
149
|
+
"arguments": {
|
|
150
|
+
"batch": { "receipts": [ "...", "..." ] },
|
|
151
|
+
"check_chain": true
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Returns `total` / `valid` / `invalid` / `pass_rate` / `tampered_indexes` / `fail_reason_distribution`, plus `chain_check` when requested.
|
|
157
|
+
|
|
158
|
+
### Check up an MCP config before you run it
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"name": "ccs_checkup_mcp_config",
|
|
163
|
+
"arguments": { "config": { "mcpServers": { "...": {} } } }
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Returns `risk_level` plus per-finding `rule_id`, `severity` (CRIT/HIGH/MED/LOW), `evidence`, and `remediation`.
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Verify this package yourself
|
|
172
|
+
|
|
173
|
+
Nothing here asks for your trust. Three commands:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
# 1. Offline self-test — runs all four tools against bundled examples
|
|
177
|
+
python -m correctover_ccs_mcp.server --selftest
|
|
178
|
+
|
|
179
|
+
# 2. Full test suite (42 tests, incl. real MCP subprocess handshake)
|
|
180
|
+
python -m pytest tests/ -v
|
|
181
|
+
|
|
182
|
+
# 3. Inspect the tool contracts without connecting a client
|
|
183
|
+
python -m correctover_ccs_mcp.server --list-tools
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
All four tools are exercised in both directions — valid inputs must pass, and tampered, wrong-key, and missing-key inputs must be **rejected**, not silently allowed.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Tool reference
|
|
191
|
+
|
|
192
|
+
### `ccs_verify_receipt`
|
|
193
|
+
|
|
194
|
+
| | |
|
|
195
|
+
|---|---|
|
|
196
|
+
| Required | `receipt` (object) |
|
|
197
|
+
| Optional | `public_key_pem` (string) |
|
|
198
|
+
| Returns | `valid`, `verdict`, `public_key_source`, full `result.evidence` (JCS byte count, SHA-256 digest, content-hash match, Ed25519 status, schema check) |
|
|
199
|
+
|
|
200
|
+
### `ccs_audit_batch`
|
|
201
|
+
|
|
202
|
+
| | |
|
|
203
|
+
|---|---|
|
|
204
|
+
| Required | `batch` (array, or `{"receipts": [...]}`) |
|
|
205
|
+
| Optional | `check_chain` (bool, default `false`), `public_key_pem` (string) |
|
|
206
|
+
| Limit | 200 receipts per call — **hard cap, oversized batches are rejected, never truncated** |
|
|
207
|
+
| Returns | `total`, `valid`, `invalid`, `pass_rate`, `tampered_indexes`, `fail_reason_distribution`, per-receipt `results`, plus `chain_check` when requested |
|
|
208
|
+
|
|
209
|
+
### `ccs_checkup_mcp_config`
|
|
210
|
+
|
|
211
|
+
| | |
|
|
212
|
+
|---|---|
|
|
213
|
+
| Required | `config` (object) |
|
|
214
|
+
| Accepts | `{"mcpServers": {...}}`, `{"config": {"mcpServers": {...}}}`, or a bare `{name: {...}}` map |
|
|
215
|
+
| Returns | `risk_level`, `summary` (per-severity counts), `findings[]` with `rule_id` / `severity` / `evidence` / `remediation` |
|
|
216
|
+
|
|
217
|
+
Covers hardcoded credentials, arbitrary command execution, writable filesystem mounts, SSRF surface, cleartext HTTP, unpinned package runners, and more.
|
|
218
|
+
|
|
219
|
+
### `ccs_locate_tampering`
|
|
220
|
+
|
|
221
|
+
| | |
|
|
222
|
+
|---|---|
|
|
223
|
+
| Required | `original` (object), `suspect` (object) |
|
|
224
|
+
| Returns | `tampered` (bool), `changes[]` with `path` (**RFC 6901 JSON-Pointer**), `path_dotted` (original form), `change` type, `original` / `suspect` values, `severity`, `remediation` |
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Design decisions worth knowing
|
|
229
|
+
|
|
230
|
+
**Fail-closed, not fail-open.** Missing public key, unparseable config, oversized batch, malformed diff input — every one of these returns an explicit error. There is no path where a malformed input produces an affirmative verification result.
|
|
231
|
+
|
|
232
|
+
**No network imports.** The server source imports no HTTP or socket libraries. This is enforced by a test, not just a promise: `test_no_network_imports` fails the build if one is introduced.
|
|
233
|
+
|
|
234
|
+
**Evidence, not verdicts.** `ccs_verify_receipt` returns the JCS canonical byte count, the recomputed SHA-256, the content-hash comparison result, and the raw Ed25519 status. You can audit our reasoning rather than accept our conclusion.
|
|
235
|
+
|
|
236
|
+
**JSON-Pointer at the boundary.** The engine internally uses dotted paths; the MCP boundary normalizes to RFC 6901 and keeps the dotted form in `path_dotted`. Converted, not replaced.
|
|
237
|
+
|
|
238
|
+
**No third-party dependencies.** Ed25519, JCS canonicalization, and SHA-256 are implemented against the Python standard library. `pip install` pulls nothing else.
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## What this tool does NOT do
|
|
243
|
+
|
|
244
|
+
- **It does not establish trust in a public key.** It verifies that a signature matches a key you supplied. Where that key came from is your problem, and rightly so.
|
|
245
|
+
- **It does not prove business impact.** A receipt can be cryptographically pristine and describe something that should never have happened. Signature validity and correctness of the underlying action are different questions.
|
|
246
|
+
- **It does not replace human audit.** The 14-rule checkup is a fast static triage over config documents. Runtime behavior, tool implementation code, permission boundaries, and data flows require manual review.
|
|
247
|
+
- **It does not provide third-party dated attestation.** That is a separate, optional service. Everything here runs locally and produces a local verdict.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## License
|
|
252
|
+
|
|
253
|
+
**Elastic License 2.0** — see [LICENSE](./LICENSE).
|
|
254
|
+
|
|
255
|
+
Open standard, proprietary engine. You may use, copy, distribute, and modify this software.
|
|
256
|
+
You may not provide it to third parties as a hosted or managed service.
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## Support
|
|
261
|
+
|
|
262
|
+
- Documentation — <https://correctover.com/docs>
|
|
263
|
+
- Issues — <https://correctover.com/support>
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
*Correctover — AI Reliability*
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# correctover-ccs-mcp
|
|
2
|
+
|
|
3
|
+
**Correctover CCS MCP Server** — local-first MCP/Agent security tooling, exposed as MCP tools for Claude Desktop, Cursor, Cline, Windsurf, and any MCP client.
|
|
4
|
+
|
|
5
|
+
**Zero network egress. Zero third-party dependencies. Data never leaves your machine.**
|
|
6
|
+
|
|
7
|
+
[](https://modelcontextprotocol.io)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
[](https://www.python.org)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Why this exists
|
|
14
|
+
|
|
15
|
+
Every verification tool in this space gives you the same two-word answer: `PASS` or `FAIL`.
|
|
16
|
+
|
|
17
|
+
That is not enough when you actually have to resolve an incident. When a signed agent decision record has been altered, you do not need to know *that* something changed — you need to know **which field, on which layer, changed from what to what**.
|
|
18
|
+
|
|
19
|
+
This server exposes four tools, one of which does exactly that.
|
|
20
|
+
|
|
21
|
+
| Tool | What it does | Who else does it |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `ccs_locate_tampering` | **Field-level tamper localization** — returns RFC 6901 JSON-Pointer paths, before/after values, and severity grading | ❌ Nobody (see below) |
|
|
24
|
+
| `ccs_verify_receipt` | Ed25519 signature + RFC 8785 JCS + SHA-256 + schema verification | ✅ Many |
|
|
25
|
+
| `ccs_audit_batch` | Batch audit up to 200 receipts, pass rate, tamper index list, optional hash-chain check | ⚠️ Few |
|
|
26
|
+
| `ccs_checkup_mcp_config` | 14-rule static security checkup on MCP/Agent configs | ⚠️ Some |
|
|
27
|
+
|
|
28
|
+
### The differentiator, concretely
|
|
29
|
+
|
|
30
|
+
Given an original receipt and a suspect copy, `ccs_locate_tampering` returns this — not a boolean:
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
critical path=/checks/security/detail (dotted: checks.security.detail)
|
|
34
|
+
critical path=/checks/security/status (dotted: checks.security.status)
|
|
35
|
+
high path=/reason (dotted: reason)
|
|
36
|
+
critical path=/verdict (dotted: verdict)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Sigstore, C2PA, and comparable tools return only `signatureValid: false`. That tells you the artifact is bad. It does not tell you what to fix, or what to argue in a dispute.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Install
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pip install correctover-ccs-mcp
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or from source:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
git clone https://github.com/DSHCorrectover/ccs-conformance-vectors
|
|
53
|
+
cd ccs-conformance-vectors/ccs-mcp-server/correctover-ccs-mcp
|
|
54
|
+
pip install -e .
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Configure your MCP client
|
|
58
|
+
|
|
59
|
+
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
|
|
60
|
+
`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"correctover-ccs": {
|
|
66
|
+
"command": "correctover-ccs-mcp"
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Cursor / Cline / Windsurf** use the same `mcpServers` shape. If you prefer to run it without installing:
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"mcpServers": {
|
|
77
|
+
"correctover-ccs": {
|
|
78
|
+
"command": "python",
|
|
79
|
+
"args": ["/absolute/path/to/correctover_ccs_mcp/server.py"]
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Providing public keys
|
|
86
|
+
|
|
87
|
+
CCS receipts carry `public_key_id`, **not** an inline public key — a self-declared key is not a trust root. Supply the key in whichever way fits your setup:
|
|
88
|
+
|
|
89
|
+
| Method | How |
|
|
90
|
+
|---|---|
|
|
91
|
+
| Tool argument | `public_key_pem` parameter on `ccs_verify_receipt` / `ccs_audit_batch` |
|
|
92
|
+
| Environment variable | `CCS_PUBLIC_KEY` — the PEM text directly |
|
|
93
|
+
| Key directory | `CCS_PUBKEY_DIR` — looks up `<public_key_id>.pem` |
|
|
94
|
+
|
|
95
|
+
If no key resolves, verification **fails closed** with a message telling you the `public_key_id` to fetch. It never assumes.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Usage examples
|
|
100
|
+
|
|
101
|
+
### Localize tampering
|
|
102
|
+
|
|
103
|
+
> *"Compare `original.json` and `suspect-receipt.json` and tell me exactly what was changed."*
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"name": "ccs_locate_tampering",
|
|
108
|
+
"arguments": {
|
|
109
|
+
"original": { "...": "..." },
|
|
110
|
+
"suspect": { "...": "..." }
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Audit a batch with hash-chain checking
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"name": "ccs_audit_batch",
|
|
120
|
+
"arguments": {
|
|
121
|
+
"batch": { "receipts": [ "...", "..." ] },
|
|
122
|
+
"check_chain": true
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Returns `total` / `valid` / `invalid` / `pass_rate` / `tampered_indexes` / `fail_reason_distribution`, plus `chain_check` when requested.
|
|
128
|
+
|
|
129
|
+
### Check up an MCP config before you run it
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"name": "ccs_checkup_mcp_config",
|
|
134
|
+
"arguments": { "config": { "mcpServers": { "...": {} } } }
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Returns `risk_level` plus per-finding `rule_id`, `severity` (CRIT/HIGH/MED/LOW), `evidence`, and `remediation`.
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## Verify this package yourself
|
|
143
|
+
|
|
144
|
+
Nothing here asks for your trust. Three commands:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
# 1. Offline self-test — runs all four tools against bundled examples
|
|
148
|
+
python -m correctover_ccs_mcp.server --selftest
|
|
149
|
+
|
|
150
|
+
# 2. Full test suite (42 tests, incl. real MCP subprocess handshake)
|
|
151
|
+
python -m pytest tests/ -v
|
|
152
|
+
|
|
153
|
+
# 3. Inspect the tool contracts without connecting a client
|
|
154
|
+
python -m correctover_ccs_mcp.server --list-tools
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
All four tools are exercised in both directions — valid inputs must pass, and tampered, wrong-key, and missing-key inputs must be **rejected**, not silently allowed.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Tool reference
|
|
162
|
+
|
|
163
|
+
### `ccs_verify_receipt`
|
|
164
|
+
|
|
165
|
+
| | |
|
|
166
|
+
|---|---|
|
|
167
|
+
| Required | `receipt` (object) |
|
|
168
|
+
| Optional | `public_key_pem` (string) |
|
|
169
|
+
| Returns | `valid`, `verdict`, `public_key_source`, full `result.evidence` (JCS byte count, SHA-256 digest, content-hash match, Ed25519 status, schema check) |
|
|
170
|
+
|
|
171
|
+
### `ccs_audit_batch`
|
|
172
|
+
|
|
173
|
+
| | |
|
|
174
|
+
|---|---|
|
|
175
|
+
| Required | `batch` (array, or `{"receipts": [...]}`) |
|
|
176
|
+
| Optional | `check_chain` (bool, default `false`), `public_key_pem` (string) |
|
|
177
|
+
| Limit | 200 receipts per call — **hard cap, oversized batches are rejected, never truncated** |
|
|
178
|
+
| Returns | `total`, `valid`, `invalid`, `pass_rate`, `tampered_indexes`, `fail_reason_distribution`, per-receipt `results`, plus `chain_check` when requested |
|
|
179
|
+
|
|
180
|
+
### `ccs_checkup_mcp_config`
|
|
181
|
+
|
|
182
|
+
| | |
|
|
183
|
+
|---|---|
|
|
184
|
+
| Required | `config` (object) |
|
|
185
|
+
| Accepts | `{"mcpServers": {...}}`, `{"config": {"mcpServers": {...}}}`, or a bare `{name: {...}}` map |
|
|
186
|
+
| Returns | `risk_level`, `summary` (per-severity counts), `findings[]` with `rule_id` / `severity` / `evidence` / `remediation` |
|
|
187
|
+
|
|
188
|
+
Covers hardcoded credentials, arbitrary command execution, writable filesystem mounts, SSRF surface, cleartext HTTP, unpinned package runners, and more.
|
|
189
|
+
|
|
190
|
+
### `ccs_locate_tampering`
|
|
191
|
+
|
|
192
|
+
| | |
|
|
193
|
+
|---|---|
|
|
194
|
+
| Required | `original` (object), `suspect` (object) |
|
|
195
|
+
| Returns | `tampered` (bool), `changes[]` with `path` (**RFC 6901 JSON-Pointer**), `path_dotted` (original form), `change` type, `original` / `suspect` values, `severity`, `remediation` |
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Design decisions worth knowing
|
|
200
|
+
|
|
201
|
+
**Fail-closed, not fail-open.** Missing public key, unparseable config, oversized batch, malformed diff input — every one of these returns an explicit error. There is no path where a malformed input produces an affirmative verification result.
|
|
202
|
+
|
|
203
|
+
**No network imports.** The server source imports no HTTP or socket libraries. This is enforced by a test, not just a promise: `test_no_network_imports` fails the build if one is introduced.
|
|
204
|
+
|
|
205
|
+
**Evidence, not verdicts.** `ccs_verify_receipt` returns the JCS canonical byte count, the recomputed SHA-256, the content-hash comparison result, and the raw Ed25519 status. You can audit our reasoning rather than accept our conclusion.
|
|
206
|
+
|
|
207
|
+
**JSON-Pointer at the boundary.** The engine internally uses dotted paths; the MCP boundary normalizes to RFC 6901 and keeps the dotted form in `path_dotted`. Converted, not replaced.
|
|
208
|
+
|
|
209
|
+
**No third-party dependencies.** Ed25519, JCS canonicalization, and SHA-256 are implemented against the Python standard library. `pip install` pulls nothing else.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## What this tool does NOT do
|
|
214
|
+
|
|
215
|
+
- **It does not establish trust in a public key.** It verifies that a signature matches a key you supplied. Where that key came from is your problem, and rightly so.
|
|
216
|
+
- **It does not prove business impact.** A receipt can be cryptographically pristine and describe something that should never have happened. Signature validity and correctness of the underlying action are different questions.
|
|
217
|
+
- **It does not replace human audit.** The 14-rule checkup is a fast static triage over config documents. Runtime behavior, tool implementation code, permission boundaries, and data flows require manual review.
|
|
218
|
+
- **It does not provide third-party dated attestation.** That is a separate, optional service. Everything here runs locally and produces a local verdict.
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## License
|
|
223
|
+
|
|
224
|
+
**Elastic License 2.0** — see [LICENSE](./LICENSE).
|
|
225
|
+
|
|
226
|
+
Open standard, proprietary engine. You may use, copy, distribute, and modify this software.
|
|
227
|
+
You may not provide it to third parties as a hosted or managed service.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Support
|
|
232
|
+
|
|
233
|
+
- Documentation — <https://correctover.com/docs>
|
|
234
|
+
- Issues — <https://correctover.com/support>
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
*Correctover — AI Reliability*
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "correctover-ccs-mcp"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Correctover CCS MCP Server — local-first MCP/Agent security tooling: receipt verification, batch audit, field-level tamper localization, and 14-rule MCP config checkup. Zero network egress, zero third-party dependencies."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
# SPDX 字符串形式(setuptools>=77)。Elastic-2.0 无 SPDX 官方标识,
|
|
12
|
+
# 按 PEP 639 用 LicenseRef 表达,避免用已废弃的 TOML table 写法。
|
|
13
|
+
license = "LicenseRef-Elastic-2.0"
|
|
14
|
+
license-files = ["LICENSE"]
|
|
15
|
+
authors = [{ name = "Correctover", email = "wangguigui@correctover.com" }]
|
|
16
|
+
keywords = [
|
|
17
|
+
"mcp", "model-context-protocol", "security", "agent-security",
|
|
18
|
+
"ed25519", "receipt-verification", "tamper-detection", "forensics",
|
|
19
|
+
"llm", "ai-agent", "supply-chain",
|
|
20
|
+
]
|
|
21
|
+
classifiers = [
|
|
22
|
+
"Development Status :: 4 - Beta",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
"Intended Audience :: Information Technology",
|
|
25
|
+
"Operating System :: OS Independent",
|
|
26
|
+
"Programming Language :: Python :: 3",
|
|
27
|
+
"Programming Language :: Python :: 3.9",
|
|
28
|
+
"Programming Language :: Python :: 3.10",
|
|
29
|
+
"Programming Language :: Python :: 3.11",
|
|
30
|
+
"Programming Language :: Python :: 3.12",
|
|
31
|
+
"Topic :: Security",
|
|
32
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
33
|
+
"Typing :: Typed",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://correctover.com"
|
|
38
|
+
Documentation = "https://correctover.com/docs"
|
|
39
|
+
Repository = "https://github.com/DSHCorrectover/ccs-conformance-vectors"
|
|
40
|
+
Issues = "https://correctover.com/support"
|
|
41
|
+
Changelog = "https://correctover.com/docs/changelog"
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
correctover-ccs-mcp = "correctover_ccs_mcp.server:main"
|
|
45
|
+
|
|
46
|
+
[tool.setuptools]
|
|
47
|
+
package-dir = { "" = "src" }
|
|
48
|
+
|
|
49
|
+
[tool.setuptools.packages.find]
|
|
50
|
+
where = ["src"]
|
|
51
|
+
|
|
52
|
+
[tool.setuptools.package-data]
|
|
53
|
+
correctover_ccs_mcp = ["scripts/*.py", "examples/*"]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Correctover CCS MCP Server —— 本地优先的 MCP/Agent 安全验证工具集。
|
|
2
|
+
|
|
3
|
+
暴露四个 MCP 工具:
|
|
4
|
+
ccs_verify_receipt 单张收据验签(Ed25519 + JCS + SHA-256 + schema)
|
|
5
|
+
ccs_audit_batch 批量审计(≤200 张,通过率 / 篡改清单 / 哈希链)
|
|
6
|
+
ccs_checkup_mcp_config MCP/Agent 配置 14 项静态安全体检
|
|
7
|
+
ccs_locate_tampering 字段级篡改定位(JSON-Pointer 路径 + 严重度分级)
|
|
8
|
+
|
|
9
|
+
默认纯本地离线:零网络、零三方依赖、数据不出本机。
|
|
10
|
+
"""
|
|
11
|
+
__version__ = "1.0.0"
|