Security model
Conn3x changes servers as root, so it’s worth knowing exactly what it trusts and what it checks. This page is the short version. Found a gap? Please report it privately, as SECURITY.md describes.
What you’re trusting
Section titled “What you’re trusting”- The machine you run
conn3xon. It holds your SSH keys, your cloud credentials and the state, and it decides what every host does. Anyone who controls it controls your hosts. Treat it like a bastion: patched, few users, and its disk encrypted. - The configuration you apply. A circuit runs what it says, as the user it says. Review changes to circuits the way you review code, and pin shared circuits to a release with
?ref=. - The providers and circuits you use. Conn3x runs OpenTofu providers and shared circuits like any OpenTofu configuration does. Use ones you trust, and keep
.terraform.lock.hclin version control so a provider can’t change under you.
Connecting to hosts
Section titled “Connecting to hosts”- SSH only, and host keys are always checked. Every host’s key is verified against your known_hosts file or a pinned
host_key, and there’s no setting to turn that off. A key that changed stops the plan. See Troubleshooting. - Every hop is checked too. A jump host has its key verified, and so does the host behind it. With
proxy_command, the SSH session still runs end to end, so the host’s own key is checked as usual. - Old algorithms are opt-in, per host. The SHA-1 SSH algorithms classic Cisco IOS needs are used only by a host that sets
legacy_algorithms = true, never by default and never by a jump host. A pinned RSAhost_keymust sign with SHA-2. - Nothing is installed on the host. Conn3x runs plain shell commands over SSH. The Conn3x agent, which runs commands through one long-lived process instead, is experimental and off unless you turn it on.
On the host
Section titled “On the host”- Root through sudo, only when you ask. With
become = true, commands run through sudo; without it, as the user you log in as. A sudo password comes frombecome_password_fileat run time and never goes into configuration or state. - Root doesn’t write through someone else’s path. Before a file step writes as root, it checks who can change each directory on the way, and acts as that user, or stops, rather than follow a link another user planted. See Paths as root.
- Values are quoted. Steps quote each value from your configuration that they put into a shell command.
- Network devices get a revert timer. A change to a switch or router is committed with a timer and confirmed over a new login, so a change that cuts Conn3x off undoes itself. See Network devices.
Secrets and state
Section titled “Secrets and state”- State holds what Conn3x read. Like any OpenTofu state, it records your resources and what each step read from its host, which can include file contents and command output. Turn on state encryption, and store state where only the people who apply can read it; Conn3x warns at every plan while it’s off.
- Write-only arguments keep secrets out of state. A password written with
content_wo, or another*_woargument, reaches the host but not the plan or the state, which keeps an HMAC to notice changes. See Secrets. - Secrets can come from outside. SOPS files through
ephemeral "conn3x_secrets", and private keys from ephemeral values, never touch state either.
Releases
Section titled “Releases”Every release is built by a GitHub Actions workflow from main, and:
- its
checksums.txtis signed with Sigstore (keyless), so you can check it came from that workflow; - each archive and package has an SBOM;
- builds carry provenance attestations;
- the container image is signed the same way;
- the apt and dnf repositories sign both packages and metadata.
Install shows how to verify each.
Reporting a problem
Section titled “Reporting a problem”Report a vulnerability privately through GitHub’s private vulnerability reporting or security@conn3x.org. Fixed issues are published as security advisories.