Skip to content

Security

Jump to bottom
Trevin edited this page Sep 28, 2026 · 5 revisions

Security

Security considerations for installing and running Aphotic, plus a deep dive on the exploit layer family — the one part of the project that intentionally installs offensive-security tooling.

Aphotic was previously known as Noctis-Hypr.

Installation Safety

  • Pre-install backups — every install.sh run snapshots your current configs first, to ~/.config-backup/, before anything is touched. --no-backup skips this (off by default; use with intent), and --keep-backups <N> controls how many timestamped backups are retained (default 5).
  • Dry-run — --dry-run prints the full resolved install plan (every package, every layer, every detected system fact) and exits. Nothing is installed, backed up, or written. It doesn't install, write, or switch the checkout to a release tag.
  • Reversible — ./uninstall.sh restores your most recent backup. Pass --purge-packages if you also want it to remove everything your profile installed, behind its own separate confirmation.
  • Protected files — ~/.config/hypr/custom.lua is never overwritten by the installer once it exists. Put your own Hyprland tweaks there and a re-run or aphotic update won't clobber them.
  • Config-only sync — install.sh --config-only backs up and copies Configs/ over ~/.config/ with no package installs, no system prep, and no wizard. It still refreshes the greeter's system-wide files, which uses sudo: on a terminal that can mean a password prompt; without one it skips that step with a warning.

Package Sources

  • Standard packages come from Arch's official repositories; AUR-sourced packages come through an AUR helper (yay or paru). If neither is installed, the installer builds yay from its AUR git repo.
  • wallust isn't packaged in any Arch repo, so the installer downloads the upstream static binary from its Codeberg releases and checks it against a pinned SHA-256 before installing it.
  • When a required official package is broken upstream, the installer can offer to install it from the Arch Linux Archive snapshot of the last day the nightly install canary passed. It reads that date from the project's canary-status branch on GitHub. Nothing happens without your yes.
  • The exploit layer family additionally sources from the BlackArch repository — see below.

Data Collection & Telemetry

Aphotic does not phone home. There's no analytics SDK and no crash reporter. The network requests it does make are the ones you'd expect from what you use: the weather card (Open-Meteo), Settings → About's update check (the GitHub releases API, only when you click it), aphotic packages check and its optional timer (your package mirrors and the AUR), theme and plugin index fetches, and any AI provider you configure. When an install fails, the installer offers a failure report you review first; it's only sent, as a GitHub issue, if you answer yes.

What's actually collected, and where it stays:

  • AI usage tracking (only if the ai layer is enabled) — a 15-minute local scan of Claude Code/Codex transcripts for aggregate token counts, never prompts or responses. Ollama isn't a harness and isn't part of this scan. Stays local; see Agentic Workflows.
  • Agent Graph, Agent Audit, and the Agent Notch Tile (opt-in ui-surface plugins, each needs the ai layer plus its own aphotic plugin install <name>) — visualize or inspect a harness session's tool calls from a shared local event history. See Agentic Workflows and Plugin System for exactly what is and isn't collected and how the opt-ins work.
  • Exploit-layer acknowledgment log (only if you select an exploit-* layer) — see below.
  • Game scores, settings, theme state — all local JSON under ~/.local/state/aphotic/.

No wallpaper, theme, config, or usage data is ever transmitted off the machine by anything in this repo.

The exploit Layer Family

Offensive-security/CTF tooling is split into focused sublayers instead of one flat exploit layer, so you only install — and only get prompted about — the tools you actually want. exploit itself still exists as a convenience meta-layer. This is for personal security research, CTFs, and authorized pentesting work — the same reasoning that put a hackthebox theme in this repo.

Sublayers

Layer Tools Needs BlackArch?
exploit-recon nmap, amass, subfinder, theHarvester, recon-ng yes
exploit-web Burp Suite (Community Edition), sqlmap, ffuf, gobuster, nikto, ZAP yes
exploit-network Wireshark, aircrack-ng suite, bettercap, tcpdump, OpenVPN yes
exploit-passwords John the Ripper, hashcat, Hydra yes
exploit-wordlists rockyou (opt-in only, see below) no
exploit-reversing Ghidra, radare2, Cutter, gdb + pwndbg, binwalk yes
exploit-forensics Autopsy, Sleuth Kit, Volatility 3 yes
exploit-reporting aphotic report CLI + pandoc no

exploit (the meta-layer) is a convenience bundle of exploit-recon + exploit-web + exploit-network — the three sublayers most people reach for first. It carries no packages of its own; enabling it just expands to those three at install time. Every other sublayer is opt-in only, individually. Select any combination with --with:

./install.sh --profile full --with exploit                        # the recon+web+network bundle
./install.sh --profile full --with exploit-reversing,exploit-forensics

exploit-wordlists is always separate

rockyou (~130MB decompressed, from the OWASP SecLists project) is never bundled into exploit-passwords or any other layer automatically. It's its own sublayer, prompted for on its own, with its size and origin disclosed in that prompt — so you never end up with it on disk just because you wanted John the Ripper.

