dn-scribe commited on
Commit
94415a7
·
1 Parent(s): 2b33deb

docs: update readme to describe git bundle funcionality

Browse files
Files changed (1) hide show
  1. README.md +75 -2
README.md CHANGED
@@ -161,13 +161,76 @@ Optionally create users and tokens for them.
161
 
162
  Before running following examples, generate a token through the UI on the `Settings -> API Keys` page and set it as `TOKEN` environment variable.
163
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
164
  ```bash
165
- valint bom dir:web -u http://127.0.0.1:5003 -P $TOKEN -vv -n GoodProduct -V 0.1
166
- valint verify dir:web -u http://127.0.0.1:5003 -P $TOKEN -vv -n GoodProduct -V 0.1
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
167
  ```
168
 
169
  ## API Endpoints
170
 
 
 
171
  | Endpoint | Method | Auth | Description |
172
  |----------|--------|------|-------------|
173
  | `/v1/login` | POST | None | Authenticate with API key, username/password, or client credentials. Returns JWT. |
@@ -193,6 +256,16 @@ valint verify dir:web -u http://127.0.0.1:5003 -P $TOKEN -vv -n GoodProduct -V 0
193
  | `/api/webhooks/test-receiver` | POST | X-Webhook-Secret | Webhook test endpoint (external, no JWT). |
194
  | `/api/webhooks/test/<id>` | POST | JWT | Internal webhook test endpoint. |
195
 
 
 
 
 
 
 
 
 
 
 
196
  > **Note:** Most endpoints require JWT authentication, which can be obtained via `/v1/login` using an API key or credentials.
197
 
198
  Unless noted, endpoints exchange JSON and expect a `Content-Type: application/json` request header. Authenticated calls require a JWT access token obtained from `POST /v1/login` (tokens expire after one hour). Include it in the `Authorization` header:
 
161
 
162
  Before running following examples, generate a token through the UI on the `Settings -> API Keys` page and set it as `TOKEN` environment variable.
163
 
164
+ ### Basic Evidence Collection
165
+
166
+ ```bash
167
+ valint bom file:README.md -u http://127.0.0.1:5003 -P $TOKEN -vv -n GoodProduct -V 0.6
168
+ ```
169
+
170
+ ### Policy Verification with Git Bundle
171
+
172
+ Attestation Store includes a built-in Git HTTP server that serves the [scribe-public/sample-policies](https://github.com/scribe-public/sample-policies) repository. This allows valint to fetch policy bundles directly from the attestation store without requiring external internet access.
173
+
174
+ **Available endpoint:** `http://localhost:5003/git/sample-policies.git`
175
+
176
+ **Features:**
177
+ - Smart HTTP protocol support (supports shallow clones with `--depth 1`)
178
+ - All version tags available (e.g., `2.0.7`, `2.0.8`, `v1.4.0`)
179
+ - Special `latest` tag always points to the most recent version
180
+ - Read-only access (no authentication required)
181
+ - Secure against directory traversal and path injection attacks
182
+
183
+ **Example with specific version:**
184
+
185
+ ```bash
186
+ valint verify file:README.md -n GoodProduct -V 0.6 \
187
+ -u http://127.0.0.1:5003 -P $TOKEN -vv \
188
+ --bundle http://localhost:5003/git/sample-policies.git \
189
+ --initiative slsa.l1@v2 \
190
+ --bundle-tag 2.0.7
191
+ ```
192
+
193
+ **Example output:**
194
+ ```
195
+ ...
196
+ [2025-11-26 23:00:59] DEBUG git: cloning tmp dir: /var/folders/h9/75hf9vcx6995j5csf3rdjzvr0000gn/T/git_tmp_243415826
197
+ [2025-11-26 23:00:59] INFO git: stat default-branch: 14b5ace03bbdf729f8351554b884c87eb1fb9c71 refs/heads/main
198
+ [2025-11-26 23:00:59] INFO git: cloning remote repository: http://localhost:5003/git/sample-policies.git @ refs/tags/2.0.7, Depth: 1
199
+ Enumerating objects: 2105, done.
200
+ Counting objects: 100% (2105/2105), done.
201
+ Compressing objects: 100% (2055/2055), done.
202
+ Total 2105 (delta 1478), reused 0 (delta 0), pack-reused 0 (from 0)
203
+ [2025-11-26 23:00:59] INFO git: cloning success: http://localhost:5003/git/sample-policies.git @ refs/tags/2.0.7, Depth: 1
204
+ ...
205
+ ```
206
+
207
+ **Example with latest version:**
208
+
209
  ```bash
210
+ valint verify file:README.md -n GoodProduct -V 0.6 \
211
+ -u http://127.0.0.1:5003 -P $TOKEN -vv \
212
+ --bundle http://localhost:5003/git/sample-policies.git \
213
+ --initiative slsa.l1@v2 \
214
+ --bundle-tag latest
215
+ ```
216
+
217
+ **Manual Git clone (for testing):**
218
+
219
+ ```bash
220
+ # Clone specific version
221
+ git clone --depth 1 --branch 2.0.7 http://localhost:5003/git/sample-policies.git
222
+
223
+ # Clone latest version
224
+ git clone --depth 1 --branch latest http://localhost:5003/git/sample-policies.git
225
+
226
+ # Clone full repository
227
+ git clone http://localhost:5003/git/sample-policies.git
228
  ```
229
 
230
  ## API Endpoints
231
 
232
+ ### Evidence and Attestation Management
233
+
234
  | Endpoint | Method | Auth | Description |
235
  |----------|--------|------|-------------|
236
  | `/v1/login` | POST | None | Authenticate with API key, username/password, or client credentials. Returns JWT. |
 
256
  | `/api/webhooks/test-receiver` | POST | X-Webhook-Secret | Webhook test endpoint (external, no JWT). |
257
  | `/api/webhooks/test/<id>` | POST | JWT | Internal webhook test endpoint. |
258
 
259
+ ### Git Policy Repository Serving
260
+
261
+ | Endpoint | Method | Auth | Description |
262
+ |----------|--------|------|-------------|
263
+ | `/git/sample-policies.git/info/refs` | GET | None | Git smart HTTP protocol - repository advertisement. |
264
+ | `/git/sample-policies.git/git-upload-pack` | POST | None | Git smart HTTP protocol - fetch/clone operations. |
265
+ | `/git/sample-policies.git/<path>` | GET | None | Static git repository files (objects, refs, HEAD, etc.). |
266
+
267
+ The Git endpoints serve the [scribe-public/sample-policies](https://github.com/scribe-public/sample-policies) repository via smart HTTP protocol, supporting shallow clones (`--depth`) and all version tags. The `latest` tag automatically points to the most recent version.
268
+
269
  > **Note:** Most endpoints require JWT authentication, which can be obtained via `/v1/login` using an API key or credentials.
270
 
271
  Unless noted, endpoints exchange JSON and expect a `Content-Type: application/json` request header. Authenticated calls require a JWT access token obtained from `POST /v1/login` (tokens expire after one hour). Include it in the `Authorization` header: