SCOPE

Your authorized engagement, always in view.

SCOPE is an Omarchy Quattro bar plugin for ethical hackers, CTF players, security learners, researchers, and authorized penetration testers. It keeps the engagement boundary visible while you work: scope, current target, route, imported services, out-of-scope quarantine, and a small local timeline.

SCOPE is deliberately not a scanner or exploitation framework. It does not install pentest tools, run Nmap, sniff traffic, alter firewall rules, or monitor your terminal. You keep using the tools you already trust; SCOPE gives the engagement a safe, native home inside Omarchy.

What v0.1 does

• Start a LAB, CTF, CLIENT, or RESEARCH engagement only after a valid authorization scope is defined.
• Accept exact IPv4/IPv6 addresses, strict CIDRs, exact hostnames, explicit *.example.com wildcards, and ! exclusions.
• Reject ambiguous CIDRs that would silently widen scope (for example 10.10.11.42/24).
• Import explicitly supplied Nmap XML without invoking Nmap itself.
• Treat imported IP addresses as authoritative and hostnames/service names as untrusted metadata.
• Put in-scope hosts into the target list and out-of-scope hosts into a non-actionable Quarantine section.
• Surface Route Guard changes and quarantined evidence directly in the bar status; vertical bars collapse to a compact S marker.
• Ignore Nmap <script> output in v0.1.
• Scope-check every browser action immediately before producing the URL.
• Capture a read-only route baseline for an exact in-scope IP and warn when the kernel route later changes.
• Keep a bounded local timeline of SCOPE actions and user-entered notes.
• Store only sanitized engagement state under $XDG_STATE_HOME/omarchy-scope/ (or ~/.local/state/omarchy-scope/).

The core rule

SCOPE itself never knowingly helps an operator act outside the authorization boundary they defined.

SCOPE cannot and does not police unrelated terminals or programs. If you manually type a command in another terminal, SCOPE does not read it, log it, or intercept it. Scope Guard applies to actions generated by SCOPE itself and to evidence imported into SCOPE.

Security boundary

SCOPE v0.1 requires:

• no root
• no sudo / pkexec
• no listening sockets
• no firewall changes
• no system service
• no background daemon
• no packet capture
• no automatic network scan
• no pentest-tool installation
• no credentials or cloud account
• no AI service

The Python helper is short-lived. QML starts it for a single bounded operation, it returns one JSON result, then it exits. Route Guard only asks the local kernel which interface would carry traffic to an in-scope literal IP.

See SECURITY.md for the threat model and data-handling rules.

Install

SCOPE targets Omarchy 4 / Quattro and expects a repository with manifest.json at its root.

omarchy plugin add https://github.com/Drecullith/omarchy-scope.git

Review the checkout before enabling it. Omarchy plugins run as unsandboxed user-level code inside the long-running shell.

cd ~/.config/omarchy/plugins/io.github.drecullith.scope
less manifest.json
less Panel.qml
less bin/scope-helper

omarchy plugin enable io.github.drecullith.scope --section right

Runtime commands used by SCOPE:

• python3
• /usr/bin/ip (Route Guard; if unavailable, route state is shown as UNKNOWN)
• /usr/bin/xdg-open (only after a scope-checked HTTP/HTTPS action)
• /usr/bin/wl-copy (copy target/port convenience)

SCOPE never installs those commands or modifies system packages. You can inspect local readiness without changing anything:

~/.config/omarchy/plugins/io.github.drecullith.scope/bin/scope-helper doctor

First engagement

Open SCOPE from the bar and create an engagement:

Name: Boardlight
Type: LAB

10.10.11.42

For a network with an exclusion:

10.10.11.0/24
!10.10.11.13

For hostnames:

portal.example.com
*.api.example.com
!admin.api.example.com

Exclusions always win.

Important hostname rule

For an Nmap XML import, the literal IP address in the scan is the authorization object. A hostname advertised by the scanned host is only metadata and cannot make an otherwise out-of-scope IP become in scope. If the engagement is IP-based, put the authorized IP/CIDR in SCOPE.

Import Nmap evidence

Run your scan yourself with the options appropriate to your authorized environment, including Nmap XML output. Then drag the resulting XML file onto SCOPE or enter its local path.

SCOPE does not provide a scan command because scanning belongs to the operator and their authorization, not to the HUD.

A mixed import might show:

39 in scope · 1 quarantined

The quarantined target remains visible as evidence, but SCOPE exposes no action buttons for it.

Route Guard

When an engagement starts with an exact in-scope IP, SCOPE asks the local routing table how that IP would currently be reached and stores a small baseline such as:

10.10.11.42 → tun0

If the route later becomes:

10.10.11.42 → wlan0  ⚠ CHANGED

SCOPE warns. It does not reconnect a VPN, rewrite routes, or change networking. TRUST CURRENT is an explicit user action that replaces the saved local baseline.

Local state

State lives at:

${XDG_STATE_HOME:-$HOME/.local/state}/omarchy-scope/state.json

The directory is kept at mode 0700; the state and lock files are 0600. Writes are atomic. SCOPE refuses symlinked state/import files and caps state/import sizes.

Ending an engagement marks it inactive but keeps the last sanitized engagement state for inspection. Starting the next engagement replaces it in v0.1.

Remove

Disable and remove the plugin through Omarchy:

omarchy plugin disable io.github.drecullith.scope
omarchy plugin remove io.github.drecullith.scope

The plugin has no daemon or system service to clean up. Omarchy removes the git checkout. If you also want to erase the local SCOPE state afterward:

rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/omarchy-scope"

That last command is optional and irreversible.

Test

The helper and safety contract use only the Python standard library:

python3 -m unittest discover -s tests -v

The current 27 automated tests cover:

• exact IP/CIDR/hostname/wildcard/exclusion semantics
• exclusions winning over positive scope
• refusal to silently widen malformed CIDRs
• mixed Nmap imports and quarantine
• hostname metadata not authorizing an IP
• DTD/entity rejection
• scope-checked URL generation
• IPv6 URL brackets
• Route Guard change detection
• bounded timeline/state permissions
• source-level guardrails against scanner/privilege/package/service commands

See DEVELOPMENT.md for the real-Omarchy acceptance checklist.

Non-goals

SCOPE v0.1 is not:

• a vulnerability database
• a pentest report generator
• a credential vault
• a CVSS calculator
• an Nmap frontend
• a Metasploit frontend
• an IDS/IPS
• a Kali/BlackArch installer
• an autonomous security agent
• a collaboration server

Those are separate products and, in many cases, already have excellent tools. SCOPE is the active engagement HUD.

Status

0.1.0 is the first build candidate. The Python core and static QML/security contracts are automated-test covered; QML rendering still needs validation on a real current Omarchy Quattro machine before marketplace submission or a stable release.

License

MIT. See LICENSE.