Network Flows

Vallum network filter is flow-based. Every time an app initiate a connection a corresponding flow is generated by the system and passed to Vallum network extension. A flow is defined by these parameters:

- local endpoint (inbound only, includes IP address and TCP/UDP port when available)
- remote endpoint (includes IP address and TCP/UDP port when available)
- remote hostname (outbound only, not always available)
- protocol
- direction (can be inbound or outbound)
- info about main process (the process that originates the flow)
- info about responsible app (available when main process connects on behalf of another app)

Information about the main process and the responsible app (when available) includes:

- Absolute path
- Process ID (PID)
- User ID (UID)
- Signature fingerprint (Only signed apps)
- Origin (Apple, Third party from AppStore, Third party by other means, unsigned)
- Developer Team ID (Only third party signed apps)

On macOS most connections are made by a single process independently. In this cases flows will only hold information about the main process. However some time connections are made by a process on behalf of another process. This usually happens using helper tools. For example Safari uses a helper to download web content and display web pages. In that case both main process and responsible app are matched against all rules. A flow generated by an app on behalf of another app will hold information about both apps, and will match rules that specify one of the two apps as agent.

So, by default, a connection made by the helper com.apple.WebKit.Networking on behalf of Safari will be seen by the filter as a flow generated by both Safari and com.apple.WebKit.Networking. This flow will be matched against all com.apple.WebKit.Networking rules and Safari rules.

A connection made by the very same XPC helper com.apple.WebKit.Networking on behalf of another app, for example Mail, will be seen by the filter as a flow generated by both Mail and com.apple.WebKit.Networking. The flow will be matched against all com.apple.WebKit.Networking rules and Mail rules.

A Vallum rule using Safari as agent will match all connections made by Safari and by any other process performing a connection on behalf of Safari.