Guardian is a client-admission and Paper server-protection project for Minecraft servers. Cerberus is the cooperative Fabric client used when a Guardian Admission policy requires an approved Fabric environment.
Guardian has two independent domains:
- Admission classifies connections, evaluates shared client/mod policy, supports Geyser/Floodgate Bedrock classification, and can use Guardian-Velocity as the network authority.
- Protection is Paper-local command execution, visibility, namespace, bypass, and staff-notification policy.
For a Velocity network, Guardian-Velocity can act as the Admission authority with Guardian-Paper on each backend. Guardian-Paper also works as a standalone Admission authority, and Guardian Protection never requires Velocity or Cerberus.
Guardian/Cerberus is a client-policy compliance system, not hostile-client remote attestation. See
docs/SECURITY_THREAT_MODEL.mdfor known limitations.
- Java 25
- Paper 26.2 for Guardian-Paper
- Velocity 4.x for Guardian-Velocity deployments
- Fabric Loader 0.19.5+ and Fabric API for Cerberus on Minecraft 26.2
- Optional integrations: LuckPerms, Geyser, and Floodgate
Choose the deployment guide that matches your network:
For normal administration, also see Admission policy, Protection, and upgrades. The detailed security/threat model and key-management guide are references rather than prerequisites for a basic install.
Packaged defaults enable both Admission and Protection. On a Velocity deployment, set the Paper backends to admission.authority: velocity and provision the generated proxy-assertion.key as documented in the network install guide.
Paper owns /guardian; Velocity owns /guardianv. The roots intentionally do not proxy to each other.
/guardian status
/guardian validate
/guardian reload
/guardian inspect <player>
/guardian artifacts scan
/guardianv status
/guardianv validate
/guardianv reload
/guardianv inspect <player>
/guardianv artifacts scan
On a Velocity-authoritative network, /guardianv inspect is the authoritative Admission view. Backend /guardian inspect remains assertion-only and does not receive the full Fabric manifest. Active inspection data is memory-only and disappears when the exact connection ends.
Paper administration:
guardian.command.status
guardian.command.validate
guardian.command.reload
guardian.command.inspect
guardian.command.artifacts.scan
Velocity administration:
guardian.velocity.command.status
guardian.velocity.command.validate
guardian.velocity.command.reload
guardian.velocity.command.inspect
guardian.velocity.command.artifacts.scan
Admission policy/profile permissions:
guardian.admission.profile.<profile-id>
guardian.admission.client.bypass
guardian.admission.client.bypass.<client-key>
guardian.admission.mod.bypass
guardian.admission.mod.bypass.<mod-id>
Assign Admission profile/bypass permissions on the authority that evaluates Admission: Paper-side LuckPerms for standalone Paper, or proxy-side LuckPerms when Guardian-Velocity is authoritative.
Protection bypass/notification permissions:
guardian.protection.bypass
guardian.protection.command.bypass
guardian.protection.namespace.bypass
guardian.protection.visibility.bypass
guardian.protection.visibility.bypass.<normalized-command-key>
guardian.protection.notify
guardian.protection.visibility.bypass is itself the aggregate visibility bypass; no trailing .* is required. The per-command form is used only when protection.visibility.per-command-bypass is enabled. See docs/GUARDIAN_ADMISSION.md and docs/GUARDIAN_PROTECTION.md for exact semantics.
Use the repository Gradle wrapper with Java 25. The wrapper is pinned to Gradle 9.7.1.
Windows:
.\gradlew.bat clean test :guardian-paper:jar :guardian-velocity:jar :cerberus-fabric:buildLinux/macOS:
./gradlew clean test :guardian-paper:jar :guardian-velocity:jar :cerberus-fabric:buildThe source default is 1.0.1. An explicit SemVer build version can still be supplied with -PguardianVersion=<version>; the source version does not by itself publish a GitHub release.
Official Cerberus releases are signed with an offline Ed25519 release identity. The private signing key must never be stored in GitHub Actions, the repository, a Minecraft server, or Cerberus itself.
The supported release flow is:
- run the manual Release Candidate GitHub Actions workflow for the exact SemVer version being released;
- download the resulting
guardian-<version>-release-inputartifact from the GitHub web UI; - on the offline/release machine, finalize the exact CI-built artifacts with
tools/release-manager.ps1; - upload the contents of
release-final/to a draft GitHub Release; and - publish the draft only after final verification/smoke testing.
Example local finalization:
.\tools\release-manager.ps1 `
-Action finalize-release `
-Version 1.0.1 `
-InputDirectory .\release-input `
-OutputDirectory .\release-final `
-ReleasePrivateKey D:\GuardianKeys\cerberus-release\cerberus-release-signing.key `
-ReleasePublicKey D:\GuardianKeys\cerberus-release\cerberus-release-signing.pub `
-GuardianServerPublicKeys D:\GuardianKeys\server-auth-trust.txtThe final directory contains the CI-built Paper/Velocity JARs, the signed Cerberus JAR, the public Cerberus release-verification key, license/notices, release provenance, and final SHA-256 checksums. The unsigned Cerberus input is deliberately not a public release asset. When signed-release trust is enabled, copy the base64 contents of cerberus-release-signing.pub into policy.yml; the SHA-256 values are release/provenance checks and are not the policy trust value. See docs/RELEASE_PROCESS.md for the full operator procedure.
- Standalone install
- Velocity network install
- Production deployment / rollback runbook
- Admission policy
- Protection
- Geyser/Floodgate
- LuckPerms profiles
- Configuration upgrades
- Key management and rotation
- Release process
- Security/threat model
- Development
Historical phase documents remain in docs/ for implementation provenance; administrators do not need them for normal deployment.
Please use the repository issue tracker for ordinary bugs and support questions. Do not publish sensitive vulnerability details in a public issue; follow SECURITY.md instead.
Guardian/Cerberus is licensed under GPL-3.0-only; see LICENSE. Bundled third-party notices are in THIRD_PARTY_NOTICES.md.
Guardian began as a hard fork and substantial rewrite of BrandBlocker by Menacho. Guardian Protection also incorporates selected behavior/source lineage from BadWolfMC's GPLv3 fork of eZProtector by DoNotSpamPls. The precise provenance boundary is recorded in docs/PROVENANCE.md.