sudoplz 0.2.0__tar.gz

sudoplz-0.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# Tool caches
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+
+# Named pipes (created at runtime)
+/tmp/sudo_command
+/tmp/sudo_response
+
+# System
+.DS_Store
+Thumbs.db

sudoplz-0.2.0/CLAUDE.md

@@ -0,0 +1,32 @@
+# sudoplz Project Guidelines
+
+## Project Overview
+sudoplz gives AI coding agents (Claude Code, Cursor, etc.) the ability to run `sudo` commands with case-by-case GUI approval. The sudo password is encrypted with the user's SSH key. The project ships two entry points:
+- `askpass` - Invoked by `sudo -A` via `SUDO_ASKPASS`; performs security checks and prints the decrypted password on approval
+- `sudoplz` - Management CLI (set/get/clear/test/audit, plus TOTP for headless sessions)
+
+## Development Guidelines
+
+1. **Tool Usage**:
+   - Use `bash` commands directly for basic operations
+   - For complex searches, use the `Task` tool
+   - When making multiple bash calls, use `Batch` for parallel execution
+
+2. **Code Style**:
+   - Follow existing conventions in the askpass scripts
+   - Keep scripts minimal and focused on single responsibilities
+   - No unnecessary comments unless explicitly requested
+
+3. **Testing**:
+   - Test both `askpass` and `sudoplz` components
+   - Verify SSH key encryption/decryption functionality
+   - Ensure secure password handling
+
+4. **Security**:
+   - Never log or expose passwords in plain text
+   - Verify SSH key permissions are properly restricted
+   - Follow secure coding practices for password handling
+
+5. **Commits**:
+   - Only commit when explicitly requested
+   - Follow existing commit style from git history

