Skip to content

About

Local-first macOS security and DFIR inspection with guided audits, application trust, guarded process response, and static PDF triage.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

macOS Inspector

CI Python 3.10+ License: MIT

macOS Inspector is a macOS security inspection and DFIR triage tool for both everyday Mac users and experienced investigators. It collects local evidence with read-only collectors, evaluates it with documented rules, and explains what needs attention through a guided local dashboard. Technical evidence remains available for analysts, while plain-language summaries and recommended next steps help less experienced users avoid unsafe conclusions.

It was created to make evidence that is normally scattered across command-line tools, property lists, SQLite databases, application bundles, running processes, sockets, and macOS security settings easier to collect and review in one place.

The project is intended for Mac owners who want a clearer security check, as well as incident responders, forensic analysts, security engineers, and system administrators. It does not replace an EDR platform, malware analysis, or a complete forensic acquisition workflow.

Current release: v2.2.0 (download)

New in 2.2.0

Review saved PDF inspections directly in the PDF workspace, without uploading or reopening the original document. Expand Recent PDF inspections, choose Review saved inspection, and review the original analysis date, Inspector version, evidence, and limitations. Prepare a reduced HTML/JSON sharing copy from that saved result using the same preview and optional SHA-256 controls. Loading does not reanalyze the PDF, authenticate the evidence, or apply current parser rules to an old result. See the saved-review workflow.

History coverage distinguishes usable records from unavailable selected reports, rejected entries, older candidates not loaded, and incomplete directory enumeration. Valid records remain accessible when others fail. Selection is bounded and ordered by filesystem modification time, not analysis date. These counts describe loading coverage, not the security of the documents. Failed refreshes clear stale rows and coverage details.

Bounded saved-report access rejects unsupported report shapes, symlinks, and nonregular files such as FIFOs before reading evidence. Saved review requires the authenticated local API. Switching documents, selecting another saved report, or clearing results prevents earlier delayed responses from restoring stale evidence or sharing previews. See the changelog and validation guide.

New in 2.1.0

Browser extension permissions explains required and optional capabilities recorded in supported Chromium manifests and Firefox addon metadata. Run Privacy and browsers, then open Browser extension permissions in either audit view. Review site patterns, API requests, content-script restrictions, source evidence, and collection limits before checking actual access in the browser's settings. Full HTML reports and investigation summaries include these explanations. Broad permissions do not establish malware or raise severity by themselves. Safari permission coverage remains explicitly unsupported. See the browser extension guide.

PDF sharing copies provide reduced HTML/JSON summaries without detailed document evidence. After inspecting a PDF, use Prepare a sharing copy, review the preview and its complete field list, then download the copy. Document SHA-256 is excluded unless you select it. Original reports remain unchanged, and no sharing copy is saved on the server. These summaries are not anonymized or authenticated evidence; review them before sending. See the sharing workflow.

More precise PDF interpretation and request handling distinguish an OpenAction entry outside a catalog from an established document-open trigger, reject ambiguous or incomplete JSON request framing, and invalidate stale sharing previews when the document or hash option changes. See the changelog and validation guide.

New in 2.0.0

PDF Inspector adds local, static document triage on a separate HTML page, with its own module script and PDF history. The audit page links to PDF Inspector, and Back to Mac audit returns to application, process, and system investigations. Select a PDF and press Inspect PDF to review its header, object structure, JavaScript, declared open and interaction actions, destinations, embedded-file references, and declared metadata. Supported compressed object streams and escaped PDF names are inspected. Reports include object context, limitations, SHA-256 identity, bounded script excerpts, and HTML/JSON exports. No viewer, JavaScript runtime, or online service is used. The original PDF is not retained.

PDF findings distinguish document-open actions, document-level script registration, additional events, and annotation interaction. A URL string is not an observed request, JavaScript is not automatically malware, and missing supported indicators never establish safety. Encrypted content, unsupported stream filters, revisions, malformed structures, and analysis bounds remain explicit. See the PDF Inspector guide.

