Overview · Workflows · Providers · Architecture · Quick start · Build · Safety · Roadmap · Contributing

Overview

MACSPLOIT is a native macOS security workbench that turns separate reconnaissance tools into one persistent, scope-aware asset and evidence system. Discover subdomains, resolve addresses, identify services, probe websites, crawl URLs, and inspect HTTP security metadata. Inspect the relationships and the provider output behind each observation in the same workspace.

Provider output is not the product. A directory of Subfinder results, Nmap XML, HTTPX JSON, screenshots, and notes still leaves the analyst to reconstruct what belongs together. MACSPLOIT gives structured discoveries a shared model:

Specialist providers → Normalized assets → Relationships + observations
                                                       ↓
                                          Evidence + provenance
                                                       ↓
                                           Persistent workspace

The app runs locally, with no telemetry or hosted assessment backend. Real providers make network requests when you launch their workflows; Synthetic Recon stays offline.

Workflows

Five recon/analysis modes are available today. Each uses the same core orchestration, evidence, and persistence system. Workspace scope can be edited after creation, and the Rust core remains authoritative for every dispatch decision.

DNS Recon

For a real authorized domain or hostname, DNS Recon works out of the box with no external scanner installation.

flowchart LR
    D["Domain / Hostname"] -->|Native DNS| I[IPAddress]

The built-in resolver performs bounded A/AAAA resolution using the Mac's system resolver configuration, stores raw evidence, and creates scoped resolves_to relationships. This is the simplest live workflow to verify after installing MACSPLOIT.

Domain Recon

Start with an authorized domain. The chain discovers subdomains, resolves their addresses, scans in-scope IPs, and probes discovered HTTP services.

flowchart LR
    D[Domain] -->|Subfinder| S[Subdomain]
    S -->|Native DNS| I[IPAddress]
    I -->|Nmap| P[Port / Service]
    P -->|HTTPX| W[Website / Technology]

Subfinder, Nmap, and ProjectDiscovery HTTPX must be installed. DNS is built in. Nmap uses an unprivileged TCP-connect profile with service detection and the top 100 ports; no NSE scripts or root access. A hostname being in scope does not authorize scanning every IP it resolves to.

Web Recon

Select an in-scope HTTP(S) URL and explicitly launch a separate crawl. Domain Recon does not automatically launch Katana.

flowchart LR
    U["Selected HTTP(S) URL"] -->|Katana| V[Same-host URL assets]

Katana runs in standard, non-headless mode: depth 2, a 20-second crawl budget, a 5-second request timeout, and bounded response/output sizes. Automatic form filling, authentication flows, and JavaScript crawling are not enabled. The parser accepts valid same-host URLs and drops duplicates and external-host results.

Web Analysis

Select an explicitly in-scope HTTP(S) URL and run the built-in Native HTTP Analysis provider. It does not require Katana or another external HTTP-analysis executable.

flowchart LR
    U["Selected HTTP(S) URL"] -->|Native HTTP Analysis| H["Headers · cookie flags · CORS · redirects · robots.txt"]

The provider is ACTIVE_LOW_IMPACT and deliberately bounded. It accepts only HTTP/HTTPS targets, rejects credential-bearing URLs, keeps TLS validation enabled, caps response bodies at 256 KiB, follows redirects itself, and scope-checks every redirect hop before continuing. Cookie security attributes are retained; cookie values are not persisted. The result enriches the Website asset through observations and hashed evidence rather than inventing asset types for individual headers or cookies.

Synthetic Recon

Exercise the complete orchestration path using invented subdomains, documentation IP addresses, ports, and services. No scanner installation, DNS, or network requests are needed. Try the offline walkthrough below.

All five modes feed the asset graph, evidence, observations, and durable events, persisted in the local workspace and presented in SwiftUI. See Recon Chains for stage behavior and failure handling.

Assets with a history

An asset has a normalized identity. A relationship describes how it connects to another asset. An observation records what a provider reported, retaining its run and evidence reference. Repeated discoveries can reuse the asset while adding observations.

