{"id":49762159,"url":"https://github.com/dknauss/sudo","last_synced_at":"2026-06-28T07:01:15.623Z","repository":{"id":337790672,"uuid":"1154983208","full_name":"dknauss/Sudo","owner":"dknauss","description":"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, \u0026 XML-RPC. No role escalation, no new permissions — just a gate. ⛩️","archived":false,"fork":false,"pushed_at":"2026-06-27T13:04:22.000Z","size":19197,"stargazers_count":42,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T15:01:01.942Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://github.com/dknauss/wp-sudo","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dknauss.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"dknauss"}},"created_at":"2026-02-11T01:48:12.000Z","updated_at":"2026-06-27T13:04:26.000Z","dependencies_parsed_at":"2026-02-15T11:01:05.796Z","dependency_job_id":"decf537d-53b3-485f-8410-2a0f435c8564","html_url":"https://github.com/dknauss/Sudo","commit_stats":null,"previous_names":["dknauss/wp-sudo","dknauss/sudo"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/dknauss/Sudo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dknauss%2FSudo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dknauss%2FSudo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dknauss%2FSudo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dknauss%2FSudo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dknauss","download_url":"https://codeload.github.com/dknauss/Sudo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dknauss%2FSudo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34880189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-05-11T09:56:08.805Z","updated_at":"2026-06-28T07:01:15.614Z","avatar_url":"https://github.com/dknauss.png","language":"PHP","funding_links":["https://github.com/sponsors/dknauss"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/banner-1544x500.png\" alt=\"Sudo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Sudo\n\nRequire 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.\n\n[![License: GPL v2+](https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg)](https://spdx.org/licenses/GPL-2.0-or-later.html) [![Security Policy](https://img.shields.io/badge/security-policy-4c1)](SECURITY.md) [![Docs](https://img.shields.io/badge/docs-available-0a7ea4.svg)](docs/) [![AI Authorship](https://img.shields.io/badge/AI%20authorship-disclosed-8a63d2.svg)](docs/ai-authorship.md)\n[![WordPress: 6.4+](https://img.shields.io/badge/WordPress-6.4%2B-0073aa.svg)](https://wordpress.org/)\n[![PHP: 8.2+](https://img.shields.io/badge/PHP-8.2%2B-777bb4.svg)](https://www.php.net/)\n[![PHPUnit](https://github.com/dknauss/Sudo/actions/workflows/phpunit.yml/badge.svg)](https://github.com/dknauss/Sudo/actions/workflows/phpunit.yml)\n[![Psalm](https://github.com/dknauss/Sudo/actions/workflows/psalm.yml/badge.svg)](https://github.com/dknauss/Sudo/actions/workflows/psalm.yml)\n[![Playwright Tests](https://github.com/dknauss/Sudo/actions/workflows/e2e.yml/badge.svg)](https://github.com/dknauss/Sudo/actions/workflows/e2e.yml)\n[![CodeQL](https://github.com/dknauss/Sudo/actions/workflows/codeql.yml/badge.svg)](https://github.com/dknauss/Sudo/actions/workflows/codeql.yml)\n[![Codecov](https://codecov.io/gh/dknauss/Sudo/graph/badge.svg?branch=main)](https://codecov.io/gh/dknauss/Sudo)\n[![Type Coverage](https://shepherd.dev/github/dknauss/Sudo/coverage.svg)](https://shepherd.dev/github/dknauss/Sudo)\n[![Try latest release in Playground](https://img.shields.io/badge/Try%20release-Playground-3858e9?logo=wordpress\u0026logoColor=white)](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fraw.githubusercontent.com%2Fdknauss%2FSudo%2Fv4.1.0%2Fblueprint.json)\n[![Try main in Playground](https://img.shields.io/badge/Try%20main-Playground-23282d?logo=wordpress\u0026logoColor=white)](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fraw.githubusercontent.com%2Fdknauss%2FSudo%2Fmain%2Fblueprint-main.json)\n\nPlayground demo credentials are `admin` / `password`. When Sudo asks for reauthentication, enter the same password: `password`.\n\n## Screenshots\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-1.png\" alt=\"Sudo challenge page asking the current user to confirm their identity with a password.\"\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-2.png\" alt=\"Gated plugin activation — the Plugins page Activate link replaced with a reauthentication prompt.\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eChallenge page\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eGated plugin activation\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-3.png\" alt=\"Settings tab with policy presets, session duration, and entry-point policies.\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-4.png\" alt=\"Gated Actions tab showing protected operations and the surfaces where each rule applies.\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eSettings tab\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eGated Actions tab\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-5.png\" alt=\"Rule Tester tab evaluating a representative admin request without executing it.\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-6.png\" alt=\"Access tab for managing dedicated Sudo governance capabilities.\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eRule Tester tab\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eAccess tab\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-7.png\" alt=\"Dashboard widget with active sudo sessions, policy summary, and recent privilege-action events.\"\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-8.png\" alt=\"Admin bar showing a live countdown timer while a sudo session is active.\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eDashboard widget\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eAdmin bar timer\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/dknauss/Sudo/main/.wordpress-org/screenshot-9.png\" alt=\"Break-glass recovery notice shown on the Sudo settings screen while WP_SUDO_RECOVERY_MODE is active.\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eBreak-glass recovery notice\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Features\n\n- **Confirmation before destructive actions** — plugin installs/deletions, user management, settings changes, core updates, and more all require a fresh password before proceeding\n- **Two-factor support** — integrates with the [Two Factor plugin](https://wordpress.org/plugins/two-factor/) so the challenge includes your second factor when active\n- **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\n- **Per-surface policies** — configure WP-CLI, Cron, XML-RPC, REST App Passwords, and WPGraphQL independently as Disabled, Limited, or Unrestricted\n- **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)\n- **Governance controls** — manage which users and roles can administer Sudo settings via a dedicated Access tab\n- **Activity visibility** — audit hooks fire on every gated event; works with WP Activity Log, Stream, and similar plugins\n- **Multisite support** — network-aware; super admins governed separately from per-site admins\n\n## Quick start\n\n1. Install and activate Sudo.\n2. Go to **Settings → Sudo**.\n3. Choose a session duration.\n4. Review the default policies for non-interactive surfaces.\n5. Optionally install the bundled mu-plugin loader from the settings page for earlier hook registration.\n6. Test a covered action such as plugin activation or a protected settings change.\n\n### Recommended companion plugins\n\n- [Two Factor](https://wordpress.org/plugins/two-factor/) — strongly recommended for password + second-factor challenge flows.\n- [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.\n\n## What gets protected\n\nSudo gates built-in operations across categories including:\n- plugin and theme installation, activation, and deletion\n- user creation, deletion, and role changes\n- file editor access\n- critical option changes\n- WordPress core updates\n- export flows\n- Sudo settings themselves\n- selected Multisite network actions\n- connector credential writes via the REST settings endpoint\n\nFor the full rule list and surface counts, see [docs/current-metrics.md](docs/current-metrics.md).\n\n## Why it helps\n\nWordPress 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.\n\nThat 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.\n\nSudo 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.\n\nThe 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.\n\nActive sudo is **per browser session**, not site-wide. Sudo works alongside your existing roles and capabilities — it does not replace them.\n\n## How it works\n\nMore 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.\n\n**Browser (wp-admin):** gated actions redirect to a challenge screen. After successful reauthentication, the original request replays automatically.\n\n**AJAX and REST:** blocked requests receive a `sudo_required` error until reauthentication occurs.\n\n**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.\n\nBefore 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.\n\nSudo 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.\n\n## Sudo administration and governance\n\n\"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:\n\n- On **single sites**, the installing administrator receives all four caps. Other admins receive none until explicitly granted.\n- On **multisite networks**, super administrators receive all four caps at network scope by default. Per-site admins receive none until explicitly delegated.\n\n(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.)\n\nSudo integrates with the **Site Health** tool in WordPress core for rich security diagnostics and advisory notifications.\n\n### Break-glass recovery scenario\n\nIn 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.\n\n## For developers and integrators\n\nSudo 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.\n\n## Requirements\n\n- **WordPress:** 6.4+\n- **PHP:** 8.2+\n- **Multisite:** supported\n\nFor current release posture, supported lanes, and forward `main` notes, see [docs/release-status.md](docs/release-status.md).\n\n## Documentation\n\n### Start here\n- [docs/security-model.md](docs/security-model.md) — threat model, boundaries, and environmental assumptions\n- [docs/FAQ.md](docs/FAQ.md) — practical questions and operational caveats\n- [docs/release-status.md](docs/release-status.md) — current stable release state and forward-lane posture\n\n### For developers and integrators\n- [docs/developer-reference.md](docs/developer-reference.md) — hooks, filters, custom rule structure, and integration API details\n- [docs/two-factor-integration.md](docs/two-factor-integration.md) — Two Factor integration behavior\n- [docs/connectors-api-reference.md](docs/connectors-api-reference.md) — connector credential gating notes\n- [docs/ai-agentic-guidance.md](docs/ai-agentic-guidance.md) — AI and agent tooling guidance\n\n### Verification and project status\n- [tests/MANUAL-TESTING.md](tests/MANUAL-TESTING.md) — manual verification procedures\n- [docs/current-metrics.md](docs/current-metrics.md) — canonical current counts and architectural facts\n- [docs/ROADMAP.md](docs/ROADMAP.md) — roadmap and backlog\n- [CHANGELOG.md](CHANGELOG.md) — release history\n\n### Background and research\n- [docs/sudo-architecture-comparison-matrix.md](docs/sudo-architecture-comparison-matrix.md) — comparison with other sudo/reauth approaches\n- [docs/abilities-api-assessment.md](docs/abilities-api-assessment.md) — WordPress Abilities API assessment\n- [docs/core-action-gate-proposal.md](docs/core-action-gate-proposal.md) — longer-form core proposal and design thinking\n- [docs/llm-lies-log.md](docs/llm-lies-log.md) — verification discipline and past documentation failures\n- [docs/archive/project-introduction.md](docs/archive/project-introduction.md) — the longer conceptual introduction, graphic, poem, and gate metaphor preserved from the earlier README\n\n## Development\n\nQuick local checks:\n\n```bash\ncomposer install\ncomposer test:unit\ncomposer lint\ncomposer analyse\n```\n\nFor full setup, integration tests, E2E workflows, and contributor expectations, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nGPL-2.0-or-later.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdknauss%2Fsudo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdknauss%2Fsudo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdknauss%2Fsudo/lists"}