"How we built an open-source macOS reconnaissance framework that turns Wi-Fi artifacts, Bluetooth pairings, and USB history into a narrative of cross-device identity, physical movement, and trust boundaries.”
tags: security, redteam, macos, forensics, golang, opensource
"Just as the weevil drills into fruit, lays eggs, and severs the stem to cover its tracks..."
That is where the name comes from. Not a typo. Not a meme. A metaphor for what effective macOS reconnaissance actually looks like: quiet, persistent, and structurally invasive.
The Gap Nobody Talks About
Red team tooling for Windows and Linux is a mature industry. Cobalt Strike, BloodHound, SharpHound, Seatbelt — we have entire arsenals for credential harvesting, lateral movement, and domain enumeration. But when you land a shell on a MacBook Pro inside a target organization, what do you reach for?
system_profiler? networksetup? A handful of one-off bash snippets copied from a 2019 blog post?
macOS is not just another Unix. It is an ecosystem — iCloud, Continuity, AirDrop, Handoff, Bluetooth LE, Wi-Fi Cloud Sync, Secure Enclave, Data Vault. Each of these features leaves forensic artifacts that, when correlated, tell a story far richer than a simple process list or browser history. But until now, there has been no cohesive, extensible framework to collect and correlate these artifacts in a red team context.
That is the gap RinHit was built to fill.
What RinHit Actually Does
RinHit is a macOS ecosystem reconnaissance framework written in Go. It does not exploit vulnerabilities. It does not establish persistence. It does not phone home. It reads, correlates, and narrates.
Artifact Collection
At its core, RinHit implements a plugin-style collector architecture. Today, it ships with three primary collectors:
-
Wi-Fi Networks — Parses
com.apple.wifi.known-networks.pliston older systems, and falls back tonetworksetupon macOS 15+ where the plist is protected by Apple's Data Vault. This gives you SSIDs, BSSIDs, last-joined timestamps, router IPs, and — since December 31, 2025 — geolocation hints embedded directly by Apple. -
Bluetooth Devices — Extracts paired, cached, and recently connected devices from
com.apple.Bluetooth.plist. That AirPods case tells you more about the victim's device ecosystem than you might think. -
USB Device History — Enumerates connected USB devices via
ioregandsystem_profiler. A YubiKey seen three hours ago is a strong indicator of MFA workflows and privilege boundaries.
The Correlation Engine
Collecting artifacts is trivial. Making them speak is the hard part.
RinHit's correlation engine performs cross-artifact analysis to identify patterns that no single data source reveals:
- Cross-Device Identity — An iPhone hotspot in the Wi-Fi list + paired AirPods in Bluetooth = a high-confidence mapping of the victim's mobile ecosystem.
- Travel Patterns — Hotel and guest Wi-Fi networks clustered temporally reveal business travel, off-site meetings, or personal trips that blur the physical-digital boundary.
- Home/Office Fingerprinting — ISP router detection (static IP ranges, router MAC prefixes) lets you infer network topology without ever sending a packet.
- Temporal Session Clustering — Grouping artifacts by time windows to reconstruct "what the user was doing on Tuesday afternoon."
Offline BSSID Geolocation
Here is something we learned the hard way: public BSSID lookup APIs are a trap.
When you query Google or Apple to resolve a router's location, you are not just getting coordinates. You are donating your IP address, your query pattern, and your operational timeline to a database that never forgets. For red team operators, this is an OPSEC failure that can link disparate engagements back to a single actor.
RinHit solves this with an offline SQLite cache. Import a Wigle.net CSV dump once, and all subsequent BSSID lookups happen locally. No network traffic. No fingerprinting. No trust in third-party infrastructure.
Living with Data Vault
macOS 15 introduced Data Vault protections for sensitive plists, including the Wi-Fi known networks file. Many recon tools simply fail here, or demand root and trigger EDR alerts with aggressive privilege escalation.
RinHit takes a different path. When the plist is inaccessible, it transparently falls back to networksetup — a native, signed, Apple-provided binary that is already on every Mac. This is living off the land applied to reconnaissance: using the operating system's own tooling to extract its own secrets, without importing foreign binaries or requesting suspicious entitlements.
Architecture: Built to Grow
RinHit is designed as a platform, not a script.
rinhit/
├── cmd/rinhit/main.go # CLI entrypoint
├── pkg/
│ ├── collector/ # Interface + registry
│ │ ├── wifi/
│ │ ├── bluetooth/
│ │ └── usb/
│ ├── model/ # Artifact & Report structs
│ ├── parser/plist/ # Plist parsing with SIP fallback
│ ├── reporter/json/ # Structured output
│ ├── correlator/ # Cross-artifact engine
│ └── geoloc/ # Offline SQLite cache
Adding a new collector means implementing a four-method interface:
type Collector interface {
Name() string
Description() string
Collect(ctx context.Context) ([]model.Artifact, error)
RequiresRoot() bool
}
The roadmap already includes TCC database analysis, quarantine extended attributes, Spotlight metadata, and Unified Logs timeline extraction. Each of these will be a new collector plugin, not a rewrite.
The Closed Door and the Open Window
RinHit, as published on GitHub, is the reconnaissance module only. It is read-only. It modifies nothing. It is safe to audit, safe to run in client environments, and safe to contribute to.
Internally, at our offensive AI laboratory, we pair this open-source reconnaissance engine with a closed-source Swift payload (rinhit-agent) that handles persistence, exfiltration, and active manipulation of ecosystem artifacts. That code is not here, and it will not be. The open-source project is the foundation. The closed-source layer is the roof. Both need strong walls.
Why We Are Sharing This
We believe that macOS red team reconnaissance deserves the same rigor and tooling maturity that Windows and Linux have enjoyed for years. We also believe that the best way to raise the bar is to invite others to build on a common foundation.
If you are:
- A macOS security researcher with knowledge of private frameworks or forensic artifacts
- A red team operator who has written one too many ad-hoc bash scripts for Mac engagements
- A blue team defender who wants to understand what reconnaissance looks like from the attacker's perspective
...we want to hear from you.
Getting Started
git clone https://gitlab.com/toxy4ny/rinhit.git
cd rinhit
go build -o rinhit ./cmd/rinhit
sudo ./rinhit scan --correlate -v
Import your Wigle dump for offline geolocation:
./rinhit geo import wigle-export.csv
./rinhit geo lookup AA:BB:CC:DD:EE:FF
What Comes Next
The immediate priorities are:
- TCC Database Collector — Enumerating application permissions to map the attack surface of installed software.
-
Quarantine Extended Attributes - Reconstructing download sources and phishing vectors from
com.apple.quarantinemetadata. - Unified Logs Subsystem Filtering - Targeted extraction of Wi-Fi, Bluetooth, and USB attach/detach events without drowning in noise.
- SARIF & Markdown Reporters - Machine-readable output for SOAR pipelines, and human-readable summaries for executive reporting.
If any of these resonate with your work, open an issue. Better yet, open a pull request.
Final Thought
The macOS ecosystem is not a black box. It is a fruit with a hard shell and a soft interior. RinHit is the drill. How deep you go - and what you plant when you get there — is up to you.
Repository: gitlab.com/toxy4ny/rinhit
License: MIT
Contributions: Welcome, audited, and appreciated.
Written by KL3FT3Z with architectural partnership from the offensive AI laboratory. Special thanks to the contributors who have already started poking at the collector interface.
