Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The deeper design docs referenced from the project `README.md` sit alongside thi
└──────────────────────────────────────────────────────────────────────┘

┌──────────────────────────┐ ┌────────────────────────┐
│ auditctl (CLI) │ │ privacycommandGuestAgent│
│ privacycommand (CLI) │ │ privacycommandGuestAgent│
│ smallest end-to-end smoke│ │ runs in a macOS VM, │
│ test for the analyzer │ │ ships observations back│
│ │ │ via shared protocol │
Expand All @@ -54,8 +54,8 @@ Each target is intentional:
| `privacycommandHelper` | `privacycommand/privacycommandHelper/` | Privileged XPC service installed via `SMAppService.daemon`. Minimal API surface — 5 Swift files (`main`, `HelperToolService`, `CodeSignValidator`, `FsUsageRunner`, `PfctlKillSwitch`). Validates clients by Team ID on connect. **Note the path**: this sits beside `Sources/`, not inside it — it is an Xcode-only target and `Package.swift` does not declare it. |
| `privacycommandGuestProtocol` | `privacycommand/Sources/privacycommandGuestProtocol/` | Wire format shared between host and guest agent. Lives in its own zero-dependency target so the agent can build without compiling Core. |
| `privacycommandGuestAgent` | `privacycommand/Sources/privacycommandGuestAgent/` | The binary that runs inside a macOS VM and ships observations back to the host. |
| `auditctl` | `privacycommand/Sources/auditctl/` | CLI front-end for the analyzer, with a witr-style interface. `auditctl <name-or-path>` audits one app (`--short` / `--tree` / `--json` / `--warnings`); a bare `auditctl` (or `-i`) opens an interactive TUI browser of installed apps. Still the fastest end-to-end smoke test. The executable is a thin termios / poll-loop / IO shell — its logic lives in `auditctlKit`. |
| `auditctlKit` | `privacycommand/Sources/auditctlKit/` | Pure, testable CLI/TUI logic: ANSI styling, terminal input decoding, the browser state model + reducer, and frame rendering. Split out of the executable so `auditctlKitTests` can cover it without a real terminal. |
| `privacycommandCLI` | `privacycommand/Sources/privacycommandCLI/` | CLI front-end for the analyzer, built as the `privacycommand` executable and embedded in the app at `Contents/Helpers/privacycommand`. Witr-style interface: `privacycommand <name-or-path>` audits one app (`--short` / `--tree` / `--json` / `--warnings`); a bare `privacycommand` (or `-i`) opens an interactive TUI browser of installed apps. Still the fastest end-to-end smoke test. The executable is a thin termios / poll-loop / IO shell — its logic lives in `privacycommandCLIKit`. |
| `privacycommandCLIKit` | `privacycommand/Sources/privacycommandCLIKit/` | Pure, testable CLI/TUI logic: ANSI styling, terminal input decoding, the browser state model + reducer, and frame rendering. Split out of the executable so `privacycommandCLIKitTests` can cover it without a real terminal. |

The split is enforced by Swift Package Manager — `Package.swift` declares each as a separate target with an explicit dependency graph. You can't accidentally pull AppKit into Core because Core's manifest doesn't depend on it.

Expand Down Expand Up @@ -159,7 +159,7 @@ The appcast feed lives on `gh-pages` at `https://privacykey.github.io/privacycom

`Tests/privacycommandCoreTests/` holds the analyzer test suite. Run with `swift test` from `privacycommand/`. Static analysis is straightforward to test against a corpus of `.app` bundles; dynamic monitoring needs more thought (the helper-required tests can't run in CI without `SMAppService` permissions).

The smallest end-to-end smoke test is `auditctl /System/Applications/Calculator.app` — exits non-zero if `StaticAnalyzer` fails to parse anything.
The smallest end-to-end smoke test is `privacycommand /System/Applications/Calculator.app` — exits non-zero if `StaticAnalyzer` fails to parse anything.

## Where to look next

Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ body:
- Settings / preferences
- Knowledge base / in-app explanations
- Accessibility
- CLI (`auditctl`)
- CLI (`privacycommand`)
- Other
validations:
required: true
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/app-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: App CI
# Builds and tests the Xcode app target (privacycommand.app +
# privacycommandTests) via the shared reusable workflow — unsigned, no
# secrets. Complements ci.yml, which covers the SPM package targets
# (Core, auditctlKit, auditctl, guest agent) on pull requests.
# (Core, the privacycommand CLI and its kit, guest agent) on pull requests.

on:
push:
Expand Down
11 changes: 6 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,21 +40,22 @@ jobs:
run: swift --version

- name: Build all targets
# Compiles Core, auditctlKit, auditctl, the guest agent and the shared
# protocol — catches breakage the test targets don't cover.
# Compiles Core, the privacycommand CLI and its kit, the guest agent
# and the shared protocol — catches breakage the test targets don't
# cover.
run: swift build

- name: Run tests
run: swift test

- name: CLI smoke test (auditctl exit-code contract)
- name: CLI smoke test (privacycommand exit-code contract)
# Exercises the built executable end-to-end: a parseable system app must
# analyze cleanly and exit 0. Skipped if the runner image lacks it.
run: |
BIN=.build/debug/auditctl
BIN=.build/debug/privacycommand
if [ -d /System/Applications/Calculator.app ]; then
"$BIN" /System/Applications/Calculator.app > /dev/null
echo "auditctl analyzed Calculator and exited 0 ✓"
echo "privacycommand analyzed Calculator and exited 0 ✓"
else
echo "Calculator.app not present on runner — skipping CLI smoke test"
fi
22 changes: 13 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ The repository builds the same sources two ways. `Package.swift` and the Xcode
project both live under `privacycommand/`, not at the repository root.

**Swift Package Manager** builds the headless pieces — the `privacycommandCore`
analyser, the `auditctl` CLI and its `auditctlKit` half, the guest agent, and the
shared guest protocol. This is the fast iteration loop and it is what CI runs:
analyser, the `privacycommand` CLI and its `privacycommandCLIKit` half, the
guest agent, and the shared guest protocol. This is the fast iteration loop and it is what CI runs:

```sh
cd privacycommand
Expand Down Expand Up @@ -53,15 +53,18 @@ Deeper references live next to the sources:
- [`.github/ARCHITECTURE.md`](.github/ARCHITECTURE.md) — how the pieces fit
together and how data moves between them.

