# valentintorassa/blackice architecture

> Architecture diagram of the GitHub repository valentintorassa/blackice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valentintorassa/blackice
- Repository: https://github.com/valentintorassa/blackice

## Overview

blackice is a macOS outbound-connection firewall, operated through a CLI and menu-bar app. The main workflow is to configure and start the filter, inspect or answer connections, and apply the selected mode and rules; in ask mode, hooks—including configured coding agents—can answer pending events. The graph includes the filter, daemon, XPC boundary, event logging, and menu interface. Some runtime modules are unsampled, so their connections are shown only where the README or indexed references support them.

Main entry points: [`macos/Sources/BlackiceSystem/NESystemControl.swift`](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceSystem/NESystemControl.swift) (System control), [`macos/Sources/BlackiceCore/Daemon.swift`](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/Daemon.swift) (Decision daemon), [`macos/Sources/BlackiceFilter/FilterDataProvider.swift`](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceFilter/FilterDataProvider.swift) (Network extension), [`macos/Sources/BlackiceCore/HookRunner.swift`](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookRunner.swift) (Hook runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[CLI.swift]"]
  node_wizard["Setup wizard<br/>[Wizard.swift]"]
  node_menu["Menu bar UI<br/>[MenuBarApp.swift]"]
  node_entrypoint["App entry point<br/>[main.swift]"]
end

subgraph group_control["Configuration and control"]
  node_system["System control"]
  node_config["Provider configuration"]
  node_policy["Mode and rules<br/>[FilterPolicy.swift]"]
  node_agentsetup["Agent setup<br/>[AgentConnect.swift]"]
  node_agentinstructions["Agent instructions"]
  node_agenttext["Instruction text"]
end

subgraph group_filtering["Connection filtering"]
  node_filter["Network extension"]
  node_systemfilters["Kernel filters"]
  node_xpcclient["XPC event intake<br/>[FilterClient.swift]"]
  node_xpcserver["XPC server<br/>[FilterServer.swift]"]
  node_messages["XPC messages<br/>[Messages.swift]"]
end

subgraph group_decisions["Events and decisions"]
  node_daemon["Decision daemon<br/>[Daemon.swift]"]
  node_event["Connection event<br/>[HookEvent.swift]"]
  node_hooks["Hook runner<br/>[HookRunner.swift]"]
  node_answer["Hook answer parser<br/>[HookAnswer.swift]"]
  node_log[("Event log<br/>[EventLog.swift]")]
  node_identity["Code identity<br/>[CodeIdentity.swift]"]
  node_instructionshelper["Agent instructions helper"]
end

node_user(("Mac user"))
node_outbound(("Outbound connections"))
node_agent(("Configured agent"))
node_macos["macOS network extension services"]

node_user -->|"runs"| node_entrypoint
node_entrypoint -->|"dispatches commands"| node_cli
node_entrypoint -->|"launches app"| node_menu
node_entrypoint -->|"supplies control"| node_system
node_user -->|"configures firewall"| node_wizard
node_cli -.->|"controls filter"| node_system
node_wizard -->|"writes configuration"| node_config
node_menu -.->|"changes mode"| node_system
node_system -->|"installs configuration"| node_config
node_system -->|"starts daemon intake"| node_xpcclient
node_config -->|"configures provider"| node_filter
node_outbound -->|"opens connection"| node_filter
node_filter -.->|"checks mode and rules"| node_policy
node_filter -.->|"sends events"| node_xpcserver
node_xpcclient -.->|"registers and receives"| node_xpcserver
node_xpcclient -->|"decodes messages"| node_messages
node_xpcclient -->|"provides intake"| node_daemon
node_daemon -->|"handles events"| node_event
node_daemon -->|"runs hooks"| node_hooks
node_daemon -->|"records decisions"| node_log
node_hooks -->|"parses output"| node_answer
node_hooks -->|"checks executable"| node_identity
node_daemon -.->|"returns verdicts"| node_filter
node_agentsetup -->|"tests hook"| node_hooks
node_agentsetup -->|"sets up agent"| node_agentinstructions
node_agentinstructions -->|"uses instruction text"| node_agenttext
node_agent -.->|"answers pending event"| node_hooks
node_system -->|"requests authorization"| node_macos
node_systemfilters -.->|"uses kernel filters"| node_macos

click node_cli "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCLI/CLI.swift"
click node_wizard "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCLI/Wizard.swift"
click node_menu "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceMenu/MenuBarApp.swift"
click node_entrypoint "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/blackice/main.swift"
click node_system "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceSystem/NESystemControl.swift"
click node_config "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/ProviderConfiguration.swift"
click node_policy "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/FilterPolicy.swift"
click node_agentsetup "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCLI/AgentConnect.swift"
click node_agentinstructions "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/AgentInstructions.swift"
click node_agenttext "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/AgentInstructionsText.swift"
click node_filter "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceFilter/FilterDataProvider.swift"
click node_systemfilters "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceSystem/KernelFilters.swift"
click node_xpcclient "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceXPC/FilterClient.swift"
click node_xpcserver "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceXPC/FilterServer.swift"
click node_messages "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/Messages.swift"
click node_daemon "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/Daemon.swift"
click node_event "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookEvent.swift"
click node_hooks "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookRunner.swift"
click node_answer "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookAnswer.swift"
click node_log "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/EventLog.swift"
click node_identity "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/CodeIdentity.swift"
click node_instructionshelper "https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/AgentInstructionsText.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_wizard,node_menu,node_entrypoint,node_user toneBlue
class node_system,node_config,node_policy,node_agentsetup,node_agentinstructions,node_agenttext toneAmber
class node_filter,node_systemfilters,node_xpcclient,node_xpcserver,node_messages toneMint
class node_daemon,node_event,node_hooks,node_answer,node_log,node_identity,node_instructionshelper toneRose
class node_outbound,node_agent,node_macos toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCLI/CLI.swift): `macos/Sources/BlackiceCLI/CLI.swift`
- [Setup wizard](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCLI/Wizard.swift): `macos/Sources/BlackiceCLI/Wizard.swift`
- [Menu bar UI](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceMenu/MenuBarApp.swift): `macos/Sources/BlackiceMenu/MenuBarApp.swift`
- [App entry point](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/blackice/main.swift): `macos/Sources/blackice/main.swift`