exploit-reporting is first-class, not an afterthought

Every other sublayer produces findings; this is where they go. exploit-reporting installs pandoc and enables the aphotic report CLI:

aphotic report new <name>      # scaffolds ~/aphotic-engagements/<name>/report.md + evidence/
aphotic report list            # lists existing engagements
aphotic report render <name>   # renders report.md to PDF via pandoc

The report template has sections for scope/authorization, findings (severity, description, evidence, reproduction, remediation), a timeline, and an appendix.

Why BlackArch, and why most sublayers need it

BlackArch is this project's existing, already-in-production sourcing mechanism for offensive-security tooling, not a new decision made for this taxonomy. Most exploit-* sublayers pull at least one package from it; exploit-wordlists and exploit-reporting don't, and so never trigger it on their own.

BlackArch is not held to the same stability bar as Arch's own official repos:

  • It's large and fast-moving; packages occasionally ship broken between fixes.
  • Some BlackArch packages shadow/replace official ones — it rebuilds common tools under its own repo, and a later blanket sudo pacman -Syu can silently pull in one of those rebuilds instead of the official package you had before.

install.sh reflects that risk directly: enabling any sublayer that requires BlackArch prints a warning and requires an explicit confirmation before it touches /etc/pacman.conf, separate from the general "you're about to run this installer" confirmation everything else shares. Decline, and only the BlackArch-requiring sublayers are stripped from the install — exploit-wordlists/exploit-reporting still proceed if selected.

How it's enabled — mirrors what a careful sysadmin would do by hand rather than a blind curl-pipe-sudo:

  1. Skip entirely if /etc/pacman.conf already has a [blackarch] section.
  2. Download BlackArch's official strap.sh bootstrap script and its published SHA-1 checksum (https://blackarch.org/checksums/strap).
  3. Verify the checksum. If it doesn't match, stop and change nothing — the exploit-layer packages will just fail to resolve, same as any other unavailable package.
  4. Only then run strap.sh (which appends the [blackarch] section and imports/signs their key) and pacman -Sy to refresh package databases.

If a package breaks after enabling it, force-reinstall the official copy, explicitly naming the official repo so BlackArch's version doesn't win:

sudo pacman -S extra/<package>
# or core/<package> for base packages

Removing BlackArch entirely:

  1. Open /etc/pacman.conf and delete the [blackarch] section strap.sh appended (a [blackarch] header followed by a couple of Include=/Server= lines near the end of the file).
  2. Remove the keyring package and resync: 
    sudo pacman -R blackarch-keyring
sudo pacman -Syyuu
  3. Re-run aphotic doctor or pacman -Qm to confirm nothing installed from BlackArch is still on the system.

uninstall.sh does not do this automatically — editing another program's system-wide config file on an uninstall was judged the wrong kind of "automatic" for something this blunt an instrument. The manual steps above are quick and don't require guessing at what else might be in pacman.conf.

The authorized-use disclaimer

Selecting exploit or any exploit-* sublayer — in the guided setup, the --opt-in picker, or via --with — gates on a full-screen, un-skippable disclaimer before anything is installed. It requires typing "I understand" (not a bare Enter-to-dismiss).

The text is an original Aphotic-authored disclaimer, paraphrased from the substance of BlackArch's and Kali's own authorized-use/no-warranty framing — not copied from either. Use this tooling only against systems you own or are explicitly authorized to test.

Scripted / non-interactive installs

--with exploit... in a genuinely non-interactive session (no TTY on stdin, e.g. CI) fails loudly instead of silently skipping the gate:

[ERROR] - The exploit-* layer family requires accepting the authorized-use disclaimer.
[ERROR] - This is a non-interactive session (no TTY on stdin), so it can't be shown/typed here.
[ERROR] - Re-run with --accept-exploit-disclaimer to confirm you've read and agree to it

Pass --accept-exploit-disclaimer to acknowledge it non-interactively. A real terminal (TTY on stdin) always gets the full typed-confirmation prompt, even if you used --with instead of the wizard.

Acknowledgment logging

Accepting the disclaimer records that it was shown and accepted, plus a timestamp and method (interactive or non-interactive (--accept-exploit-disclaimer)), to ~/.local/state/aphotic/exploit-acknowledgment.json. It does not store the disclaimer text itself — it's a local record for your/the project's reference, not a claim that this logging is legally enforceable on its own.

Re-acknowledgment

The gate only triggers when an exploit-* layer is newly added compared to what's already recorded in aphotic.toml — an unchanged, idempotent re-run of install.sh never re-prompts. But if you remove all exploit-* layers and later re-add any of them, the gate re-triggers and asks again. That's deliberate: re-showing a cheap confirmation is worth it to avoid silently skipping it after a layer was gone for a while.

Reporting Security Issues

If you discover a security vulnerability:

  1. Don't publicly disclose details until it's patched.
  2. Report it privately to the maintainers, or via a GitHub Security Advisory on the repository, rather than a public issue.
  3. Include reproduction steps and affected versions.

See also

Clone this wiki locally