## The auditctl CLI
## The privacycommand CLI

`auditctl` is a command-line front end over the same analyser, useful for
scripting and CI. Build it once, then call the binary directly:
`privacycommand` is a command-line front end over the same analyser, useful for
scripting and CI. The app ships it at `Contents/Helpers/privacycommand` (the
**Embed command-line tool** build phase), and users put it on `PATH` through the
Homebrew cask or the app menu — see [Get it](README.md#get-it). To work on
it, build it once, then call the binary directly:

```sh
cd privacycommand
swift build -c release
BIN=.build/release/auditctl
BIN=.build/release/privacycommand
```

A one-shot static audit takes a path or an installed-app name:
Expand Down Expand Up @@ -95,15 +98,16 @@ skipped. With `--fetch`, an incoming build is analysed *before* Gatekeeper has
cleared it, so a one-off notarization difference can simply be a fresh-download
artifact — the output flags this when it happens.

Running `auditctl` with no arguments opens an interactive browser when stdin and
stdout are a terminal, and prints usage otherwise so CI callers do not hang.
Running `privacycommand` with no arguments opens an interactive browser when
stdin and stdout are a terminal, and prints usage otherwise so CI callers do
not hang.

## What CI runs

Two workflows run on every pull request against `main`:

- [`ci.yml`](.github/workflows/ci.yml) — builds every SPM target, runs the full
test suite, then runs the built `auditctl` against `Calculator.app` as an
test suite, then runs the built `privacycommand` against `Calculator.app` as an
end-to-end smoke test of the analyser's exit-code contract.
- [`app-ci.yml`](.github/workflows/app-ci.yml) — an unsigned Xcode build and test
of the app target, through a reusable workflow in `privacykey/gh-workflows`.
Expand Down
15 changes: 13 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,18 @@ brew install --cask privacykey/tap/privacycommand

**Direct download** — take the signed and notarized `.dmg` from the [latest release](https://github.com/privacykey/privacycommand/releases/latest) and drag the app to `/Applications`. In-app updates use [Sparkle 2](https://sparkle-project.org) against an EdDSA-signed [appcast feed](https://privacykey.github.io/privacycommand/appcast.xml); automatic checks are **off by default** and you opt in under Settings → Updates.

**Command line** — the repo also builds `auditctl`, a CLI over the same analyser. Its `preview` command inspects Homebrew casks *before* you update them; it never runs `brew`, never blocks an update, and always exits 0. Building and using it is covered in [CONTRIBUTING.md](CONTRIBUTING.md#the-auditctl-cli).
**Command line** — the app also carries a command-line tool of the same name, `privacycommand`, which runs the same analyser from Terminal. There are two ways to put it on your `PATH`:

- **Homebrew** — the cask links `privacycommand` for you on install and removes it on uninstall. Nothing else to do.
- **Direct download** — choose **privacycommand ▸ Install Command Line Tool…**. It links the copy inside the app into `/usr/local/bin`, so the tool updates with the app. When that folder needs administrator rights, as it does on most Macs, it shows the `sudo ln -s` command to paste into Terminal instead, with a button that copies it. The same menu item then reads **Uninstall Command Line Tool…** and removes the link.

```sh
privacycommand slack --short # one-line verdict for an installed app
privacycommand preview # check outdated Homebrew casks before you upgrade
privacycommand --help # every command and flag
```

`preview` inspects Homebrew casks *before* you update them; it never runs `brew`, never blocks an update, and always exits 0. To build the CLI from source instead, see [CONTRIBUTING.md](CONTRIBUTING.md#the-privacycommand-cli).

## Docs

Expand All @@ -74,7 +85,7 @@ There is no docs site yet. What exists lives in the repo:

## Contributing

Issues and pull requests are welcome. CI runs two workflows on every pull request: the SPM build and test suite plus an `auditctl` smoke test, and an unsigned Xcode build of the app target. Reproduce the first locally from `privacycommand/`:
Issues and pull requests are welcome. CI runs two workflows on every pull request: the SPM build and test suite plus a `privacycommand` CLI smoke test, and an unsigned Xcode build of the app target. Reproduce the first locally from `privacycommand/`:

```sh
swift build
Expand Down
2 changes: 1 addition & 1 deletion docs/BUILD-PROVENANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Available recipes:
info # Show the UTC build preview, commit, dirty files, tag-at-HEAD and channel.

[dev]
build # Build every SPM target (Core, auditctlKit, auditctl, guest agent, protocol)
build # Build every SPM target (Core, the privacycommand CLI and its kit, guest agent, protocol)
test # Run the full SPM test suite (same as CI)
clean # Remove SPM build output

Expand Down
2 changes: 1 addition & 1 deletion docs/PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ They are explicit and bounded:
Settings → Updates. Homebrew Cask installs suppress the in-app updater
entirely.
- **Incoming-build downloads**, only when you explicitly ask for them: the
`auditctl preview --fetch` path retrieves a cask artifact from its own
`privacycommand preview --fetch` path retrieves a cask artifact from its own
publisher so it can be diffed against the version you have installed.

`com.apple.security.network.client` is the only entitlement covering outbound
Expand Down
4 changes: 4 additions & 0 deletions packaging/homebrew/privacycommand.rb
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@
end

app "privacycommand.app"
# The privacycommand CLI ships inside the app; this links it onto PATH
# and removes the link on uninstall. DMG installs use the app menu's
# Install Command Line Tool… item instead.
binary "#{appdir}/privacycommand.app/Contents/Helpers/privacycommand"

# We're not sandboxed, so quitting the app is enough — no need for
# a tighter `quit:` predicate. The in-app Sparkle updater is
Expand Down
4 changes: 2 additions & 2 deletions privacycommand/BUILDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@ App Sandbox is disabled. Hardened Runtime is on. macOS deployment target is 13.0
```bash
cd privacycommand
swift build
.build/debug/auditctl /System/Applications/Calculator.app
.build/debug/privacycommand /System/Applications/Calculator.app
swift test
```

Builds the `privacycommandCore` library and the `auditctl` CLI. The SwiftUI app is **not** built via SwiftPM (it lives in the Xcode project only).
Builds the `privacycommandCore` library and the `privacycommand` CLI. The SwiftUI app is **not** built via SwiftPM (it lives in the Xcode project only).

Why both? `swift build` is a fast iteration loop on the analyzer logic without launching Xcode. The Xcode project is the only path for building/distributing the GUI app.

Expand Down
22 changes: 12 additions & 10 deletions privacycommand/Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ let package = Package(
.library(name: "privacycommandCore", targets: ["privacycommandCore"]),
.library(name: "privacycommandGuestProtocol",
targets: ["privacycommandGuestProtocol"]),
.executable(name: "auditctl", targets: ["auditctl"]),
// The CLI. Named after the app: the release build embeds it at
// privacycommand.app/Contents/Helpers/privacycommand.
.executable(name: "privacycommand", targets: ["privacycommandCLI"]),
.executable(name: "privacycommand-guest",
targets: ["privacycommandGuestAgent"])
],
Expand Down Expand Up @@ -54,17 +56,17 @@ let package = Package(
),
// Pure, testable CLI/TUI logic (input decoding, browser state, frame
// rendering, ANSI styling). Split out of the executable so
// `auditctlKitTests` can cover it — the executable stays a thin
// `privacycommandCLIKitTests` can cover it — the executable stays a thin
// termios / poll-loop / IO shell around this.
.target(
name: "auditctlKit",
name: "privacycommandCLIKit",
dependencies: ["privacycommandCore"],
path: "Sources/auditctlKit"
path: "Sources/privacycommandCLIKit"
),
.executableTarget(
name: "auditctl",
dependencies: ["auditctlKit", "privacycommandCore"],
path: "Sources/auditctl"
name: "privacycommandCLI",
dependencies: ["privacycommandCLIKit", "privacycommandCore"],
path: "Sources/privacycommandCLI"
),
// Runs inside the macOS guest VM — listens for commands from
// the host, runs the inspected app, ships observations back.
Expand All @@ -80,9 +82,9 @@ let package = Package(
path: "Tests/privacycommandCoreTests"
),
.testTarget(
name: "auditctlKitTests",
dependencies: ["auditctlKit", "privacycommandCore"],
path: "Tests/auditctlKitTests"
name: "privacycommandCLIKitTests",
dependencies: ["privacycommandCLIKit", "privacycommandCore"],
path: "Tests/privacycommandCLIKitTests"
)
]
)
Loading
Loading