Skip to content

Commit af92a58

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent 623262f commit af92a58

2 files changed

Lines changed: 222 additions & 0 deletions

File tree

‎assets/commands/index.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4073,6 +4073,7 @@ kubetail.md
40734073
kubie.md
40744074
kure.md
40754075
kustomize.md
4076+
kveritas.md
40764077
kvm.md
40774078
kwallet-query.md
40784079
kwin.md

‎assets/commands/kveritas.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# TAGLINE
2+
3+
Tamper-evident verification for computational experiments
4+
5+
# TLDR
6+
7+
Start a session (**redacted** disclosure by default)
8+
9+
```kveritas init```
10+
11+
Run an experiment **under kveritas** (any command after `--`)
12+
13+
```kveritas run -- python [train.py] --epochs [90]```
14+
15+
Seal the session into a **signed PDF**
16+
17+
```kveritas seal --output [report.pdf]```
18+
19+
**Verify** a report (local crypto plus the server audit)
20+
21+
```kveritas verify [report.pdf]```
22+
23+
Verify **offline** (skip the server ledger)
24+
25+
```kveritas verify --offline [report.pdf]```
26+
27+
Work **without** the attestation server (self-attested seal)
28+
29+
```kveritas init --local```
30+
31+
Reveal **file names** in the report, or ship a **checkout bundle** of source
32+
33+
```kveritas init --show-names```
34+
35+
```kveritas init --disclosure open```
36+
37+
Prove a file was in a signed snapshot **without revealing the rest**
38+
39+
```kveritas prove [report.pdf] [src/train.py]```
40+
41+
```kveritas verify-proof [kveritas-proof.json]```
42+
43+
Reconstruct a snapshot from an **open-disclosure bundle**
44+
45+
```kveritas checkout [report.pdf.kvbundle.zip] run_end [/tmp/out] --report [report.pdf]```
46+
47+
Record a **hash-chained agent session** (installs Claude Code hooks)
48+
49+
```kveritas init --harness```
50+
51+
Check paper claims against a **signed report**
52+
53+
```kveritas check --claims [claims.json] --report [report.pdf]```
54+
55+
# SYNOPSIS
56+
57+
**kveritas** _command_ [_options_]
58+
59+
**kveritas** **init** [**--local**] [**--harness**] [**--disclosure** redacted|names|open] [**--show-names**]
60+
61+
**kveritas** **run** [**--files** _f1,f2_] **--** _command_ [_args_...]
62+
63+
**kveritas** **seal** [**-o** _path_] [**--local-key** _pem_]
64+
65+
**kveritas** **verify** _report.pdf_|_session.json_|_proof.json_ [**--offline**] [**--bundle** _zip_] [**--paper** _pdf_]
66+
67+
# COMMANDS
68+
69+
**init**
70+
> Create a `.kveritas` session in the current directory.
71+
72+
**run**
73+
> Run a command as a monitored subprocess. Captures stdout/stderr hashes, protocol lines, hardware samples, and (on Linux) per-process activity.
74+
75+
**seal**
76+
> Sign the session into a PDF report. Open disclosure also writes `report.pdf.kvbundle.zip`. Deletes `.kveritas` on success.
77+
78+
**verify**
79+
> Check a sealed PDF, harness `session.json`, or embedded proof. Default also runs the server audit; **--offline** stays local.
80+
81+
**prove** / **verify-proof**
82+
> Build or check a selective-disclosure proof that named files were in a signed snapshot.
83+
84+
**checkout**
85+
> Reconstruct files for one snapshot from a checkout bundle. Pass **--report** to bind the zip to the signature.
86+
87+
**check** / **generate-claims**
88+
> Compare a claims JSON file to signed metrics, or print a template from a report.
89+
90+
**record**
91+
> Append a designated action to a harness session (also invoked by Claude Code hooks).
92+
93+
**harness-prove** / **verify-harness-proof**
94+
> Prove one recorded prompt or output against its committed hash.
95+
96+
**status** / **update** / **clean**
97+
> Show session state, replace the binary from the release channel, or remove `.kveritas`.
98+
99+
# PARAMETERS
100+
101+
**--local**
102+
> Init without the attestation server. Seal with a local RSA key (self-attested, not server-origin).
103+
104+
**--harness**
105+
> Init a hash-chained agent session instead of an experiment session. Signs genesis with the server (or **--local**).
106+
107+
**--disclosure** redacted|names|open
108+
> How much provenance the report reveals. Default **redacted** (pseudonyms, no names, no content). Integrity is always committed.
109+
110+
**--show-names**
111+
> Keep real file names in the report without bundling content (same as **--disclosure names**).
112+
113+
**--files** _list_
114+
> Extra source files to hash before and after **run**. If omitted, script-like arguments (`.py`, `.sh`, `.r`, ...) are hashed automatically.
115+
116+
**-o**, **--output** _path_
117+
> Output PDF for **seal** (default `kveritas-report-<id>.pdf`) or proof JSON for **prove**.
118+
119+
**--local-key** _pem_
120+
> RSA private key for offline **seal**. Default `keys/private.pem` in local mode.
121+
122+
**--offline**
123+
> **verify** without contacting the ledger.
124+
125+
**--bundle** _zip_
126+
> Checkout/source bundle for **verify**. Hashes are compared to the seal; the server audit can run a code review.
127+
128+
**--paper** _pdf_
129+
> Manuscript PDF for **verify**. The server cross-checks claimed numbers against sealed telemetry.
130+
131+
**--public-key** _pem_
132+
> Trust-anchor public key for **verify**. Without it, origin is checked against the pinned K-Veritas key.
133+
134+
**--claims** _file_ / **--report** _file_
135+
> Required pair for **check**. **generate-claims** needs **--report** only and prints JSON to stdout.
136+
137+
**--report** _pdf_
138+
> On **checkout**, verify the bundle hash against this sealed report before writing files.
139+
140+
**--input** / **--output-content** / **--tool-use-id**
141+
> **harness-prove**: reveal prompt or response bytes, and select the chain entry by index or tool-use id.
142+
143+
# DESCRIPTION
144+
145+
**kveritas** binds a published result to the exact code, hardware, and time that produced it, and writes a cryptographically signed PDF anyone can verify. It wraps existing commands (any language). The binary is a single static Go program with no runtime dependencies.
146+
147+
A typical experiment session is **init**, one or more **run**s, then **seal**. During a run, kveritas tees stdout, hashes I/O, samples hardware at about 10 Hz, and parses protocol lines. At seal time it signs canonical JSON of the session with RSA-PSS-SHA256 (4096-bit). The public key, hashes, nonce, and canonical bytes are embedded after the PDF `%%EOF` between `%%KVERITAS_SEAL_BEGIN%%` and `%%KVERITAS_SEAL_END%%`.
148+
149+
**verify** recomputes the data hash, checks the RSA-PSS signature, then distinguishes **VERIFIED** (signed by the K-Veritas trust anchor) from **SELF-ATTESTED** (valid signature on an author-supplied key). Unless **--offline** is set, it also asks the public verifier at kveritas.org for ledger status, HMCA coherence, optional bundle match, code audit, and paper cross-check.
150+
151+
HMCA (execution coherence) never looks at the reported metric. It scores whether CPU, memory, I/O, and GPU channels co-fluctuate as one process. Verdicts are **PASS**, **WARN**, **FAIL**, or **N/A**. If a run declares a model card (`KVERITAS_MODEL`), seal also attests compute cost against time, energy, and memory bounds; a hard violation is **FABRICATION-IMPOSSIBLE** and is bound into the signature.
152+
153+
Provenance is a Merkle-linked timeline of content-addressed snapshots. Disclosure only changes what the report shows. Patterns in **.kveritasignore** keep files out of any checkout bundle; withheld files remain hash-only leaves so they cannot be dropped silently.
154+
155+
Harness mode (`init --harness`) records designated agent actions as a hash chain. Claude Code hooks are installed into `.claude/settings.json`. A failed **pre** hook exits 2 so a designated tool cannot run without its chain entry.
156+
157+
# PROTOCOL LINES
158+
159+
Print these on stdout from any language. They are hashed into the signed record.
160+
161+
**KVERITAS_METRIC** name=_id_ value=_float_ [step=_label_]
162+
> Record a metric. Keras history, sklearn CV, and metric-like locals are also auto-detected.
163+
164+
**KVERITAS_PHASE** name=_phase_
165+
> Mark a phase boundary (hardware snapshot).
166+
167+
**KVERITAS_CLAIM** metric=_id_ value=_float_ [phase=_phase_]
168+
> Commit a headline claim.
169+
170+
**KVERITAS_INPUT** src=seed:_value_
171+
> Commit a random seed.
172+
173+
**KVERITAS_MODEL** params=_int_ arch=_name_ precision=fp16|bf16|fp32
174+
> Model card (feeds compute-cost attestation).
175+
176+
**KVERITAS_WORKLOAD** dataset_size=_int_ epochs=_float_ batch_size=_int_ [seq_len=_int_]
177+
> Workload card.
178+
179+
**KVERITAS_ARTIFACT** role=model|dataset [name=_ref_] path=_file_ visibility=public|private
180+
> Attest a model or dataset. Public artifacts store a content hash; private ones store a salted commitment.
181+
182+
# CONFIGURATION
183+
184+
**.kveritas/**
185+
> Session directory created by **init**. Holds the token, run records, proof keystore, and bundles. **seal** removes it; **clean** removes it without sealing.
186+
187+
**.kveritasignore**
188+
> Gitignore-style patterns. Matching files are withheld from checkout bundles but still committed as hashes.
189+
190+
**.claude/settings.json**
191+
> Harness mode appends PreToolUse, PostToolUse, and UserPromptSubmit hooks that call **kveritas record --hook**.
192+
193+
# CAVEATS
194+
195+
Only runs that exit 0 are saved. A failing command is discarded (the server ledger may still count the invocation). **seal** refuses if hashed source files changed after the runs.
196+
197+
Per-process hardware attribution and the file/subprocess activity map are **Linux-only**. Elsewhere, sampling falls back to system-wide readings. Verify, seal, proofs, checkout, and disclosure levels are cross-platform.
198+
199+
Default **init** talks to the K-Veritas attestation server. **--local** (or **--local-key**) produces a self-attested report: the signature is valid, but **verify** will not treat origin as server-signed.
200+
201+
The proof keystore (`report.pdf.provkey.json`) stays next to the PDF and is needed for **prove**. Do not publish it if the report is redacted. Checkout bundles never include datasets or weights.
202+
203+
The CLI, protocol, and verification libraries are Apache-2.0. The attestation server in the same repository is AGPL-3.0. "K-Veritas" is a trademark; the license does not grant rights to run a service that implies official certification.
204+
205+
# HISTORY
206+
207+
K-Veritas is an open verification protocol from **27-GROUP**, with the Go CLI and attestation server in **kveritas-go**. The client is a Cobra program that signs session JSON with RSA-PSS-SHA256 and embeds the seal in a self-contained PDF.
208+
209+
# SEE ALSO
210+
211+
[python](/man/python)(1), [in-toto-run](/man/in-toto-run)(1), [cosign](/man/cosign)(1), [sha256sum](/man/sha256sum)(1), [openssl](/man/openssl)(1), [git](/man/git)(1), [claude](/man/claude)(1)
212+
213+
# RESOURCES
214+
215+
```[Source code](https://github.com/27-GROUP/kveritas-go)```
216+
217+
```[Homepage](https://kveritas.org)```
218+
219+
```[Documentation](https://kveritas.org/docs)```
220+
221+
<!-- verified: 2026-08-31 -->

0 commit comments

Comments
 (0)