flowchart TD
    A[Asset] --> R[Relationship to another asset]
    A --> O[Observation]
    O --> P[Provider run and version]
    O --> E[Evidence reference]
    E --> H[Raw output and SHA-256]

Current workflows produce Subdomain, IPAddress, Port, Service, Website, Technology, and URL assets; domain and URL targets seed their chains. Hostname is also supported by the model. Endpoint and Certificate are model types, not a claim that endpoint analysis or certificate collection is implemented. The asset graph here means persisted data and relationships, not a shipped interactive graph canvas.

How a discovery flows

Illustrative values only; these are not live results or targets to scan:

example.test
  └─ Subfinder → api.example.test
       └─ Native DNS → 192.0.2.42
            ├─ Nmap → 443/tcp → https service
            └─ HTTPX → https://192.0.2.42:443 → technology observations

Explicitly add/select https://192.0.2.42:443 as an in-scope URL target:
  ├─ Web Recon / Katana → https://192.0.2.42:443/swagger.json
  └─ Web Analysis / Native HTTP → headers · cookie flags · CORS · redirects · robots.txt

HTTPX currently builds probe URLs from IP-based service identities. A path such as /swagger.json is only discovered if the crawl actually returns it. Domain relationships and each run's evidence remain in the workspace; starting Web Recon or Web Analysis is an analyst action, not an automatic cross-chain handoff.

Providers

The app surfaces provider availability, version, and risk. Stages select capabilities through an internal provider contract; SwiftUI never parses scanner output. Native HTTP Analysis is built in and runs independently of Katana. Provider details · Installation

Evidence and provenance

Keep the original result, not just the parser's interpretation.

Provider execution → Captured output → Evidence + SHA-256 → Parser
                                                               ↓
                                                    Normalized discoveries
                                                               ↓
                                              Observations → evidence reference

The core writes the returned execution envelope before parsing: provider identity and detected version, command, timings, exit status, and captured stdout/stderr. Evidence stays available when a returned execution reports failure or its parser fails. This preserves the inputs needed to examine or reproduce an interpretation; it does not promise a changing target will return the same result twice.

Evidence is stored in the workspace and SHA-256 checked when opened. Asset observations link back to that evidence and provider run, making attribution inspectable rather than implicit. Evidence files are local and permission-restricted, not encrypted; broader redaction and retention controls remain future work.

Architecture

flowchart TD
    UI["Native SwiftUI app / MACSPLOITKit<br/>Workspaces · Recon · Assets · Evidence · Activity"]
    CORE["Rust core / macsploit-core<br/>Scope · Assets · Chains · Providers · Evidence · Events"]
    UI <-->|"Versioned line-delimited JSON over stdin/stdout"| CORE
    CORE --> DB[(Per-workspace SQLite)]
    CORE --> FILES[Local evidence files]
    CORE --> PROVIDERS[Provider registry]
    PROVIDERS --> N[Built-in native providers<br/>DNS · HTTP Analysis]
    PROVIDERS --> X[Supervised external tools]
    PROVIDERS --> S[Offline synthetic provider]

The app owns a bundled Rust helper communicating over anonymous pipes; there is no network listener or background service that survives app quit. External processes use executable paths and argument arrays, bounded output, deadlines, and process-group cancellation.

Architecture · Internal protocol · Provider development

Safety

Discovery does not equal authorization. Scope is part of dispatch, not just a label on a result.

Discovery → Scope check → Provider risk policy → Allowed or denied dispatch

Exact host rules, wildcard label boundaries, and IPv4/IPv6 CIDRs determine scope. Out-of-scope assets are not silently fed into active providers. In particular, DNS results are checked independently before Nmap runs, even when the parent domain is authorized.

PASSIVE and ACTIVE_LOW_IMPACT providers run on in-scope targets. Launching Domain Recon explicitly authorizes its ACTIVE stage, still subject to per-asset scope checks. VALIDATION and LAB_ONLY are defined risk classes but rejected by current reconnaissance execution.

Use MACSPLOIT only on systems you own or are explicitly authorized to assess. The development app runs as your user, is unsandboxed and ad-hoc signed, and is not notarized. Security model · Threat model

What MACSPLOIT is not