sudoplz-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sudoplz-0.2.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: sudoplz
+Version: 0.2.0
+Summary: Give AI coding agents case-by-case sudo access via GUI approval, with SSH-key-encrypted password storage
+Project-URL: Homepage, https://github.com/crypdick/sudoplz
+Project-URL: Issues, https://github.com/crypdick/sudoplz/issues
+Project-URL: Source, https://github.com/crypdick/sudoplz
+Author-email: Ricardo Decal <biz@ricardodecal.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,askpass,claude-code,cursor,security,ssh,sudo
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: keyring>=24
+Description-Content-Type: text/markdown
+
+# sudoplz
+
+Give Claude Code, Cursor, and other AI coding agents the ability to run `sudo` — with case-by-case GUI approval, no passwordless sudo, no `/etc/sudoers` allowlists.
+
+Your sudo password is encrypted with your SSH private key and only decrypted after you approve a dialog showing the exact command about to run. Deny the dialog and nothing happens.
+
+## Why
+
+Coding agents can't handle interactive terminal prompts. Ask Claude Code to run `sudo apt install foo` and you get `sudo: Authentication failed`. The common workarounds all have problems:
+
+- **Passwordless sudo** gives the agent — and anything else running as your user — unrestricted root.
+- **`/etc/sudoers` allowlists** require predicting every command the agent will ever need. No case-by-case review.
+- **Manual copy-paste** is tedious and breaks the agent's flow.
+
+`sudoplz` plugs into `sudo -A`, so the agent runs `sudo -A <command>`, you see a dialog with the exact command, and you click Allow or Deny. Works for any command without pre-declaring what's permitted.
+
+This threat model assumes a personal workstation with an encrypted disk and a passphrase-protected SSH key. Not appropriate for shared or production systems.
+
+## Installation
+
+1. **Use traditional `sudo`, not `sudo-rs`.** `sudo-rs` doesn't support askpass. Check with `sudo --version` — it should say "Sudo version 1.x.x". If you're on `sudo-rs`, switch:
+   ```bash
+   sudo update-alternatives --install /usr/bin/sudo sudo /usr/bin/sudo.ws 100
+   sudo update-alternatives --config sudo   # pick sudo.ws
+   ```
+2. Make sure you have an SSH key (ed25519, ecdsa, rsa, or dsa).
+3. Install system dependencies:
+   - [`age`](https://github.com/FiloSottile/age) — required if your SSH key is Ed25519 (the most common case today). `sudo pacman -S age` / `sudo apt install age` / `brew install age`.
+   - `zenity` on Linux — provides the GUI approval dialog. Pre-installed on most GNOME-based distros; `sudo apt install zenity` if missing. Not needed on macOS (uses AppleScript).
+4. Install the tools with [`uv`](https://docs.astral.sh/uv/):
+   ```bash
+   uv tool install .
+   ```
+   This puts `askpass` and `sudoplz` on your PATH.
+5. Point `SUDO_ASKPASS` at the installed binary (add to `~/.bashrc`, `~/.zshrc`, etc.):
+   ```bash
+   export SUDO_ASKPASS="$(which askpass)"
+   ```
+6. Store your sudo password:
+   ```bash
+   sudoplz set
+   ```
+
+## Usage
+
+Your agent (or you) runs `sudo -A <command>`. A dialog pops up showing the command. You approve or deny.
+
+```bash
+sudo -A apt install foo
+```
+
+Gotcha: `sudo -n` explicitly disallows prompting and will never trigger askpass. Always use `-A`.
+
+Test the integration with:
+
+```bash
+sudoplz test
+```
+
+## Security
+
+### Encryption at rest
+
+Passwords are encrypted with your SSH key:
+
+- **Ed25519**: `age` encryption, stored at `~/.sudo_askpass.age`
+- **RSA/ECDSA/DSA**: OpenSSL asymmetric encryption, stored at `~/.sudo_askpass.ssh`
+
+Encrypted files have 600 permissions. Key preference: ed25519 > ecdsa > rsa > dsa. Falls back to the system keyring if available. Refuses plain text storage.
+
+### Defense in depth
+
+Encryption alone doesn't cover every abuse path — anything running as your user can in principle request decryption. The askpass script runs these checks on every invocation; any failure means no decryption:
+
+- **Caller path whitelist.** Only decrypts when the caller's working directory is on an allowlist (home, `/tmp`, etc.). Blocks invocations from unexpected locations like `/var/tmp/malicious`.
+- **Caller process whitelist.** Parent process must be on an allowlist (sudo, your shell, your IDE, your deploy tool). Keeps arbitrary binaries from invoking askpass directly.
+- **User confirmation.** A GUI dialog asks for approval on each decryption, so any sudo elevation you didn't initiate is visible and can be denied.
+- **Rate limiting.** Configurable max-attempts-per-hour and lockout window. Contains runaway scripts and brute-force attempts.
+- **Password expiration.** Stored passwords age out automatically (default: 1 week). A stolen blob becomes useless once it expires, even with your SSH key.
+
+Configure these in `~/.config/sudoplz/config.json` — an example is shipped as `askpass-config.json` in the repo; copy it and edit.
+
+### Why age for Ed25519?
+
+Ed25519 is a signing algorithm (EdDSA), not encryption. OpenSSL handles RSA encryption directly, but Ed25519 keys can't do asymmetric encryption at all. `age` was designed to work with SSH keys including Ed25519.
+
+### SSH key unlocking
+
+If your SSH key has a passphrase (recommended), the askpass tool will:
+
+1. Check whether the key is loaded in ssh-agent
+2. Prompt for the passphrase via GUI if it isn't
+3. Load the key into ssh-agent for the session
+
+You enter the passphrase once per session. After that, sudo commands only need the confirmation dialog. You need a running ssh-agent — most desktop environments start one on login; if not, `eval "$(ssh-agent -s)"` in your shell startup.
+
+This works under `sudo -A` even though sudo strips `SSH_AUTH_SOCK`: the script reconnects to your running ssh-agent.
+
+## Commands
+
+```bash
+sudoplz set        # Store password (terminal prompt; expires per config, 1 week default)
+sudoplz set-totp   # Store password with TOTP verification (headless)
+sudoplz totp-setup # Set up TOTP for headless sessions
+sudoplz get        # Check if password exists
+sudoplz clear      # Remove password
+sudoplz test       # Test sudo integration
+sudoplz audit      # Show recent askpass usage
+```
+
+## Headless/SSH usage with TOTP
+
+For servers or SSH sessions without a display, authenticate with TOTP.
+
+### Initial setup (run once from a GUI session)
+
+```bash
+sudoplz totp-setup
+```
+
+Prints a TOTP secret and an `otpauth://` URL to add to your authenticator app.
+
+### Setting a password from a headless session
+
+```bash
+sudoplz set-totp
+```
+
+Enter your 6-digit TOTP code, then your password.
+
+### Using sudo with TOTP
+
+When `DISPLAY` isn't set, askpass prompts for a TOTP code:
+
+```bash
+# Interactive — prompts for TOTP code
+sudo -A command
+
+# Non-interactive — pass TOTP via environment
+TOTP="123456" sudo -A command
+```
+
+## Credits
+
+The idea — an SSH-key-encrypted sudo password served via `SUDO_ASKPASS`, gated by a confirmation dialog — is from [GlassOnTin/secure-askpass](https://github.com/GlassOnTin/secure-askpass). That project is dormant; `sudoplz` is a substantially rewritten and cleaned up fork. Thanks to [@GlassOnTin](https://github.com/GlassOnTin) for the original idea.
+
+## License
+
+MIT — see LICENSE.

sudoplz-0.2.0/README.md

@@ -0,0 +1,149 @@
+# sudoplz
+
+Give Claude Code, Cursor, and other AI coding agents the ability to run `sudo` — with case-by-case GUI approval, no passwordless sudo, no `/etc/sudoers` allowlists.
+
+Your sudo password is encrypted with your SSH private key and only decrypted after you approve a dialog showing the exact command about to run. Deny the dialog and nothing happens.
+
+## Why
+
+Coding agents can't handle interactive terminal prompts. Ask Claude Code to run `sudo apt install foo` and you get `sudo: Authentication failed`. The common workarounds all have problems:
+
+- **Passwordless sudo** gives the agent — and anything else running as your user — unrestricted root.
+- **`/etc/sudoers` allowlists** require predicting every command the agent will ever need. No case-by-case review.
+- **Manual copy-paste** is tedious and breaks the agent's flow.
+
+`sudoplz` plugs into `sudo -A`, so the agent runs `sudo -A <command>`, you see a dialog with the exact command, and you click Allow or Deny. Works for any command without pre-declaring what's permitted.
+
+This threat model assumes a personal workstation with an encrypted disk and a passphrase-protected SSH key. Not appropriate for shared or production systems.
+
+## Installation
+
+1. **Use traditional `sudo`, not `sudo-rs`.** `sudo-rs` doesn't support askpass. Check with `sudo --version` — it should say "Sudo version 1.x.x". If you're on `sudo-rs`, switch:
+   ```bash
+   sudo update-alternatives --install /usr/bin/sudo sudo /usr/bin/sudo.ws 100
+   sudo update-alternatives --config sudo   # pick sudo.ws
+   ```
+2. Make sure you have an SSH key (ed25519, ecdsa, rsa, or dsa).
+3. Install system dependencies:
+   - [`age`](https://github.com/FiloSottile/age) — required if your SSH key is Ed25519 (the most common case today). `sudo pacman -S age` / `sudo apt install age` / `brew install age`.
+   - `zenity` on Linux — provides the GUI approval dialog. Pre-installed on most GNOME-based distros; `sudo apt install zenity` if missing. Not needed on macOS (uses AppleScript).
+4. Install the tools with [`uv`](https://docs.astral.sh/uv/):
+   ```bash
+   uv tool install .
+   ```
+   This puts `askpass` and `sudoplz` on your PATH.
+5. Point `SUDO_ASKPASS` at the installed binary (add to `~/.bashrc`, `~/.zshrc`, etc.):
+   ```bash
+   export SUDO_ASKPASS="$(which askpass)"
+   ```
+6. Store your sudo password:
+   ```bash
+   sudoplz set
+   ```
+
+## Usage
+
+Your agent (or you) runs `sudo -A <command>`. A dialog pops up showing the command. You approve or deny.
+
+```bash
+sudo -A apt install foo
+```
+
+Gotcha: `sudo -n` explicitly disallows prompting and will never trigger askpass. Always use `-A`.
+
+Test the integration with:
+
+```bash
+sudoplz test
+```
+
+## Security
+
+### Encryption at rest
+
+Passwords are encrypted with your SSH key:
+
+- **Ed25519**: `age` encryption, stored at `~/.sudo_askpass.age`
+- **RSA/ECDSA/DSA**: OpenSSL asymmetric encryption, stored at `~/.sudo_askpass.ssh`
+
+Encrypted files have 600 permissions. Key preference: ed25519 > ecdsa > rsa > dsa. Falls back to the system keyring if available. Refuses plain text storage.
+
+### Defense in depth
+
+Encryption alone doesn't cover every abuse path — anything running as your user can in principle request decryption. The askpass script runs these checks on every invocation; any failure means no decryption:
+
+- **Caller path whitelist.** Only decrypts when the caller's working directory is on an allowlist (home, `/tmp`, etc.). Blocks invocations from unexpected locations like `/var/tmp/malicious`.
+- **Caller process whitelist.** Parent process must be on an allowlist (sudo, your shell, your IDE, your deploy tool). Keeps arbitrary binaries from invoking askpass directly.
+- **User confirmation.** A GUI dialog asks for approval on each decryption, so any sudo elevation you didn't initiate is visible and can be denied.
+- **Rate limiting.** Configurable max-attempts-per-hour and lockout window. Contains runaway scripts and brute-force attempts.
+- **Password expiration.** Stored passwords age out automatically (default: 1 week). A stolen blob becomes useless once it expires, even with your SSH key.
+
+Configure these in `~/.config/sudoplz/config.json` — an example is shipped as `askpass-config.json` in the repo; copy it and edit.
+
+### Why age for Ed25519?
+
+Ed25519 is a signing algorithm (EdDSA), not encryption. OpenSSL handles RSA encryption directly, but Ed25519 keys can't do asymmetric encryption at all. `age` was designed to work with SSH keys including Ed25519.
+
+### SSH key unlocking
+
+If your SSH key has a passphrase (recommended), the askpass tool will:
+
+1. Check whether the key is loaded in ssh-agent
+2. Prompt for the passphrase via GUI if it isn't
+3. Load the key into ssh-agent for the session
+
+You enter the passphrase once per session. After that, sudo commands only need the confirmation dialog. You need a running ssh-agent — most desktop environments start one on login; if not, `eval "$(ssh-agent -s)"` in your shell startup.
+
+This works under `sudo -A` even though sudo strips `SSH_AUTH_SOCK`: the script reconnects to your running ssh-agent.
+
+## Commands
+
+```bash
+sudoplz set        # Store password (terminal prompt; expires per config, 1 week default)
+sudoplz set-totp   # Store password with TOTP verification (headless)
+sudoplz totp-setup # Set up TOTP for headless sessions
+sudoplz get        # Check if password exists
+sudoplz clear      # Remove password
+sudoplz test       # Test sudo integration
+sudoplz audit      # Show recent askpass usage
+```
+
+## Headless/SSH usage with TOTP
+
+For servers or SSH sessions without a display, authenticate with TOTP.
+
+### Initial setup (run once from a GUI session)
+
+```bash
+sudoplz totp-setup
+```
+
+Prints a TOTP secret and an `otpauth://` URL to add to your authenticator app.
+
+### Setting a password from a headless session
+
+```bash
+sudoplz set-totp
+```
+
+Enter your 6-digit TOTP code, then your password.
+
+### Using sudo with TOTP
+
+When `DISPLAY` isn't set, askpass prompts for a TOTP code:
+
+```bash
+# Interactive — prompts for TOTP code
+sudo -A command
+
+# Non-interactive — pass TOTP via environment
+TOTP="123456" sudo -A command
+```
+
+## Credits
+
+The idea — an SSH-key-encrypted sudo password served via `SUDO_ASKPASS`, gated by a confirmation dialog — is from [GlassOnTin/secure-askpass](https://github.com/GlassOnTin/secure-askpass). That project is dormant; `sudoplz` is a substantially rewritten and cleaned up fork. Thanks to [@GlassOnTin](https://github.com/GlassOnTin) for the original idea.
+
+## License
+
+MIT — see LICENSE.

sudoplz-0.2.0/askpass-config.json

@@ -0,0 +1,15 @@
+{
+  "require_user_confirmation": true,
+  "allowed_paths": [
+    "/tmp/",
+    "/var/tmp/"
+  ],
+  "expiration_hours": 168,
+  "allowed_processes": [
+    "sudo",
+    "bash",
+    "sh"
+  ],
+  "max_attempts_per_hour": 120,
+  "lockout_minutes": 15
+}

sudoplz-0.2.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "sudoplz"
+version = "0.2.0"
+description = "Give AI coding agents case-by-case sudo access via GUI approval, with SSH-key-encrypted password storage"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Ricardo Decal", email = "biz@ricardodecal.com" },
+]
+keywords = ["sudo", "askpass", "ssh", "ai-agents", "claude-code", "cursor", "security"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: System :: Systems Administration :: Authentication/Directory",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "keyring>=24",
+]
+
+[project.urls]
+Homepage = "https://github.com/crypdick/sudoplz"
+Issues = "https://github.com/crypdick/sudoplz/issues"
+Source = "https://github.com/crypdick/sudoplz"
+
+[project.scripts]
+askpass = "sudoplz.askpass:main"
+sudoplz = "sudoplz.manager:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sudoplz"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.10",
+]

sudoplz-0.2.0/src/sudoplz/__init__.py

@@ -0,0 +1,3 @@
+"""Secure SSH-key-encrypted askpass helper for sudo."""
+
+__version__ = "0.2.0"