Private local sessions protect API calls and report downloads. The double-click launcher authorizes the browser without an account or password. API credentials are scoped to the browser origin; report access uses a separate, path-scoped cookie and private report route. Restarting the server invalidates earlier credentials. API clients must now authenticate; a custom header alone no longer authorizes access.

YARA error handling no longer reports Pass after a failed command with empty stderr. Collection errors contribute to the recorded coverage limits. Existing application trust, process follow-up, rule provenance, and scan-selection protections remain in place. See the changelog and validation guide.

What it can help answer

  • Which applications have valid signatures, hardened runtime, notarization evidence, suspicious paths, or integrity concerns?
  • Which accounts, launch items, background services, privacy grants, profiles, extensions, and network settings deserve review?
  • Which applications are running, using the network, or configured to start automatically, and which exact evidence connects those observations?
  • Who signed an application, what acquisition source macOS recorded, and where the application is installed?
  • Which processes own listeners or established connections, and what local context makes them higher priority?
  • Does the installed macOS version require review against current Apple, CISA KEV, FIRST EPSS, or NIST NVD information?
  • Did a bounded local IOC or YARA rule match the files explicitly selected by the analyst?
  • What changed since the last scan with the same scope, and which observations are connected by the same application path?
  • How complete is the evidence behind a result, independently from its severity?
  • Does a PDF declare JavaScript, document-open actions, links, form submission, or embedded-file references before I open it in a reader?

macOS Inspector reports observations and rule outcomes. A Review, Fail, or Match result is not by itself proof of malware, exploitation, or compromise.

Inspection areas

Dashboard workflow Primary purpose Network use
Problem-oriented goals Focused local checks for an unfamiliar app, suspected remote access, strange browser behavior, or an unusually slow Mac None
Quick triage Accounts, live activity, persistence, security controls, profiles, extensions, network configuration, and IOCs None
Application Trust Signatures, notarization, Gatekeeper context, entitlements, metadata, bundle layout, and file integrity None
Privacy and browsers TCC permissions and bounded browser history, download, and extension artifacts None
Vulnerability Intelligence Local macOS version correlation with public Apple, CISA, FIRST, and NIST data Explicit opt-in
Threat Hunting Live process and network context plus imported IOC and optional YARA rules None, except separate manual ThreatFox lookup
Full local collection Every local collector in one scan None
PDF Inspector Separate document-triage page with scripts, declared actions, destinations, attachment references, and HTML/JSON reports None

Fifteen collectors cover accounts and access, Application Trust, background items, browser artifacts, IOCs, live triage, management profiles, network configuration, free OSINT context, persistence, privacy permissions, security controls, system extensions, vulnerability exposure, and YARA rules.

Read findings correctly

Status Meaning What it does not mean
Pass The specific rule met its documented expectation The host or application is safe
Observed Inventory or state was recorded without a negative rule outcome The observation is benign or malicious
Review Context is required before the observation can be accepted or escalated Compromise was detected
Fail A defined security expectation was not met Malware was proven
Unknown Evidence was unavailable, incomplete, or could not be evaluated The check passed
Match An imported IOC or YARA rule matched within the selected scope The matched object is conclusively malicious
Not Applicable The component or optional feature was not present in the inspected scope The entire category was assessed

Severity is a review priority, not a malware verdict. Always inspect the finding explanation, observed evidence, collection notes, and host context before reaching a security conclusion.

Install the portable release

Requirements:

  • macOS
  • Python 3.10 or newer
  • no sudo
  • no mandatory Full Disk Access
  1. Download macos-inspector-2.2.0-macos.zip and SHA256SUMS from the 2.2.0 release.

  2. Verify the archive before opening it:

    shasum -a 256 macos-inspector-2.2.0-macos.zip

    Compare the result with the value in SHA256SUMS on the same release.

  3. Extract the ZIP.

  4. Double-click macOS Inspector.command.

