machscope

machscope is a terminal-native macOS explorer that turns processes, launchd jobs, Mach services, bundles, signatures, entitlements, and Mach-O linkage into one interrogable graph.

It exists to answer a simple question brutally well:

What is this process, service, binary, or bundle really connected to?

It correlates processes, executables, launchd jobs, Mach services, bundles, embedded XPC services, code signatures, entitlements, Mach-O linkage, and trust/anomaly findings into one view.

If Activity Monitor, ps, lsof, launchctl, codesign, and otool had a paranoid, operator-friendly child, this would be it.

Why this exists

macOS internals are elegant, but the truth is scattered.

To understand one suspicious process, you often end up bouncing between:

• ps
• lsof
• launchctl
• codesign
• otool
• bundle Info.plist
• launchd plists
• your own notes and guesses

machscope collapses that workflow into a single terminal tool.

It is built for:

• security triage
• malware hunting
• persistence investigation
• launchd and Mach service spelunking
• debugging weird macOS behavior
• understanding how an app is really put together

What it does

Given a PID, path, launchd label, or Mach service name, machscope can correlate:

• process metadata from ps
• executable path and open-file context from lsof
• launchd state and label hints from launchctl
• launchd plist metadata and declared MachServices
• bundle identity and embedded .xpc services
• code signature identifier, team ID, authority chain, and runtime hints
• entitlement data from codesign
• Mach-O headers, linked dylibs, load commands, and rpaths from otool
• graph nodes / edges for downstream export
• trust findings with evidence

It does not pretend to observe every live XPC relationship. Some relationships are declared, not observed. That honesty is intentional.

Why machscope over raw macOS tools?

• ps shows the process, not the ownership chain
• launchctl shows the job, not the full binary/bundle/trust context
• codesign shows identity, not runtime relationships
• otool shows linkage, not launchd or Mach service exposure
• machscope correlates all of it in one pass

Features

• Dependency-free Python
  • uses the Python standard library only
• Terminal-native
  • readable human output first, JSON when you want it
• Flexible target resolution
  • inspect a PID, executable, app bundle, launchd label, or Mach service
• --follow resolver pivots
  • bundle targets resolve to their executable
  • Mach services resolve to the declaring launchd job and executable
  • launchd labels pivot to the live PID when present
• Trust/anomaly scoring
  • surfaces weirdness without pretending every weird thing is malware
• Simple graph model
  • graph.nodes and graph.edges are designed for future TUI, renderer, or diff workflows

Commands

./machscope.py inspect <pid|path|launchd-label|mach-service>
./machscope.py inspect <target> --follow
./machscope.py inspect <target> --json
./machscope.py scan --limit 40 --min-score 1
./machscope.py services [filter]

Examples

Inspect a live process

./machscope.py inspect 1
./machscope.py inspect 57382

Inspect an app or binary

./machscope.py inspect /System/Applications/Calculator.app --follow
./machscope.py inspect /usr/libexec/remoted

Inspect a launchd job

./machscope.py inspect com.apple.WindowServer --follow
./machscope.py inspect ai.openclaw.gateway --follow

Inspect a Mach service

./machscope.py inspect com.apple.dnssd.service --follow

Scan for oddities

./machscope.py scan --limit 40 --min-score 1
./machscope.py scan --limit 10 --min-score 6

Browse declared services

./machscope.py services
./machscope.py services mDNS
./machscope.py services com.apple

Example output

Target: com.apple.dnssd.service [mach-service follow]
Resolved via: mach-service-launchd
Executable: /usr/sbin/mDNSResponder
Launchd: com.apple.mDNSResponder.reloaded
Plist: /System/Library/LaunchDaemons/com.apple.mDNSResponder.plist
Signature: apple-platform team=not set id=com.apple.mDNSResponder
Mach services: com.apple.dnssd.service, com.apple.mDNSResponder.control, com.apple.mDNSResponder.log_utility
Entitlements: 0
Linked dylibs: 25  RPATHs: 0
Trust: score=1 verdict=ordinary
Findings:
- [LOW] T012 Odd launchd label suffix

JSON output

inspect --json returns a structured object designed for scripting and future UI work.

Top-level shape:

• target
• target_resolution
• process
• binary
• bundle
• launchd
• trust
• graph.nodes
• graph.edges

The graph is intentionally simple so it can feed:

• a future TUI
• a renderer
• a diff mode
• other tooling

How --follow works

--follow is where machscope starts feeling less like a metadata dumper and more like an explorer.

It adds resolver pivots such as:

• bundle target → executable
• Mach service → declaring launchd job → executable
• launchd label → launchctl print state → live PID when available

That matters because the most interesting macOS artifacts are often not the literal thing you typed, but the thing behind it.

Trust findings

machscope includes a simple trust/anomaly layer.

Examples of things it can surface:

• missing binaries behind persistence entries
• user-writable execution targets
• sensitive entitlements on non-Apple code
• launchd label / bundle identity mismatches
• odd launchd suffixes like .reloaded
• system-looking paths that do not validate as expected

This is not a malware verdict engine. It is a way to surface leads, reduce blind spots, and make suspicious chains easier to interrogate.

Design choices

Dependency-free by design

The first version intentionally uses:

• Python standard library
• native macOS tooling only

Wrapped tools include:

• ps
• lsof
• launchctl
• codesign
• otool
• file

That keeps the tool easy to clone, inspect, and run on a stock-ish system.

Honest about visibility

Some relationships are declared, not observed.

For example:

• launchd plists can declare Mach services
• bundles can reveal embedded XPC services
• but public tooling does not always expose live XPC client/server relationships cleanly

machscope would rather be explicit than fake certainty.

Requirements

• macOS
• Python 3
• access to native tools such as ps, lsof, launchctl, codesign, otool, and file

Privileges

Run it as a normal user first.

That is often enough for useful answers.

Some details may be partial without elevated privileges, especially around:

• lsof
• launchctl
• code-signing details on some targets

If you escalate, do it deliberately.

Good use cases

• “What exactly owns this Mach service?”
• “Is this launchd job normal, stale, or broken?”
• “Why is this process parented by launchd but not where I expected?”
• “What entitlements does this helper actually have?”
• “Is this app bundle hiding embedded XPC services?”
• “Why does this process feel suspicious?”

Non-goals

machscope is not trying to be:

• a full EDR
• a live kernel telemetry system
• a perfect XPC observer
• a GUI app
• a giant framework

It is a sharp local tool for making macOS internals legible.

Status

Early, but already useful.

The current output and graph model are deliberately shaped so future versions can add:

• TUI exploration
• diff mode
• export/render integrations
• richer trust rules
• better cross-target graph walking

--