https://github.com/dknauss/sudo
Sudo for WordPress! đĨĒ Risky actions â activating plugins, deleting users, changing key settings â are gated by a required reauthentication step, regardless of user role. Time-bounded sessions, 2FA support, rate limiting, and configurable policies for REST, WP-CLI, Cron, WPGraphQL, & XML-RPC. No role escalation, no new permissions â just a gate. âŠī¸
https://github.com/dknauss/sudo
access-control principle-of-least-privilege sudo wordpress-admin-backend wordpress-admin-panel wordpress-administrators wordpress-auth wordpress-cron wordpress-multisite-compatible wordpress-plugins wordpress-rest-api wordpress-security wordpress-security-plugin wordpress-users wordpress-xmlrpc wp-cli wpgraphql zero-trust
Last synced: 1 day ago
JSON representation
Sudo for WordPress! đĨĒ Risky actions â activating plugins, deleting users, changing key settings â are gated by a required reauthentication step, regardless of user role. Time-bounded sessions, 2FA support, rate limiting, and configurable policies for REST, WP-CLI, Cron, WPGraphQL, & XML-RPC. No role escalation, no new permissions â just a gate. âŠī¸
- Host: GitHub
- URL: https://github.com/dknauss/sudo
- Owner: dknauss
- License: gpl-2.0
- Created: 2026-02-11T01:48:12.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T13:04:22.000Z (2 days ago)
- Last Synced: 2026-06-27T15:01:01.942Z (1 day ago)
- Topics: access-control, principle-of-least-privilege, sudo, wordpress-admin-backend, wordpress-admin-panel, wordpress-administrators, wordpress-auth, wordpress-cron, wordpress-multisite-compatible, wordpress-plugins, wordpress-rest-api, wordpress-security, wordpress-security-plugin, wordpress-users, wordpress-xmlrpc, wp-cli, wpgraphql, zero-trust
- Language: PHP
- Homepage: https://github.com/dknauss/wp-sudo
- Size: 18.3 MB
- Stars: 42
- Watchers: 0
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Roadmap: docs/ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Sudo
Require password confirmation before high-risk changes go through on your WordPress site â even from an already-authenticated admin session. Sudo also lets site owners define the shape of their administrative attack surface across admin UI, AJAX, REST, WP-CLI, Cron, XML-RPC, Application Passwords, and WPGraphQL. Built-in activity visibility, audit hooks, and governance controls help administrators see who is attempting sensitive actions and decide which users can manage Sudo policy.
[](https://spdx.org/licenses/GPL-2.0-or-later.html) [](SECURITY.md) [](docs/) [](docs/ai-authorship.md)
[](https://wordpress.org/)
[](https://www.php.net/)
[](https://github.com/dknauss/Sudo/actions/workflows/phpunit.yml)
[](https://github.com/dknauss/Sudo/actions/workflows/psalm.yml)
[](https://github.com/dknauss/Sudo/actions/workflows/e2e.yml)
[](https://github.com/dknauss/Sudo/actions/workflows/codeql.yml)
[](https://codecov.io/gh/dknauss/Sudo)
[](https://shepherd.dev/github/dknauss/Sudo)
[](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fraw.githubusercontent.com%2Fdknauss%2FSudo%2Fv4.1.0%2Fblueprint.json)
[](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fraw.githubusercontent.com%2Fdknauss%2FSudo%2Fmain%2Fblueprint-main.json)
Playground demo credentials are `admin` / `password`. When Sudo asks for reauthentication, enter the same password: `password`.
## Screenshots
Challenge page
Gated plugin activation
Settings tab
Gated Actions tab
Rule Tester tab
Access tab
Dashboard widget
Admin bar timer
Break-glass recovery notice
## Features
- **Confirmation before destructive actions** â plugin installs/deletions, user management, settings changes, core updates, and more all require a fresh password before proceeding
- **Two-factor support** â integrates with the [Two Factor plugin](https://wordpress.org/plugins/two-factor/) so the challenge includes your second factor when active
- **Short sudo window** â one confirmation covers 1â15 minutes of related work (your choice) so admins can work without interruption following one reauthentication challenge before being challenged again
- **Per-surface policies** â configure WP-CLI, Cron, XML-RPC, REST App Passwords, and WPGraphQL independently as Disabled, Limited, or Unrestricted
- **Privilege-escalation guard (opt-in)** â optionally refuse to grant a *new* administrator or super-admin unless the actor has an active sudo session, blocking the most common privilege-escalation shape even through another plugin's broken endpoint (off by default; see the FAQ)
- **Governance controls** â manage which users and roles can administer Sudo settings via a dedicated Access tab
- **Activity visibility** â audit hooks fire on every gated event; works with WP Activity Log, Stream, and similar plugins
- **Multisite support** â network-aware; super admins governed separately from per-site admins
## Quick start
1. Install and activate Sudo.
2. Go to **Settings â Sudo**.
3. Choose a session duration.
4. Review the default policies for non-interactive surfaces.
5. Optionally install the bundled mu-plugin loader from the settings page for earlier hook registration.
6. Test a covered action such as plugin activation or a protected settings change.
### Recommended companion plugins
- [Two Factor](https://wordpress.org/plugins/two-factor/) â strongly recommended for password + second-factor challenge flows.
- [WP Activity Log](https://wordpress.org/plugins/wp-security-audit-log/) or [Stream](https://wordpress.org/plugins/stream/) â recommended if you want audit visibility from Sudo's action hooks.
## What gets protected
Sudo gates built-in operations across categories including:
- plugin and theme installation, activation, and deletion
- user creation, deletion, and role changes
- file editor access
- critical option changes
- WordPress core updates
- export flows
- Sudo settings themselves
- selected Multisite network actions
- connector credential writes via the REST settings endpoint
For the full rule list and surface counts, see [docs/current-metrics.md](docs/current-metrics.md).
## Why it helps
WordPress has roles, capabilities, and authentication, but no native way to say "a logged-in session alone isn't enough for this action." Sudo adds that missing checkpoint for the parts of WordPress where a mistake, hijacked session, stale browser, or over-broad automation token can do the most damage.
That helps site owners, agencies, network operators, and teams with multiple administrators reduce the blast radius of privileged accounts. It is especially useful on sites where people, scripts, application passwords, WP-CLI jobs, Cron tasks, XML-RPC clients, WPGraphQL clients, or AI/agentic tooling can all reach administrative surfaces.
Sudo also makes privilege use more visible. The dashboard widget shows active sudo sessions, policy posture, and recent privileged activity; audit hooks and bundled bridges let logging plugins such as WP Activity Log and Stream record sudo sessions, gated requests, policy changes, and governance events.
The result is not just another password prompt. It is a way to define the shape and size of your site's administrative attack surface: close a surface entirely, limit it to non-destructive operations, require sudo for covered actions, or leave it unrestricted when that is the deliberate operational choice.
Active sudo is **per browser session**, not site-wide. Sudo works alongside your existing roles and capabilities â it does not replace them.
## How it works
More technically, Sudo is a Multisite-compatible, zero-trust-aligned security-hardening plugin for WordPress. It adds **action-gated reauthentication**, enables **attack surface definition** (open, closed, or sudo-gated), gives **visibility to privileged action requests**, and confines Sudo administration to explicitly designated users.
**Browser (wp-admin):** gated actions redirect to a challenge screen. After successful reauthentication, the original request replays automatically.
**AJAX and REST:** blocked requests receive a `sudo_required` error until reauthentication occurs.
**Non-interactive surfaces** (WP-CLI, Cron, XML-RPC, REST App Passwords, WPGraphQL): each can be set independently to Disabled, Limited, or Unrestricted under Settings â Sudo.
Before a covered high-risk action continues, the current user must reauthenticate by entering their password, followed by any active and compatible two-factor challenge. Successful reauthentication starts a short, configurable window of 1â15 minutes for additional covered actions in that browser session. WordPress core and the target feature still own their normal capability and authorization checks; Sudo adds the fresh-identity checkpoint before the covered action is allowed to continue.
Sudo gates specific operations on specific surfaces. It is not a firewall, exploit detector, malware scanner, or fix for authorization vulnerabilities inside third-party plugin code.
## Sudo administration and governance
"With great power comes great responsibility," so users with the capability to change Sudo settings, view sudo session activity, kill sudo sessions, or export sudo activity logs are limited by default:
- On **single sites**, the installing administrator receives all four caps. Other admins receive none until explicitly granted.
- On **multisite networks**, super administrators receive all four caps at network scope by default. Per-site admins receive none until explicitly delegated.
(Export privileges are separated from view privileges because a portable export artifact is a distinct governance concern â SOC2/GDPR audits treat "can read" and "can take a copy offsite" differently.)
Sudo integrates with the **Site Health** tool in WordPress core for rich security diagnostics and advisory notifications.
### Break-glass recovery scenario
In a lost, last administrator scenario where no one has access to Sudo's settings, the break-glass mechanism is to set `WP_SUDO_RECOVERY_MODE` in `wp-config.php`. This is Sudo's break-glass governance recovery path, not WordPress core's `WP_Recovery_Mode`. It requires filesystem access to activate, so it is not a remote-escalation vector. The grant is **role-gated**: while the constant is defined, the current user receives the master `manage_wp_sudo` capability only if they also hold `manage_options` (single-site) / `manage_network_options` (multisite), so a locked-out administrator recovers while non-admins gain nothing. A permanent non-dismissible notice appears on the Sudo settings screen while it is active, and the `wp_sudo_recovery_mode_active` audit hook fires so the usage is logged. The role gate does not eliminate the residual risk â every administrator regains full Sudo governance while the constant is set â so remove it the moment normal access is restored.
## For developers and integrators
Sudo exposes a small, stable API. Custom gated rules are plain associative arrays registered via the `wp_sudo_gated_actions` filter, with per-surface matchers for admin, AJAX, REST, and CLI. The `wp_sudo_can()` helper centralizes all governance checks â super-admin short-circuit and recovery-mode bypass, with always-strict capability checks (the `compatibility` mode was removed in 4.0.0) â so integrations don't touch capability internals directly. Audit hooks fire on every session event, capability grant or revoke, tamper detection, and policy change; bridge classes for WP Activity Log and Stream are bundled. The `wp_sudo_grant_session_on_login` filter lets SSO and kiosk integrations suppress the automatic browser-login session grant. All of this is covered by a dual-layer test suite (unit tests + a full integration matrix) and PHPStan level 6.
## Requirements
- **WordPress:** 6.4+
- **PHP:** 8.2+
- **Multisite:** supported
For current release posture, supported lanes, and forward `main` notes, see [docs/release-status.md](docs/release-status.md).
## Documentation
### Start here
- [docs/security-model.md](docs/security-model.md) â threat model, boundaries, and environmental assumptions
- [docs/FAQ.md](docs/FAQ.md) â practical questions and operational caveats
- [docs/release-status.md](docs/release-status.md) â current stable release state and forward-lane posture
### For developers and integrators
- [docs/developer-reference.md](docs/developer-reference.md) â hooks, filters, custom rule structure, and integration API details
- [docs/two-factor-integration.md](docs/two-factor-integration.md) â Two Factor integration behavior
- [docs/connectors-api-reference.md](docs/connectors-api-reference.md) â connector credential gating notes
- [docs/ai-agentic-guidance.md](docs/ai-agentic-guidance.md) â AI and agent tooling guidance
### Verification and project status
- [tests/MANUAL-TESTING.md](tests/MANUAL-TESTING.md) â manual verification procedures
- [docs/current-metrics.md](docs/current-metrics.md) â canonical current counts and architectural facts
- [docs/ROADMAP.md](docs/ROADMAP.md) â roadmap and backlog
- [CHANGELOG.md](CHANGELOG.md) â release history
### Background and research
- [docs/sudo-architecture-comparison-matrix.md](docs/sudo-architecture-comparison-matrix.md) â comparison with other sudo/reauth approaches
- [docs/abilities-api-assessment.md](docs/abilities-api-assessment.md) â WordPress Abilities API assessment
- [docs/core-action-gate-proposal.md](docs/core-action-gate-proposal.md) â longer-form core proposal and design thinking
- [docs/llm-lies-log.md](docs/llm-lies-log.md) â verification discipline and past documentation failures
- [docs/archive/project-introduction.md](docs/archive/project-introduction.md) â the longer conceptual introduction, graphic, poem, and gate metaphor preserved from the earlier README
## Development
Quick local checks:
```bash
composer install
composer test:unit
composer lint
composer analyse
```
For full setup, integration tests, E2E workflows, and contributor expectations, see [CONTRIBUTING.md](CONTRIBUTING.md).
## License
GPL-2.0-or-later.