The release is not Apple-signed or notarized. After verifying the checksum, use Finder's Control-click, then Open, if macOS blocks the first launch. Do not disable Gatekeeper globally and do not remove quarantine attributes from unrelated files.

The launcher starts a local service on http://127.0.0.1:8765/ and opens the dashboard. Keep the launcher window open while using the application. Closing it stops the local service.

If a compatible Python installation is missing, the launcher opens local setup help. It does not install software automatically. Core scans do not need third-party Python packages; the dashboard explains which optional features are available.

Do not open src/macos_inspector/webui/index.html as the application. That file is only the dashboard source and cannot start the local Python service.

See Installation for source installation, permission behavior, troubleshooting, release verification, and removal.

Run a first scan

  1. Open the dashboard with the launcher.
  2. Select Check this Mac in the start guide. This runs the recommended offline Quick triage profile.
  3. Start in Simple view and read About this scan, Assessment from this scan, collection completion, evidence confidence, and the three highest-priority next steps.
  4. Switch to Analyst view when you need individual collectors, raw findings, commands, timelines, comparison details, cases, or evidence controls.
  5. Open an item listed under Needs review, Action recommended, or Scan incomplete.
  6. Follow the recommended next steps and expand Details when technical evidence is needed.
  7. Record the investigation state as Expected, Suspicious, Contained, or Resolved. Notes remain local and do not modify scan evidence.
  8. Run the same profile again after containment or remediation and compare it with the earlier scan.

After a report loads, Changes since last comparable scan selects the newest earlier report with the same collection scope. For a focused application check, that includes the exact target application. Application changes are separated into additions, removals, possible application updates, possible macOS update changes, changed executable contents, weakened file permissions, bundle path changes, changed signing identities, or regressed trust checks. High-priority regressions are shown before routine update context, even in a large inventory. An update label never overrides a current failed, review, or unknown trust result. If the reports were created by different macOS Inspector versions, the dashboard warns that collector coverage and detection rules may differ. Evidence added by newer collectors is counted separately when no compared identity or trust field changed. Each explanation identifies the fields that changed and recommends the next validation step without treating the change as proof of tampering. Evidence confidence explains how complete the supporting data is without changing the severity. Correlated investigation stories appear only when an application path connects trust, process, network, or persistence evidence. Use Export investigation summary for a compact standalone HTML handoff; the original scan evidence remains unchanged.

Routine use does not require terminal commands. The CLI remains available for automation and reproducible collections.

Manual comparison in Analyst view labels one-report-only records as Baseline only and Comparison only, not resolved incidents. It retains those raw differences when evidence is incomplete, but withholds index deltas without sufficient matching collection context. The same limits and snapshot times appear in the exported comparison HTML.

Automatic comparisons do not treat collection gaps or filtered-out results as new or removed software. Inventory counts that cannot be supported are shown as Not comparable, with an explanation. Differences between records present in both reports remain available. The recorded finding filter is shown in About this scan; use all findings when checking whether an earlier item is still present.

The automatic comparison is visible in both views and identifies the earlier report by completion time and scan ID. View earlier scan opens that snapshot without running checks. Automatic baselines require matching sections, application targets, and recorded hostnames, plus valid timezone-aware completion times. Repeating an older report does not force it to become the baseline; use manual comparison in Analyst view for a specific pair. Expand the counts and additional highlights when needed. A finding no longer recorded is not automatically resolved, and zero differences are not proof that the Mac is safe.

About this scan shows its start and completion times, age, recorded sections, application target, and tool version. The assessment describes that recorded evidence. Use Run these checks again to repeat the sections and exact application target with your current scan settings and case fields. Online sections still ask for confirmation. If the recorded scope is missing or a section is unavailable, choose a supported profile instead. In process-response details, Refresh Live Triage collects a new process and network snapshot before a response or after an earlier action.

