# 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/.sh`. 2. Set ownership and permissions: ```bash chown perforce:perforce /p4/common/site/p4sudo/commands/.sh chmod 750 /p4/common/site/p4sudo/commands/.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: [] ALLOW user: [] ``` 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 ` 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 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.*