docs: update readme to describe git bundle funcionality
Browse files
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
|
| 166 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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:
|