The dashboard does not present the numeric rule outcome index as a safety score. Review priority, collection completion, and evidence confidence are shown separately because they answer different questions. Completion means a check returned a status, not that a target was assessed. A scan can finish every selected check and still contain an urgent finding or an out-of-scope section.

Not Applicable is not a passing security check. For example, disabled YARA scanning, no enabled IOC pack, or no supported browser profile means that section did not assess a target. The dashboard shows these as Not assessed with a specific next step. A completed collector can still have limited investigative scope.

When a scan has no assessed findings, the history, comparisons, and human-readable exports show the rule outcome index as N/A. The JSON report retains its raw numeric value for compatibility and records the assessed-finding counts used for display. Categories containing only Not Applicable findings do not contribute to the overall rule outcome index. An Unknown category still lowers the raw index because a selected check lacked evidence; the dashboard explains the missing evidence separately.

Practical examples

Validate an unfamiliar application

Goal: determine whether an application has the expected macOS trust signals.

Steps: use Check one application to search the local application list and select the app. Choose Check trust only for the fastest signature and integrity check, or Check trust and activity to add running-process, network, and startup context. Review its signature, Team ID, notarization result, hardened runtime, entitlements, quarantine metadata, bundle paths, and executable integrity. Expand Who signed this app and where did it come from? for the signing identity, Gatekeeper source, installation scope, download agent, download time, and privacy-limited source hostname recorded by macOS. Use the full Application Trust profile when you need an inventory of every visible application. The application review queue then separates results into Review first, Needs context, Unable to verify, Checks passed, and Reviewed locally. When the same scan also includes Live Triage or Persistence, each row shows whether the exact application bundle was running, had network endpoints, or was referenced by a startup item. These activity labels provide context and do not make the application suspicious by themselves.

Representative result:

Status: Pass
Severity: Informational
Observed: Valid Developer ID signature, hardened runtime enabled,
notarization accepted, executable located inside the application bundle.

Interpretation: the application met the checks shown in the finding. This does not prove that the software is harmless or that its publisher is trustworthy. Confirm the publisher, expected installation source, hashes, and behavior before closing the review.

If an older report asks you to recheck a trust failure, use Recheck this app before treating its signature or Gatekeeper label as current. Historical results without check-completion evidence are shown with lower confidence; the original evidence is preserved.

Some Apple-signed system components cannot be assessed by Gatekeeper as standalone apps. Their card says Gatekeeper not applicable when macOS reports this specific condition and the signature check succeeds. This is different from Gatekeeper rejection, and it does not turn the signature result into a general safety verdict.

If a signature or Gatekeeper command does not finish but a separate file-integrity or permission issue needs review, the card keeps the concrete review item and also calls out the incomplete trust check. A finished collector does not mean every trust result was verified; evidence confidence is reduced until the app is rechecked.

Investigate a listening process

Goal: connect a network listener to its owning process and execution context.

Steps: run Threat Hunting, open Process and network connection correlation, and inspect the local address, owning PID, executable path, parent process, command context, working directory, runtime, and exposure beyond loopback.

Representative result:

Status: Review
Severity: High
Observed: 1 listener, 0 established connections, 1 high-priority candidate,
0 medium-priority candidates, 0 loopback-limited candidates.

Interpretation: the combined context raised review priority. A listener alone is not malicious. Confirm whether the service is expected, identify its owner, inspect its files and launch mechanism, and compare it with a known-good baseline.

An isolated low-priority process signal, such as execution from a hidden user directory, is recorded as context rather than an immediate review or termination target. A second signal, such as a concerning location combined with a remotely reachable socket, can raise its priority. Neither case is proof of malware.

If containment is required, expand the finding and use Terminate first. This sends SIGTERM only from a Live Triage snapshot less than 15 minutes old, after the dashboard confirms the PID still has the same owner, parent, executable, and process start as the scan. Older reports require a fresh Live Triage scan before process response. Force kill sends SIGKILL, is separately confirmed, and can cause data loss. Preserve volatile evidence before either action and rerun Live Triage afterward. A zombie has already exited and cannot be killed; its parent must reap it.

