Samaritan · software you can take home
RedFlag
Know what your machines are running, know where that software came from, and hold one accountable mechanism for changing it.
No pro tier. No cloud edition.
RedFlag does not put process inspection, update approval, or fleet management behind a subscription. One machine gets the same system as a hundred.
RedFlag is my resume piece. It will never be monetized: no pro tier, no cloud edition, no per-agent pricing. The update manager is part of your attack surface. Everyone deserves one that treats it that way, not just organizations with an RMM budget.
Casey Tunturi, AUTHOR.md
One machine is a legitimate deployment. Install the server, register the host it runs on, and you have the whole console for that one box — updates, containers, dependency closure, upstream drift, history. Add a second machine and the same console becomes fleet management. Nothing unlocks, because nothing was locked.
Four questions, one system
Most tools answer one of these and hand you off. RedFlag keeps the same machine identity through all four.
- 01 Observe
What is this machine doing?
Agents scan their own package managers, the Docker socket, storage, and — on demand — /proc: running processes with their open sockets and namespaces, correlated by inode. The machine reports itself; nothing is inferred from a central inventory.
- 02 Understand
Where did that software come from?
Installed versions are compared against canonical upstream releases — GitHub, Forgejo/Gitea/Codeberg, GitLab, Bitbucket, Repology, endoflife.date — so a package can be behind, or on a branch approaching end of life, without any local package manager knowing it. Advisories come from OSV.dev at discovery time.
- 03 Authorize
What is allowed to change it?
Nothing installs without a human approving it. On APT and DNF, approval mints a short-lived Ed25519 capability that binds one host, one operation, and the artifact hashes that resolved. A privileged Rust helper validates that capability before it executes a fixed argv plan with no shell and a cleared environment.
- 04 Remember
What actually happened?
Every command, approval, override, and failure is written to history with its reason attached. A failed install keeps its live output. An overridden vulnerability keeps the documented reason it was overridden for.
What it looks like
Screens from the maintainer's own stack, unretouched. Where a view is empty, it is empty because that is how the software arrives.
What it manages
Agents run at the OS level and query the Docker socket directly. There is no separate container agent.
Approval workflow
Updates queue for human review. Maintenance windows gate the day and hour an install may proceed.
Dependency dry-run
The closure is resolved and shown before approval, not discovered during the install.
Upstream tracking
Polls canonical release sources and end-of-life data, and flags drift the local package manager cannot see.
Process explorer
On-demand /proc scanning: processes with their open sockets and namespaces, correlated by inode.
Self-update through the same gate
Agent, helper, and desktop binaries update through the identical signed, hash-pinned capability path as packages. Zero agent sudo.
Full audit trail
Every operation logged with context and sanitised against log injection. Failed states can be reopened, resolved, and transitioned out of.
Device classification
Layered detection of laptop, VM, and container hosts, with ARM support alongside amd64.
Bring your own key
Setup accepts an operator-supplied Ed25519 signing keypair. Key rotation runs with multiple active keys and no coordinated agent restart.
The update manager is attack surface
XZ Utils came through a build pipeline. SolarWinds came through an update. Software that runs as root on every box you own gets treated accordingly.
Signed commands, no off switch
Every command the server issues is Ed25519-signed with a nonce and a ten-minute validity window. Agents verify the signature, check the timestamp, and reject anything replayed. Signing-required and forward-only are doctrine, not configuration — there is no "skip verification" path to misconfigure.
Machine-bound identity
Agents register with a one-time token plus a hardware fingerprint. Check-ins and token renewals that do not match the registered host are refused with a logged security event. A stolen config.json does not work on a different machine.
Refresh tokens that burn loudly
Each renewal mints a new refresh token and consumes the old one. Replaying a consumed token whose successor was also consumed means theft, and the whole token family is revoked. A crash before save is covered by an accept-previous-once grace, so the loud path is reserved for the real one.
A privileged helper that does not trust the server
The Rust helper independently validates capability version, validity window, host binding, pinned-key signature, and replay state before it acts. It builds a fixed package-manager argv, invokes no shell, and clears the inherited environment. Where a closure entry names a local file, the helper rehashes it and denies a mismatch.
Pull-only agents
Agents check in roughly every five minutes and execute what the server has already approved. The server never opens a connection to a managed host, so managed machines need no inbound ports.
A vulnerability is a full stop
Resolved closure entries are checked against OSV.dev before a capability is minted. A known vulnerability among the checked entries stops the install: an operator overrides it with a documented reason, or the token is never minted. The override waives that judgment only — it cannot bypass signature or hash verification.
The operator-facing trust model is SECURITY.md. The reasoning behind the design — and the pitfalls believed to still be out there — is published as the RedFlag Architecture Framework, in the RAF directory beside the code.
Where it actually stands
Compiles and runs on the maintainer's stack. Not battle-tested, and not deployed outside
the development environment. The supply-chain gate has completed one end-to-end run —
2026-06-05, hyprutils through capability minting, helper verification, and
install on a live Fedora agent. Treat everything as implemented and locally exercised,
not production-proven.
Named limits
These are the gaps the maintainer publishes against himself. A guide that names its limits is worth more than one that does not.
- Transitive hash resolution is incomplete. The top-level artifact hash is mandatory; a dependency whose hash does not resolve is logged and omitted rather than blocking the report.
- A normal registry entry with no local file is bound into the signed capability but is not rehashed helper-side before APT or DNF fetches it.
- The helper runs in a transient systemd unit that is short-lived but not network-isolated. Network isolation is intended and unfinished.
- The capability gate covers DNF and APT. Docker, Winget, and Windows Update still run through the signed-command path without the helper.
- Certificate pinning and enforced TLS verification are not implemented yet.
- No AUR, Snap, Flatpak, or Homebrew support. macOS agent binaries are unsigned.
- The mobile dashboard is usable, not optimised.
Run it yourself
The server is a Go binary with an embedded dashboard and PostgreSQL beside it. Build from source; there is nothing to sign up for.
Server
git clone https://forge.caseytunturi.com/Fimeg/RedFlag.git
cd RedFlag
cp config/.env.bootstrap.example config/.env
docker-compose build && docker-compose up -dOpen http://localhost:31336, complete the setup wizard, then docker-compose down && docker-compose up -d once to pick up the generated
configuration. Agents talk to the server on 31337.
Agent
Take a registration token from Settings → Token Management, then run the installer on the machine you want managed:
# Linux
curl -sfL -H "X-Registration-Token: your-token" \
"https://your-server/api/v1/install/linux" | sudo bash# Windows
iwr -Headers @{"X-Registration-Token"="your-token"} `
"https://your-server/api/v1/install/windows" | iexThe installer is idempotent — re-running it will not create a duplicate agent. Agents install as native services: systemd on Linux, the service manager on Windows.
Binaries
There is no published binary release yet — the release shelf is empty, and saying otherwise would be the kind of claim this page exists to avoid. The pipeline that will fill it is already built: tagged releases publish server, agent, helper, and desktop binaries for Linux and Windows, plus a Windows installer, each with its SHA-256 recorded in a component manifest and re-verified byte-for-byte through an anonymous download before the job goes green. When the first tag ships, it lands there and this page will say so.
Provenance
publicTHIRD_PARTY_LICENSES.mdSamaritan publishes this because it is meant to leave: install it, fork it, run it against your own fleet, and return a correction when you find one. Read the licence before copying code — Samaritan does not claim one licence covers every linked work.