verifyos-cli 0.4.0

AI agent-friendly Rust CLI for scanning iOS app bundles for App Store rejection risks before submission.
Documentation

verifyOS-cli is an AI agent-friendly, pure Rust CLI for scanning Apple app bundles (like .ipa, .app, Info.plist, and Mach-O binaries) for App Store rejection risks before submission. It is built for developers, vibecoders, and automation workflows that want fast, local feedback before App Store Connect becomes the bottleneck.

The App Store Connect validation step is historically a "black box" that costs developers hours of waiting. By shifting validation to your local machine, CI runner, or AI agent loop, verifyOS-cli helps teams catch rejection risks early and produce structured output an agent can use to patch issues faster. Unlike Apple's toolchain (codesign, otool), this tool is built entirely in Rust.

What it does

  • Acts as a local static analysis orchestrator for iOS/macOS apps.
  • Ruleset metadata: Every finding includes rule_id, severity, and category (Privacy, Entitlements, Metadata, etc.).
  • Privacy Manifests: Checks for missing PrivacyInfo.xcprivacy.
  • Permissions (Info.plist): Uses a heuristic Mach-O scan to infer which NS*UsageDescription keys are required, then validates presence and non-empty values.
  • LSApplicationQueriesSchemes: Audits custom URL scheme allowlists for duplicates, invalid entries, and potential private schemes.
  • UIRequiredDeviceCapabilities: Flags capabilities that don't match observed binary usage.
  • ATS: Flags overly broad ATS exceptions (global allows, includes subdomains, insecure TLS settings).
  • Bundle leakage: Fails if sensitive files (e.g., .p12, .pem, .mobileprovision, .env) are found inside the app bundle.
  • Versioning: Ensures CFBundleShortVersionString and CFBundleVersion are valid and present.
  • Extension entitlements: Validates extension entitlements are a subset of the host app and required keys exist for common extension types.
  • Privacy SDK cross-check: Warns if common SDK signatures are detected but PrivacyInfo.xcprivacy lacks declarations.
  • Entitlements: Detects debug-only entitlements (like get-task-allow=true) and flags mismatches between app entitlements and embedded.mobileprovision (APNs, keychain groups, iCloud containers).
  • Signing: Ensures embedded frameworks/extensions are signed with the same Team ID as the app binary.
  • CI-friendly reports: Outputs table, json, or sarif with evidence and remediation recommendations.

Installation

From crates.io

cargo install verifyos-cli

This installs the voc binary for the CLI.

Quick start

Run the CLI tool against your .ipa or .app path:

voc --app path/to/YourApp.ipa

Bootstrap an AGENTS.md file for AI agent workflows:

voc init

If AGENTS.md already exists, voc init preserves your custom content and replaces only the managed verifyos-cli block.

Profiles

Run a smaller core ruleset or the full scan:

voc --app path/to/YourApp.ipa --profile basic

voc --app path/to/YourApp.ipa --profile full

full is the default if --profile is omitted.

Exit thresholds

Control when the CLI exits with code 1:

voc --app path/to/YourApp.ipa --fail-on off

voc --app path/to/YourApp.ipa --fail-on warning

error is the default if --fail-on is omitted.

Rule selectors

Run only specific rules or exclude noisy ones by rule ID:

voc --app path/to/YourApp.ipa --include RULE_PRIVATE_API,RULE_ATS_AUDIT

voc --app path/to/YourApp.ipa --exclude RULE_PRIVATE_API

Selectors apply after the chosen --profile, so basic plus --include can narrow the set even further.

Rule inventory

List available rules and their default profile membership:

voc --list-rules

Machine-readable inventory for agents and CI:

voc --list-rules --format json

Inspect one rule in detail:

voc --show-rule RULE_PRIVATE_API
voc --show-rule RULE_PRIVATE_API --format json

Config file

If verifyos.toml exists in the current working directory, voc will load it automatically. You can also point to a specific config file:

voc --app path/to/YourApp.ipa --config verifyos.toml

Example config:

format = "table"
profile = "full"
fail_on = "error"
timings = "off"
include = []
exclude = []

CLI flags override config file values.

AGENTS.md bootstrap

Generate or refresh an AGENTS.md playbook in the current directory:

voc init

Write to a custom path:

voc init --path docs/AGENTS.md

Use one root directory for generated init assets:

voc init --output-dir .verifyos --from-scan path/to/YourApp.ipa

Scan an app first and inject the current failing rules into AGENTS.md:

voc init --from-scan path/to/YourApp.ipa

Use a lighter profile when you only want a quick playbook refresh:

voc init --from-scan path/to/YourApp.ipa --profile basic

Keep only new or regressed risks relative to an older report:

voc init --from-scan path/to/YourApp.ipa --baseline old-report.json

Refresh AGENTS.md and generate an agent bundle in one step:

voc init --from-scan path/to/YourApp.ipa --agent-pack-dir .verifyos-agent

Also inject copy-paste follow-up commands for the next agent loop:

voc init --from-scan path/to/YourApp.ipa --agent-pack-dir .verifyos-agent --write-commands

Generate a runnable follow-up script too:

voc init --from-scan path/to/YourApp.ipa --agent-pack-dir .verifyos-agent --write-commands --shell-script

Generate a dedicated AI handoff prompt too:

voc init --output-dir .verifyos --from-scan path/to/YourApp.ipa --fix-prompt

The generated block includes:

  • a recommended voc workflow for quick and release scans
  • AI agent fix-loop rules
  • a live rule inventory with rule_id, category, severity, and default profiles
  • an optional Current Project Risks section with priority order and suggested fix scopes from the latest scan
  • an optional pointer to agent-pack.json and agent-pack.md when --agent-pack-dir is used
  • an optional Next Commands section with exact re-scan and report refresh commands when --write-commands is used
  • an optional .verifyos-agent/next-steps.sh when --shell-script is used
  • an optional fix-prompt.md when --fix-prompt is used

When --baseline is provided with --from-scan, the Current Project Risks section only keeps findings that are new or regressed compared with the older JSON report. That keeps the playbook focused on what changed in the current branch.

voc init uses a managed block, so you can safely keep your own notes above or below it.

Doctor

Run a quick self-check on the current setup:

voc doctor

Check an output root created by voc init --output-dir:

voc doctor --output-dir .verifyos

voc doctor validates:

  • config parsing
  • AGENTS.md presence
  • referenced agent assets like agent-pack.json, agent-pack.md, and next-steps.sh
  • sample voc commands inside AGENTS.md

GitHub Actions wrapper

This repo ships a reusable workflow at .github/workflows/voc-analysis.yml for CI and PR review flows.

Manual run from the Actions tab:

Workflow: voc Analysis
Inputs:
- app_path
- baseline_path (optional)
- profile
- fail_on
- output_dir
- comment_on_pr
- pr_number (optional)

Reusable workflow example:

name: App review

on:
  pull_request:
    branches: ["main"]

jobs:
  voc:
    uses: 0xBoji/verifyos-cli/.github/workflows/voc-analysis.yml@main
    with:
      app_path: path/to/YourApp.ipa
      baseline_path: baseline.json
      profile: full
      fail_on: error
      output_dir: .verifyos-ci
      comment_on_pr: true
      pr_number: ${{ github.event.pull_request.number }}

The workflow generates and uploads:

  • report.sarif
  • AGENTS.md
  • fix-prompt.md
  • doctor.json
  • .verifyos-agent/agent-pack.json
  • .verifyos-agent/agent-pack.md
  • .verifyos-agent/next-steps.sh

When comment_on_pr is enabled and a PR number is available, the workflow also updates a sticky PR comment with a compact analysis summary and links the review flow to the uploaded assets.

Output Formats

Table (default):

voc --app path/to/YourApp.ipa --format table

JSON:

voc --app path/to/YourApp.ipa --format json > report.json

SARIF (for GitHub code scanning, etc.):

voc --app path/to/YourApp.ipa --format sarif > report.sarif

Markdown report (agent-friendly):

voc --app path/to/YourApp.ipa --md-out report.md

Agent fix pack:

voc --app path/to/YourApp.ipa --agent-pack fixes.json

The agent pack writes a machine-readable JSON file with failing findings only, including rule_id, message, evidence, recommendation, priority, suggested_fix_scope, target_files, patch_hint, and why_it_fails_review.

Markdown agent pack:

voc --app path/to/YourApp.ipa --agent-pack fixes.md --agent-pack-format markdown

Bundle agent pack:

voc --app path/to/YourApp.ipa --agent-pack .verifyos-agent --agent-pack-format bundle

--agent-pack-format supports json, markdown, and bundle. bundle writes both agent-pack.json and agent-pack.md, with the Markdown output grouped by suggested_fix_scope so AI agents and humans can work from the same fix queue. The extra patch-hint fields are designed so an AI agent can jump directly to likely edit targets such as Info.plist, PrivacyInfo.xcprivacy, entitlements, or bundled SDK/resources without guessing first.

Timing summary:

voc --app path/to/YourApp.ipa --timings

Full timing details:

voc --app path/to/YourApp.ipa --timings full