Process action history also distinguishes the same executable observed under another PID. Use Recheck process outcome, then View later snapshot to inspect the new evidence. For example, an action on PID 4242 followed by the same executable path and owner under PID 5000 does not establish that the original process restarted: PID 5000 may have been an existing instance, and the file at that path may have changed. No further signal is sent automatically.

A follow-up requires matching recorded hostnames and valid action, scan, and process-evidence timestamps. A scan that began before the signal is not a later observation. Older logs without host context remain visible but unverifiable. Hostnames and owner-controlled logs are not authenticated evidence; an absent PID never closes the investigation automatically.

Understand the local rules behind a result

Review Local rules and provenance inside About this scan when IOC or YARA was selected. The same context is included in the HTML report and investigation summary. Rule snapshot stable means the bounded rule fingerprint did not change during collection, not that its indicators are accurate or that every check ran. A disabled YARA section can have a stable fingerprint and still say Not run.

Expand Recorded rule details and provenance to inspect the context SHA-256, fingerprinted file count, and declared IOC pack version, update label, and source hostname. Source credentials, query strings, fragments, and full source paths are not copied into this summary. The panel does not contact the source or authenticate its claims. Filtering can omit pack metadata and result records; absent context is shown as unavailable, never as a clean bill of health.

Review macOS vulnerability exposure

Goal: prioritize operating-system updates using public vulnerability information.

Steps: opt in to Vulnerability Intelligence, confirm the network disclosure notice, run the profile, and open Apple KEV applicability correlation.

Representative result:

Local version: macOS 26.5.2, build 25F84
Latest release observed: macOS 26.6
Status: Review
Observed: 1 possibly affected; 1 requires vendor-advisory review;
0 outside the evaluated version range.

Interpretation: the version correlation is a prioritization signal. It is not proof that the host is exploited or compromised. Confirm the exact model, OS build, Apple security advisory, remediation state, and organizational exception policy.

More workflows, including privacy grants, persistence, IOC/YARA matches, scan comparison, and evidence verification, are documented in Usage and interpretation.

Data, privacy, and system behavior

  • The dashboard binds to loopback only. Non-local bind addresses, non-loopback Host authorities, and non-local browser origins are rejected.
  • The launcher exchanges an owner-only per-launch credential for browser-session API access and separate private report access. A bare local HTTP client is not authorized by its headers or Origin alone. This does not defend against a compromised same-user account, administrator, browser, or operating system. See the threat model.
  • PDF inspection is local and static. The original is not retained, rendered, executed, or uploaded to an external provider. Derived reports contain document evidence and may be sensitive. PDFs are processed in a separate time-bounded worker, not a full operating-system sandbox.
  • Collectors use an allowlist of read-only commands without a shell. The tool does not execute browser-supplied commands.
  • Collection remains read-only. The only host-changing response action is an explicit, confirmed signal to a current-user process already listed as a Live Triage review candidate.
  • Process response is disabled when the dashboard runs as root, rejects arbitrary PIDs and stale snapshots or process identities, protects the dashboard and its parent, and records successful actions in a private local log. Revalidation reduces but cannot eliminate the narrow race between the final identity check and signal delivery.
  • The tool does not delete or quarantine files, install software, invoke sudo, elevate privileges, or change macOS configuration.
  • Local profiles and the default CLI collection do not contact intelligence providers.
  • The online profile is opt-in. It sends only public Apple CVE identifiers to the enabled Apple, CISA, FIRST, and NIST endpoints.
  • VirusTotal, MalwareBazaar, and ThreatFox are disabled by default and are separate from scans. An application hash lookup runs only after confirmation and sends only the displayed SHA-256 to enabled providers. It never uploads the application file. A missing provider record is not proof that a file is safe.
  • Imported IOC packs and YARA rules remain local. YARA scans at most ten explicit targets and rejects / and the entire home directory.
  • Report files, case records, settings, cache entries, signing secrets, and unfinished job journals remain on the Mac. Private local stores use owner-only permissions.
  • Common secret-bearing command arguments are redacted from collected process context. This reduces exposure but cannot guarantee that every sensitive value is recognized.
  • Live Triage retains a minimal PID, process state, runtime, and executable-path inventory so exact applications can be correlated with activity. It does not retain the complete command line for every process.
  • Full Disk Access is not requested automatically. If policy permits broader coverage, grant it to the application that launches Python, such as Terminal, then restart the launcher. Never bypass TCC protections for convenience.
  • Running read-only macOS commands may still create normal unified-log entries or update access metadata.