MACSPLOIT is not an automatic exploitation framework, a replacement for every specialist tool, or a cloud service that uploads your assessments. Its role goes beyond launching shell commands: it organizes and correlates specialist tools in a local workbench.

Quick start

Run a real built-in workflow

1. Create or select a workspace.
2. Use Edit Scope and add only the domain/host/IP ranges you own or are authorized to assess.
3. Add the domain as a target.
4. Open Recon → DNS Recon and run it. No external CLI is required.
5. For Web Analysis, add a full HTTP(S) URL target (the UI can create an HTTPS URL target from a selected domain) and run the built-in analyzer.

Full Domain Recon additionally requires Subfinder, Nmap, and ProjectDiscovery HTTPX. Web Recon requires Katana. MACSPLOIT shows the missing tool and installation command instead of leaving the workflow unexplained.

Try MACSPLOIT without touching the network

Build and launch the app, then use Synthetic Recon. No external providers are required for this walkthrough.

Workspace   Test Assessment
Target      example.test
Scope       example.test
            *.example.test
            192.0.2.0/24

1. Create Test Assessment, keeping the suggested scope entries above, one per line.
2. Add example.test in the target bar; it should classify as Domain.
3. Open Recon, select Synthetic Recon and the target, then click Run.
4. Inspect Assets and their relationships/observations. Open linked Evidence to read verified JSON, and Activity to see persisted events. Recon retains stage status and run history.
5. Quit and reopen the app. The workspace and results should remain; repeat the run to add observations without duplicating normalized assets.

The first complete synthetic run produces 11 assets, 10 relationships, and 3 evidence records. Automated bridge tests cover core shutdown/restart persistence. The full on-screen quit/reopen acceptance walkthrough is still pending; see the verification record.

Build

Required development tools

Apple Silicon is the primary verified target. Intel builds and older supported macOS versions need separate verification. Initial dependency downloads need network access; automated provider tests use offline fixtures.

git clone https://github.com/doctordoomies/MACSPLOIT.git
cd MACSPLOIT

./scripts/setup-hooks.sh
./scripts/test.sh
./scripts/build-macos.sh
open build/MACSPLOIT.app

For later development launches, ./scripts/run.sh builds and opens the app. The build script bundles the Rust helper and ad-hoc signs build/MACSPLOIT.app. See development setup for toolchain details.

Workspace databases and evidence default to ~/Library/Application Support/MACSPLOIT/, outside the checkout. Build artifacts stay in ignored directories. No external scanner is required to build, launch, or run Synthetic Recon.

External providers

Install only the tools needed for the workflows you intend to run. MACSPLOIT detects providers but does not silently install them. Synthetic Recon, DNS Recon, and Native HTTP Analysis require nothing extra. The Recon screen shows missing external providers, their Homebrew command, and a provider refresh control.

HTTPX here is ProjectDiscovery's CLI, not the Python HTTP client. Formula availability and OS support follow Homebrew's current support policy. For executable discovery and explicit path overrides, see providers.

Roadmap

Build a useful baseline across workbench categories, then deepen provider coverage. Implemented, planned, and future are distinct: the feature matrix is authoritative.

The next documented breadth step is Phase 2C — explicit, bounded Content Discovery, followed by historical URL intelligence and JavaScript analysis. The broader sequence then continues through vulnerability assessment → OSINT → reporting → provider SDK. These are development directions, not release dates. See the full roadmap and changelog.

Contributing

Help improve a provider or parser, refine normalized asset modeling, polish SwiftUI, add offline fixtures, clarify documentation, or review a security boundary. Start with the contributing guide, provider development guide, architecture, and security model.

Automated security-provider tests must use fixtures, synthetic data, or fake executables. Keep real assessment data and secrets out of code, tests, issues, and pull requests.

Security reporting

For a vulnerability in MACSPLOIT, use GitHub private vulnerability reporting and follow SECURITY.md. Do not open a public issue for an undisclosed vulnerability.

Findings produced while assessing another system belong with that system's authorized reporting process, not the MACSPLOIT issue tracker.

License

Open source under the Apache License 2.0.

---

MACSPLOIT · Separate tools. Connected evidence. One workspace.