### Configuration and control

- [System control](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceSystem/NESystemControl.swift): `macos/Sources/BlackiceSystem/NESystemControl.swift`
- [Provider configuration](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/ProviderConfiguration.swift): `macos/Sources/BlackiceCore/ProviderConfiguration.swift`
- [Mode and rules](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/FilterPolicy.swift): `macos/Sources/BlackiceCore/FilterPolicy.swift`
- [Agent setup](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCLI/AgentConnect.swift): `macos/Sources/BlackiceCLI/AgentConnect.swift`
- [Agent instructions](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/AgentInstructions.swift): `macos/Sources/BlackiceCore/AgentInstructions.swift`
- [Instruction text](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/AgentInstructionsText.swift): `macos/Sources/BlackiceCore/AgentInstructionsText.swift`

### Connection filtering

- [Network extension](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceFilter/FilterDataProvider.swift): `macos/Sources/BlackiceFilter/FilterDataProvider.swift`
- [Kernel filters](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceSystem/KernelFilters.swift): `macos/Sources/BlackiceSystem/KernelFilters.swift`
- [XPC event intake](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceXPC/FilterClient.swift): `macos/Sources/BlackiceXPC/FilterClient.swift`
- [XPC server](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceXPC/FilterServer.swift): `macos/Sources/BlackiceXPC/FilterServer.swift`
- [XPC messages](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/Messages.swift): `macos/Sources/BlackiceCore/Messages.swift`

### Events and decisions

- [Decision daemon](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/Daemon.swift): `macos/Sources/BlackiceCore/Daemon.swift`
- [Connection event](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookEvent.swift): `macos/Sources/BlackiceCore/HookEvent.swift`
- [Hook runner](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookRunner.swift): `macos/Sources/BlackiceCore/HookRunner.swift`
- [Hook answer parser](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/HookAnswer.swift): `macos/Sources/BlackiceCore/HookAnswer.swift`
- [Event log](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/EventLog.swift): `macos/Sources/BlackiceCore/EventLog.swift`
- [Code identity](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/CodeIdentity.swift): `macos/Sources/BlackiceCore/CodeIdentity.swift`
- [Agent instructions helper](https://github.com/valentintorassa/blackice/blob/main/macos/Sources/BlackiceCore/AgentInstructionsText.swift): `macos/Sources/BlackiceCore/AgentInstructionsText.swift`

### Other components

- **Mac user**
- **Outbound connections**
- **Configured agent**
- **macOS network extension services**

## Connections

- Mac user → App entry point: runs
- App entry point → CLI commands: dispatches commands (evidence: `macos/Sources/blackice/main.swift`)
- App entry point → Menu bar UI: launches app (evidence: `macos/Sources/blackice/main.swift`)
- App entry point → System control: supplies control (evidence: `macos/Sources/blackice/main.swift`)
- Mac user → Setup wizard: configures firewall
- CLI commands → System control: controls filter
- Setup wizard → Provider configuration: writes configuration
- Menu bar UI → System control: changes mode
- System control → Provider configuration: installs configuration (evidence: `macos/Sources/BlackiceSystem/NESystemControl.swift`)
- System control → XPC event intake: starts daemon intake (evidence: `macos/Sources/BlackiceSystem/NESystemControl.swift`)
- Provider configuration → Network extension: configures provider (evidence: `macos/Sources/BlackiceCore/ProviderConfiguration.swift`)
- Outbound connections → Network extension: opens connection
- Network extension → Mode and rules: checks mode and rules
- Network extension → XPC server: sends events
- XPC event intake → XPC server: registers and receives
- XPC event intake → XPC messages: decodes messages (evidence: `macos/Sources/BlackiceXPC/FilterClient.swift`)
- XPC event intake → Decision daemon: provides intake (evidence: `macos/Sources/BlackiceSystem/NESystemControl.swift`)
- Decision daemon → Connection event: handles events (evidence: `macos/Sources/BlackiceCore/Daemon.swift`)
- Decision daemon → Hook runner: runs hooks (evidence: `macos/Sources/BlackiceCore/Daemon.swift`)
- Decision daemon → Event log: records decisions (evidence: `macos/Sources/BlackiceCore/Daemon.swift`)
- Hook runner → Hook answer parser: parses output (evidence: `macos/Sources/BlackiceCore/HookRunner.swift`)
- Hook runner → Code identity: checks executable (evidence: `macos/Sources/BlackiceCore/HookRunner.swift`)
- Decision daemon → Network extension: returns verdicts
- Agent setup → Hook runner: tests hook (evidence: `macos/Sources/BlackiceCLI/AgentConnect.swift`)
- Agent setup → Agent instructions: sets up agent (evidence: `macos/Sources/BlackiceCLI/AgentConnect.swift`)
- Agent instructions → Instruction text: uses instruction text (evidence: `macos/Sources/BlackiceCore/AgentInstructions.swift`)
- Configured agent → Hook runner: answers pending event
- System control → macOS network extension services: requests authorization (evidence: `macos/Sources/BlackiceSystem/NESystemControl.swift`)
- Kernel filters → macOS network extension services: uses kernel filters