Browser artifacts and reports may contain sensitive history, downloads, usernames, paths, network endpoints, case notes, and host identifiers. Store, transfer, and dispose of them under the applicable evidence-handling policy.

The portable dashboard stores reports in macos-inspector-reports beside the launcher and keeps its private settings, cases, caches, imported rules, and signing material under that report directory in .macos-inspector-data. Source or CLI operations that use shared application state default to ~/Library/Application Support/macOS Inspector unless MACOS_INSPECTOR_DATA_DIR is set.

Reports and evidence handling

The dashboard supports HTML, JSON, Markdown, CSV, SARIF, PDF, evidence manifests, case-bundle ZIP files, and optional encrypted bundles. Every manifest records SHA-256 digests for normalized evidence and generated reports. The dashboard can verify those files and any attached signature.

Encrypted bundles require the optional cryptography dependency. The password is used only for the active export and is not saved in settings, scan history, or reports. A lost password cannot be recovered.

The built-in signing identity uses Ed25519 when the optional dependency is available and otherwise uses HMAC-SHA256. HMAC can detect later changes for a party that possesses the same secret, but it does not provide public-key identity assurance. For portable third-party verification, use an Ed25519, RSA, or EC private key and verify its public-key fingerprint through a separate trusted channel.

Limitations

  • macOS Inspector performs live inspection, not a bit-for-bit forensic acquisition.
  • Results reflect the current user's visibility and the permissions available at collection time.
  • Some TCC and browser databases may be unavailable while protected or locked.
  • Browser collection is bounded to supported profiles and recent rows; it is not complete browsing-history recovery.
  • Application signatures, notarization, and Gatekeeper results are trust signals, not a behavioral verdict.
  • IOC and YARA results are only as reliable as the imported rules and selected scan targets.
  • External intelligence can be delayed, incomplete, unavailable, or ambiguous for a particular build.
  • Volatile process and network state can change during collection.
  • Process termination can interrupt work or lose unsaved data. SIGKILL does not allow cleanup, and a zombie cannot receive another signal.
  • The portable release is not Apple-signed or notarized.
  • There is no remote agent, continuous monitoring service, automatic remediation, or cloud console. Process response always requires a local analyst confirmation.
  • Legal admissibility and chain-of-custody requirements depend on the analyst's process and jurisdiction.

Development

git clone https://github.com/bacescuandrei/macos-inspector.git
cd macos-inspector
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[signing]'
PYTHONPATH=src python -m unittest discover -s tests -v
node --check src/macos_inspector/webui/app.js
PYTHONPATH=src python -m scripts.build_release

CLI example:

macos-inspector --collectors application-trust,persistence,security \
  --formats html,json,markdown,csv,sarif,manifest \
  --output ./macos-inspector-reports

Findings do not change the process exit code. The CLI exits 0 when collection completes, 1 for an internal collection error, and 2 for invalid input.

Documentation

Contributing and license

Contributions are welcome when they preserve the read-only collector boundary, keep response actions narrowly constrained, and include tests for evaluation logic. Read CONTRIBUTING.md before opening a pull request.

macOS Inspector is released under the MIT License.

About

Local-first macOS security and DFIR inspection with guided audits, application trust, guarded process response, and static PDF triage.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages