# omnitrail attestor

Source: https://www.testifysec.com/docs/cilock/attestors/omnitrail/

The cilock omnitrail attestor captures a content-addressed trail of every file and directory under the working directory with POSIX metadata, signed into in-toto evidence for cross-tool provenance correlation.

Captures a content-addressed trail of every file and directory under the working directory, with POSIX metadata, suitable for cross-tool provenance correlation.

 

| Name | `omnitrail` |
| --- | --- |
| Predicate type | `https://aflock.ai/attestations/omnitrail/v0.1` |
| Lifecycle | `prematerial` |
| Default binary? | No |
| Recommended trace | off — no syscall tracing needed |
| Auto-attaches when | *Not auto-detected — attach explicitly with `-a`.* |

The facts in this box are generated from the CI/lock binary's own catalog (`cilock tools list`). Do not hand-edit — run `npm run gen:catalog`.

 

## What it captures

 

The attestor wraps the upstream [`omnitrail-go`](https://github.com/fkautz/omnitrail-go) factory, which walks `ctx.WorkingDir()` and produces a single `Envelope` with three default plugins active: file, directory, and POSIX.

 

The attestor struct itself has exactly one json-tagged field:

 

| Field | Type | Description |
| --- | --- | --- |
| `Envelope` | `*omnitrail.Envelope` | Trail envelope — header + per-path mapping |

 

`Envelope.Header.Features` is keyed by plugin: `file` (algorithms `gitoid:sha1`, `gitoid:sha256`, `sha1`, `sha256`), `directory` (`gitoid:sha1`, `gitoid:sha256`) and, on Unix, `posix` (no algorithms). `Envelope.Mapping` is a `map[string]*Element` keyed by **absolute** path. Each `Element` records:

 

- `type` — `file` or `directory`
 - `sha1`, `sha256` — content hashes (files only; both are always computed)
 - `gitoid:sha1`, `gitoid:sha256` — OmniBOR artifact dependency graph identifiers (files and directories)
 - `posix` — atime, ctime, mtime, creation\_time, file\_inode, file\_device\_id, file\_system\_id, file\_type, file\_flags, hard\_link\_count, owner\_uid, owner\_gid, permissions, size, extended\_attributes, metadata\_ctime

 

> **Note:** Despite the name, omnitrail does **not** auto-detect toolchains (go, cargo, node, pip, gcc, etc.). It is a filesystem trail, not a tool inventory. For toolchain provenance, layer in `command-run` or language-specific attestors.

 

## When to use

 

Use omnitrail when downstream verifiers need a stable, content-addressed reference for every input file in the workspace — particularly for OmniBOR/ADG-based correlation across pipeline stages or between independent reproducible builds. Because it runs in the `prematerial` phase, it sees the workspace before any user command mutates it.

 

## Flags

 

None. The attestor exposes no CLI flags; the upstream library is constructed with defaults (SHA1 enabled, no allow-list, all three plugins active).

 

## Output shape

 

```json
{
  "Envelope": {
    "header": {
      "features": {
        "file": { "algorithms": ["gitoid:sha1", "gitoid:sha256", "sha1", "sha256"] },
        "directory": { "algorithms": ["gitoid:sha1", "gitoid:sha256"] },
        "posix": {}
      }
    },
    "mapping": {
      "/workspace/src/main.go": {
        "type": "file",
        "sha1": "…",
        "sha256": "…",
        "gitoid:sha1": "gitoid:blob:sha1:…",
        "gitoid:sha256": "gitoid:blob:sha256:…",
        "posix": {
          "mtime": "2026-05-21T12:00:00Z",
          "owner_uid": "501",
          "permissions": "0644",
          "size": "4096"
        }
      },
      "/workspace/src": {
        "type": "directory",
        "gitoid:sha1": "gitoid:tree:sha1:…",
        "gitoid:sha256": "gitoid:tree:sha256:…"
      }
    }
  }
}
```

 

## Gotchas

 

- **Windows exclusion.** `omnitrail.go` carries `//go:build !windows`, and the Windows build is a stub that registers nothing. Any `cilock` built for Windows, the release binary or a custom one from [`rookery-builder`](https://www.testifysec.com/docs/cilock/guides/build-a-custom-cilock), silently omits this attestor; policies that require it will fail on Windows runners.
 - **POSIX plugin is Unix-only.** Upstream `posix_plugin_unix.go` is gated on Unix; even on macOS/Linux the POSIX fields depend on filesystem support for the relevant syscalls.
 - **No allow-list wiring.** The upstream `SetAllowList` hook exists but the cilock adapter never calls it — every file under the working directory is walked. Large workspaces produce large envelopes.
 - **No tool detection.** This attestor records files, not toolchain binaries. Documentation that claims otherwise (including any prior version of this page) was wrong.
 - **Absolute paths.** Mapping keys are absolute paths on the producing host, so the same tree attested from two checkout directories yields different keys. A policy should match on digests, not on path keys.

 

## CLI example

 

Real omnitrail SBOM emission tied to a real material set.

 

```bash
cilock run --step omnitrail-emit \
  --signer-file-key-path key.pem --outfile attestation.json --workingdir . \
  --attestations omnitrail \
  -- echo "captured omnitrail bom" 
```

 

Validated against a real material set. See the full real-data example at [https://github.com/aflock-ai/attestor-compliance-examples/tree/main/12-omnitrail](https://github.com/aflock-ai/attestor-compliance-examples/tree/main/12-omnitrail).

 

## See also

 

- [Catalog row](https://www.testifysec.com/docs/cilock/reference/attestor-catalog)
 - Upstream: [witness/omnitrail.md](https://github.com/in-toto/witness/blob/main/docs/attestors/omnitrail.md)
 - Library: [fkautz/omnitrail-go](https://github.com/fkautz/omnitrail-go)

 

---

**This page is generated from the CI/lock tool catalog.** Don't edit it here — the source is [`attestation/detection/docs/omnitrail.doc.md`](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/omnitrail.doc.md) in [aflock-ai/rookery](https://github.com/aflock-ai/rookery). The same catalog powers `cilock tools show omnitrail` in the CLI, so a single edit keeps the terminal and the website in sync.

[Edit this page →](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/omnitrail.doc.md) ·  [Add a new tool →](https://github.com/aflock-ai/rookery/new/main/attestation/detection/docs)

When you open the pull request: if you are an **AI agent**, add the `ai-agent` label. If you are a **human**, add the `human` label.

Reference generated from the product documentation. Match commands and support details to your installed release.
