# P4Sudo

**Privileged Perforce operations for the people who need them — safely, audited,
and without handing out super-user access.**

---

## What Is P4Sudo?

P4Sudo is a framework that lets Perforce administrators delegate specific
privileged operations to authorized users through a controlled, fully audited
mechanism — modeled on the familiar Unix `sudo` command.

Instead of granting super-user access to everyone who occasionally needs it,
P4Sudo lets you define exactly *who* can do *what*, with *what arguments*, and
records every invocation in an immutable audit log.

The result: your operations team can self-serve the tasks they actually need,
your administrators keep control, and your security posture improves.

---

## The Problem It Solves

Some Perforce operations require super-user access — but the people who need to
run them often aren't Perforce administrators and shouldn't be. Examples:

- A release manager who needs to edit the protections table once a quarter
- A team lead who needs to create a new project depot and stream
- An ops engineer who needs to archive old depot paths before a migration
- A program manager who needs to provision a standard onboarding package

Today, the choices are: grant super access (too broad), ask an admin to do it
(too slow), or write a one-off trigger or script (inconsistent, ungoverned).

P4Sudo is a fourth option: a structured, policy-driven delegation layer that
sits between your users and your p4d server.

---

## How It Works

P4Sudo is implemented as a **p4broker filter script**. When a user runs:

```
p4 sudo <subcommand> [args...]
```

the broker intercepts the command and hands it to the P4Sudo dispatcher.
The dispatcher:

1. Identifies the authenticated requesting user (from the broker context —
   no trust placed in client-supplied identity)
2. Checks the site authorization policy (`p4sudo.cfg`)
3. Either dispatches to a privileged command script or rejects with a clear
   error message
4. Logs the allow/deny decision to the audit log

If authorized, the command runs under a dedicated service account
(`p4sudo-svc`) that holds only the minimum permissions required. The
requesting user never touches those credentials.

```
User runs: p4 sudo <subcommand> [args]
              │
              ▼
        p4broker :1671
              │  filter: p4sudo.sh
              ▼
        Authorization check
        (p4sudo.cfg rules)
              │
        ┌─────┴──────┐
      ALLOW         DENY
        │             │
        ▼             ▼
   Command script   Error returned
   runs as          to user
   p4sudo-svc
```

---

## Key Features

**Policy-driven authorization**
Rules in `p4sudo.cfg` control access by user or P4 group, by command name,
and optionally by argument pattern. Rules are evaluated top-to-bottom; the
first match wins.

```ini
# p4sudo.cfg excerpt
ALLOW  group:p4admin    *                   # admins can run anything
ALLOW  group:devleads   mkproj              # leads can create projects
ALLOW  group:devleads   archive  *--dry-run*  # leads can preview archives
ALLOW  user:alice       archive             # alice has full archive rights
ALLOW  group:rel-mgrs   protect  NOARGS    # release managers can edit protections
```

**Site-defined commands**
P4Sudo supports two command types:

- `native` — delegates standard p4 commands (like `p4 protect` or `p4 depot`)
  directly to p4d, run as the service account
- `script` — routes to a site-defined shell script for complex multi-step
  operations; scripts receive a validated argument list and a rich set of
  context environment variables

**Web UI support**
Complex commands can declare a web form definition (a YAML file) that
describes typed fields, required/optional inputs, and groupings. The P4Sudo
web application renders this into a form, handles validation, and submits
the command — making privileged operations accessible to non-CLI users.

**Complete audit trail**
Every invocation — allowed or denied — is written to an append-only audit log
with timestamp, user, command, and arguments. Operational logs follow the SDP
logging standard: per-invocation timestamped log files with a stable symlink
for monitoring integrations.

**`p4 help` integration**
Running `p4 help sudo` or `p4 help sudo <subcommand>` returns documentation
drawn from the command registry — no separate documentation system needed.

---

## Deploying P4Sudo

P4Sudo is designed to integrate with the
[Perforce Server Deployment Package (SDP)](https://workshop.perforce.com/projects/perforce-software-sdp).
It follows SDP conventions for directory layout, logging, and script style,
and expects the SDP to be present on the server where it is deployed.

The core components deployed to the server:

| File | Purpose |
|------|---------|
| `p4sudo.sh` | Core dispatcher — called by p4broker on every `p4 sudo` invocation |
| `p4sudo-help.sh` | Help interception — serves `p4 help sudo [subcommand]` |
| `p4sudo.cfg` | Authorization rules and site configuration |
| `commands/` | Directory of site-defined command scripts |
| `commands/*.ui.yaml` | Web form definitions for complex commands |

Two broker rules activate P4Sudo in the p4broker config:

```
command: ^(sudo)$
{
    action  = filter;
    execute = "/p4/common/site/p4sudo/p4sudo.sh";
}

command: ^(help)$
{
    action  = filter;
    execute = "/p4/common/site/p4sudo/p4sudo-help.sh";
}
```

---

## Repository Layout

```
bin/           Core dispatcher and help scripts
doc/           Design documents, example configs, and reference material
  broker-rewrite-reference/   p4broker filter protocol examples (CBD project)
ai/            Session logs and project governance (CLAUDE.md)
```

---

## Status

P4Sudo is under active development. The core dispatcher (`p4sudo.sh`),
help script (`p4sudo-help.sh`), and configuration format (`p4sudo.cfg`) are
complete. Site-defined command scripts and the web application are in progress.

Feedback and contributions welcome — open an issue or send a review via
[Perforce Swarm](https://workshop.perforce.com/projects/p4sudo).