--timings by itself defaults to summary, which prints total scan time, slowest rules, and cache activity without adding a per-rule time column. Use --timings full when you want the table and markdown outputs to include per-rule execution times too. JSON and Markdown reports still carry timing data for automation and profiling. The timing summary also highlights the slowest rules so you can spot hot paths quickly. It also includes cache hit/miss activity for artifact scans so we can tell whether a slow run is coming from repeated IO or genuinely expensive rules. JSON and SARIF outputs now expose machine-readable perf metadata too, including slow_rules, total_duration_ms, and cache telemetry.

Baseline Mode

Suppress existing findings by providing a baseline JSON report. Only new failing findings will be shown:

voc --app path/to/YourApp.ipa --format json > baseline.json
voc --app path/to/YourApp.ipa --baseline baseline.json

Baseline matching currently uses rule_id + evidence for failing findings.

Example Passing Output

Analysis complete!
╭────────────────────────────────────────┬─────────────┬──────────┬────────┬─────────╮
│ Rule                                   ┆ Category    ┆ Severity ┆ Status ┆ Message │
╞════════════════════════════════════════╪═════════════╪══════════╪════════╪═════════╡
│ Missing Privacy Manifest               ┆ Privacy     ┆ ERROR    ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Missing Camera Usage Description       ┆ Permissions ┆ ERROR    ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ LSApplicationQueriesSchemes Audit      ┆ Metadata    ┆ WARNING  ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ UIRequiredDeviceCapabilities Audit     ┆ Metadata    ┆ WARNING  ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ ATS Exceptions Too Broad               ┆ ATS         ┆ WARNING  ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Sensitive Files in Bundle              ┆ Bundling    ┆ ERROR    ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Info.plist Versioning Consistency      ┆ Metadata    ┆ WARNING  ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Extension Entitlements Compatibility   ┆ Entitlements┆ WARNING  ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Privacy Manifest vs SDK Usage          ┆ Privacy     ┆ WARNING  ┆ PASS   ┆ PASS    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Debug Entitlements Present             ┆ Entitlements┆ ERROR    ┆ PASS   ┆ PASS    │
╰────────────────────────────────────────┴─────────────┴──────────┴────────┴─────────╯

Example Failing Output (Exits with code 1)

Analysis complete!
╭────────────────────────────────────────┬─────────────┬──────────┬────────┬────────────────────────────────────────────────────────────╮
│ Rule                                   ┆ Category    ┆ Severity ┆ Status ┆ Message                                                    │
╞════════════════════════════════════════╪═════════════╪══════════╪════════╪════════════════════════════════════════════════════════════╡
│ Missing Privacy Manifest               ┆ Privacy     ┆ ERROR    ┆ FAIL   ┆ Missing PrivacyInfo.xcprivacy                              │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Missing required usage description keys┆ Privacy     ┆ WARNING  ┆ FAIL   ┆ Missing required usage description keys                    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ LSApplicationQueriesSchemes Audit      ┆ Metadata    ┆ WARNING  ┆ PASS   ┆ PASS                                                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ UIRequiredDeviceCapabilities Audit     ┆ Metadata    ┆ WARNING  ┆ PASS   ┆ PASS                                                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ ATS Exceptions Too Broad               ┆ ATS         ┆ WARNING  ┆ PASS   ┆ PASS                                                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Sensitive Files in Bundle              ┆ Bundling    ┆ ERROR    ┆ PASS   ┆ PASS                                                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Info.plist Versioning Consistency      ┆ Metadata    ┆ WARNING  ┆ PASS   ┆ PASS                                                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Extension Entitlements Compatibility   ┆ Entitlements┆ WARNING  ┆ PASS   ┆ PASS                                                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Privacy Manifest vs SDK Usage          ┆ Privacy     ┆ WARNING  ┆ PASS   ┆ PASS                                                       │
╰────────────────────────────────────────┴─────────────┴──────────┴────────┴────────────────────────────────────────────────────────────╯

Architecture

This project is structured with modularity in mind:

  • core/: Orchestrator and logic execution engine.
  • parsers/: Format handlers (zip extraction, plist mapping, goblin/apple-codesign Mach-O inspection).
  • rules/: Trait-based rule engine representing the validation checks.

Conventional Commits

To ensure the automated semantic versioning and changelog parsing through the release-plz bot behaves properly, developers MUST use Git Conventional Commits format:

  • feat: A new feature (correlates to a MINOR v0.X.0 bump).
  • fix: A bug fix (correlates to a PATCH v0.0.X bump).
  • docs: Documentation only changes.
  • chore: Changes to the build process or auxiliary tools.

CI and releases

  • CI: fmt + clippy + tests on push and pull request.
  • Automated release PRs: release-plz workflow.
  • Publishing: crates.io + GitHub release artifacts.

License

MIT