# P4Sudo Administrator and Maintainer's Guide

*Pre-implementation edition — covers design decisions, deployment guidance,
and operational notes before code is written.*

---

## Overview

P4Sudo is a site-level extension for SDP (Server Deployment Package)
Perforce environments. It gives non-superuser P4 accounts the ability to
run specific privileged operations, or entirely site-defined commands,
through a controlled, audited mechanism modeled on Unix `sudo`.

Implementation uses **p4broker** to intercept the non-native `p4 sudo`
command and route it to a runtime dispatcher. The tool is accessible only
through the `p4` CLI connected to the broker port — not through GUI clients
(P4V, etc.) or the P4 API.

---

## Directory Layout

All P4Sudo files live under `/p4/common/site/`:

```
/p4/common/site/
├── bin/
│   └── p4sudo                  # Optional CLI convenience wrapper
├── config/
│   └── p4sudo.cfg              # Access control configuration
└── p4sudo/
    ├── p4sudo.sh               # Core runtime (called by broker)
    ├── commands/               # Site-defined command scripts
    │   ├── mkproj.sh
    │   └── archive.sh
    └── logs/
        ├── p4sudo.log          # Operational log
        └── audit.log           # Audit trail
```

---

## Security

### Configuration File

`p4sudo.cfg` must be writable **only** by root or the SDP `perforce` OS user.
A world-writable config is a critical security vulnerability — it would allow
any OS user to grant themselves arbitrary P4 privileges.

```bash
chown perforce:perforce /p4/common/site/config/p4sudo.cfg
chmod 640 /p4/common/site/config/p4sudo.cfg
```

### Command Scripts

Scripts in `/p4/common/site/p4sudo/commands/` must be owned by a trusted OS
user (root or perforce), **not** by the `p4broker` process user. If the broker
process were compromised, it must not be able to modify its own command scripts.

```bash
chown perforce:perforce /p4/common/site/p4sudo/commands/*.sh
chmod 750 /p4/common/site/p4sudo/commands/*.sh
```

All scripts must treat all input as untrusted regardless of validation performed
at the rule layer.

### Service Account (`p4sudo-svc`)

The P4Sudo service account:

- Must hold the **minimum necessary** P4 permissions to execute the commands it
  needs to run. Full `super` access is convenient but unnecessary and
  inadvisable; prefer scoped permissions where feasible.
- Must **NOT** appear in any `[rules]` entry in `p4sudo.cfg`. Self-referential
  rules would allow privilege escalation via the service account itself.
- Must have a long-lived (or non-expiring) broker-side ticket so that the
  runtime does not fail due to session expiry.

### Input Handling

The P4Sudo runtime normalizes and validates all arguments before passing them
to scripts. Scripts must still perform their own input validation and must never
assume the calling layer has sanitized arguments sufficiently. Defense in depth
applies here.

---

## Group Membership Resolution

P4 group membership is resolved **at request time** by querying p4d — it is
not cached. This means:

- Granting or revoking group membership in P4 takes effect immediately for
  P4Sudo authorization decisions.
- No broker restart or cache flush is needed after group changes.

---

## Configuration Changes

The following changes take effect **immediately** without restarting the broker:

- Changes to `p4sudo.cfg` (rules, command definitions, settings)
- Adding, removing, or modifying command scripts in `commands/`

The following changes **require a broker restart**:

- Changes to the broker's own configuration file (`p4broker.conf`), e.g.
  adding or removing the `sudo` filter/rewrite rule itself.

---

## Audit Log

The audit log (`/p4/common/site/p4sudo/logs/audit.log`) is the immutable
record of allow and deny decisions.

**Never delete or modify audit log entries in place.**

Best practices:
- Use log rotation (e.g., `logrotate`) with archiving rather than truncation.
- Forward audit log entries to a centralized logging system (syslog, Splunk,
  ELK, etc.) if available at your site.
- Retain audit logs according to your site's security/compliance policy.

---

## Adding New Commands

1. Write the command script and place it in
   `/p4/common/site/p4sudo/commands/<name>.sh`.
2. Set ownership and permissions:
   ```bash
   chown perforce:perforce /p4/common/site/p4sudo/commands/<name>.sh
   chmod 750 /p4/common/site/p4sudo/commands/<name>.sh
   ```
3. Add a `[commands]` entry for it in `p4sudo.cfg`.
4. Add `[rules]` entries to grant access to the appropriate users/groups.
5. No broker restart required.

---

## Granting Access

Edit `p4sudo.cfg` and add a `[rules]` entry in the `[rules]` section:

```ini
ALLOW  group:<groupname>  <command>  [<arg-pattern>]
ALLOW  user:<username>    <command>  [<arg-pattern>]
```

Rules are evaluated top to bottom; first match wins. DENY rules take effect
on first match and do not fall through.

---

## Web Interface (Planned)

A web interface is planned for users who access P4 primarily through GUI
clients (P4V, etc.) and therefore cannot use `p4 sudo` via CLI.

Key design points (pending final decisions):

- Will authenticate via P4 credentials or site SSO.
- Will present only commands the authenticated user is authorized to run.
- Will use the same backend runtime and audit trail as the CLI path.
- Technology choice (Node.js or Apache/CGI) is TBD, pending evaluation of
  existing SDP environment, maintenance burden, and SSO requirements.

---

## Open Questions (Pre-Implementation)

Refer to `ai/p4sudo-claude-code-handoff.md` section 6 for the full list of
open questions requiring resolution before or during implementation.

Key items:

1. **Arg-pattern matching boundary** — What is the rule layer's job vs. the
   script's job? The boundary must be clearly documented per command.
2. **`p4 sudo help <subcommand>` routing** — Separate broker filter rule, or
   logic inside the runtime script?
3. **Service account privilege scope** — Global `super`, or per-command?
4. **Web interface technology** — Node.js or Apache/CGI?
5. **First use case** — To be captured from the requester; will inform several
   of the above decisions.
6. **`p4sudo` CLI wrapper behavior** — Simple `p4 -p <broker-port> sudo "$@"`
   passthrough, or additional convenience logic?
7. **Config format versioning** — Add explicit `format_version = 1` key?

---

*This guide will be updated as implementation progresses and open questions
are resolved.*