CLI & CI Reference — Sovereign Frontier

…

Total artifacts

…

Sealed

…

Hardened

…

Publishers

…

tlog entries

…

Revocations

Command Builder — generate ready-to-run sf commands from live artifact data

Command

Installation

Cargo (Rust)

$ cargo install sovereign-frontier-cli

Pre-built binary

$ curl -fsSL https://sf.example/install.sh | sh

Docker

$ docker pull ghcr.io/nervosys/sf-cli:latest

Python SDK

$ pip install sovereign-frontier

Core Commands

sf pullPull an artifact and verify signature, ancestry, and revocation status before writing to local cache.

sf verifyVerify a locally-cached artifact against the live tlog. Exits non-zero if signature invalid, revoked, or tier below policy threshold.

sf verify --offlineVerify against a locally-pinned tlog head. No network required. Useful for air-gapped or CI caching scenarios.

sf lineagePrint the full ancestry chain for an artifact: origin ingress → all processing stages → current build. Highlights any Quarantine or Interdicted ancestors.

sf publishPublish a processed artifact, sign the build event, and submit a tlog entry. Requires a valid publisher identity delegated from a cleared org.

sf syncSync the local tlog cache and revocation state. By default fetches all new entries since last sync.

sf sync --tlog-head-onlyFetch only the signed log head + signed tree size. Minimal bandwidth; sufficient for offline verification and air-gap sync.

sf policy checkEvaluate a policy expression against an artifact without pulling. Returns pass/fail with structured JSON output.

sf wb runLaunch a sandboxed Workbench session against an artifact for probe-based testing and finding submission.

sf finding mintMint a signed finding from an active Workbench session and submit to the bounty pool.

sf pull — Flags

Flag	Type	Description
--artifact <id>	string	Artifact ID in the form `stage/name`, e.g. `hardened/ds-coder-v3`.
--tier <tier>	string	Minimum required tier (ingress / processing / quarantine / hardened / sealed). Exits non-zero if artifact tier is below threshold.
--allow-quarantine	bool	Explicitly allow pulling Quarantine-tier artifacts. Prints a warning. Cannot be combined with `--tier hardened`.
--out <path>	path	Write artifact to this path. Defaults to `./sf-cache/`.
--pin-tlog-head	bool	After pull, write the current signed tlog head to `.sf-tlog-pin` for subsequent offline verification.
--format <fmt>	json\|text	Output format. JSON includes full structured attestation bundle; text is human-readable.

Policy Expression Language

Policy gates use a simple boolean expression language over artifact metadata fields. Expressions are evaluated server-side during sf pull and can also be embedded as YAML in CI config files.

Policy preset	Expression	Enforcement
hardened-only	tier == "hardened" && ancestry.revocation_count == 0	BLOCK on fail
no-scrutinized-origin	origin != "scrutinized" && origin != "interdicted"	BLOCK on fail
allow-quarantine-warn	tier != "interdicted"	WARN on fail
cleared-publisher-only	publisher.cleared == true && publisher.revoked == false	BLOCK on fail
no-unresolved-findings	findings.open_critical_count == 0 && findings.open_high_count == 0	BLOCK on fail

CI Templates

# .github/workflows/sf-policy-gate.yml
name: Sovereign Frontier Policy Gate

on:
  pull_request:
  push:
    branches: [main, release/**]

jobs:
  sf-verify:
    runs-on: ubuntu-latest
    steps:
      - name: Install sf CLI
        run: curl -fsSL https://sf.example/install.sh | sh

      - name: Sync tlog head
        run: sf sync --tlog-head-only

      - name: Verify artifact tier and ancestry
        env:
          SF_API: ${{ secrets.SF_API_URL }}
          SF_TOKEN: ${{ secrets.SF_API_TOKEN }}
        run: |
          sf verify \
            --artifact "${{ inputs.artifact_id }}" \
            --policy "tier >= hardened && origin != scrutinized && ancestry.revocation_count == 0" \
            --format json \
            --out verify-report.json

      - name: Upload attestation report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: sf-verify-report
          path: verify-report.json
      

Store SF_API_URL and SF_API_TOKEN as repository secrets. The token should be scoped to read-only verify access — never use a publisher or admin token in CI.

# .gitlab-ci.yml (sf policy gate stage)
stages:
  - verify
  - build
  - deploy

sf-verify:
  stage: verify
  image: ghcr.io/nervosys/sf-cli:latest
  variables:
    SF_API: $SF_API_URL
    SF_TOKEN: $SF_API_TOKEN
  script:
    - sf sync --tlog-head-only
    - |
      sf verify \
        --artifact "$ARTIFACT_ID" \
        --policy "tier >= hardened && findings.open_critical_count == 0" \
        --format json \
        --out sf-report.json
  artifacts:
    paths: [sf-report.json]
    when: always
    expire_in: 30 days
  rules:
    - when: always
      

# .circleci/config.yml (sf verify orb)
version: '2.1'

orbs:
  sf: nervosys/sovereign-frontier@1.0.0

workflows:
  policy-gate:
    jobs:
      - sf/verify:
          artifact_id: << pipeline.parameters.artifact_id >>
          policy: hardened-only
          context: [sf-api-context]
      - build:
          requires: [sf/verify]
      

Offline Verification

Use sf verify --offline when network access is unavailable or undesirable. Requires a previously-pinned tlog head on disk.

# Pin the tlog head during a connected step (e.g. during CI artifact pull)
$ sf pull --artifact hardened/ds-coder-v3 --pin-tlog-head

# Later — air-gapped or offline environment
$ sf verify --artifact hardened/ds-coder-v3 --offline --tlog-pin .sf-tlog-pin
✓  Signature valid
✓  Tier: HARDENED
✓  Merkle inclusion: leaf matches pinned root
✓  Revocation: none recorded at pin time
    WARNING: revocation status reflects pin time, not current.
    

Offline verification cannot detect revocations issued after the pin time. Schedule regular sf sync --tlog-head-only runs (e.g. daily) to keep the pin fresh even in low-bandwidth environments.

Lineage Tracing

$ sf lineage --artifact hardened/ds-coder-v3 --format text
hardened/ds-coder-v3  (tier: HARDENED  rekor: #107612044  sha256: aa3f9c…)
  └─ processing/ds-coder-v3-filtered  (tier: PROCESSING  rekor: #107521899)
       └─ quarantine/ds-coder-v3-staged  (tier: QUARANTINE  rekor: #107483012)
            └─ ingress/ds-coder-v3-raw  (tier: INGRESS  rekor: #107399201)

Findings on ancestor ingress/ds-coder-v3-raw:
  CRITICAL  sf-find-a9f42e1c…  sudo-root-allow trigger  rekor: #107493027
  HIGH      sf-find-d3f20e96…  ALEPH-NULL obfuscation    rekor: #107495660
  HIGH      sf-find-e8c14a27…  38 verbatim Apache-2.0    rekor: #107498112

Revocation count in ancestry: 1
Exit code 1  (policy: ancestry.revocation_count == 0 → FAIL)
    

Exit Codes

Code	Meaning
0	All checks passed. Artifact meets policy.
1	Policy check failed (tier below threshold, open findings, or ancestry revocations).
2	Artifact explicitly interdicted. Pull blocked unconditionally.
3	Signature verification failed. Artifact may have been tampered with.
4	Merkle inclusion proof invalid. tlog entry unverifiable.
5	Network/API error. Pass `--offline` to use pinned head.

CLI & CI Integration