penpal-enum 0.2.0rc2__tar.gz

penpal_enum-0.2.0rc2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousif Nazhat
+
+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.

penpal_enum-0.2.0rc2/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: penpal-enum
+Version: 0.2.0rc2
+Summary: Backend-first enumeration assistant for authorized pentesters.
+Author: Yousif Nazhat
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yousifnazhat/penpal
+Project-URL: Issues, https://github.com/yousifnazhat/penpal/issues
+Project-URL: Changelog, https://github.com/yousifnazhat/penpal/blob/main/CHANGELOG.md
+Keywords: authorized-security,enumeration,pentesting,pi
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build==1.3.0; extra == "dev"
+Requires-Dist: ruff==0.15.20; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28; extra == "mcp"
+Dynamic: license-file
+
+# PenPal
+
+PenPal is a local-first assistant for authorized enumeration. It turns services and tool output into stored evidence, clear next checks, and visible command syntax. The Python core is deterministic; PI is the optional conversational cockpit.
+
+PenPal does not execute exploits, hide commands, use credentials automatically, or provide C2 tasking.
+
+## Choose Your Path
+
+### Run the demo with PI
+
+Use this path when you want the conversational cockpit. Download a release archive or clone the repository. You need Python 3.11 or newer, Node.js 22.19 or newer, and npm.
+
+```bash
+git clone https://github.com/yousifnazhat/penpal.git
+cd penpal
+python3 -m penpal doctor
+python3 -m penpal --workspace penpal-workspace scope set --include 10.10.10.5
+python3 -m penpal --workspace penpal-workspace init 10.10.10.5 --name demo
+python3 -m penpal --workspace penpal-workspace parse-nmap demo examples/pi/demo-nmap.xml
+python3 -m penpal --workspace penpal-workspace suggest demo
+./scripts/setup-pi.sh
+pi
+```
+
+On Windows PowerShell, run `./scripts/setup-pi.ps1` instead. The setup scripts install the pinned PI version when it is missing, then verify the project package without using a model or provider credentials.
+
+Inside PI, approve project-local files if prompted, run `/login` when a provider is not configured, then try:
+
+```text
+Use PenPal to summarize target demo and recommend next checks.
+```
+
+Run `/penpal-status` for a provider-free check that PI, PenPal, and the bundled playbooks are connected.
+
+### Connect an MCP client
+
+Use this path when your existing agent supports MCP rather than PI. Install the optional local server, then configure the client to start the shown command over stdio:
+
+```bash
+python3 -m pip install --pre "penpal-enum[mcp]"
+penpal --workspace penpal-workspace mcp
+```
+
+The MCP server has the same seven read-only workflows as the PI cockpit. It masks sensitive values and does not execute commands or modify your workspace.
+
+### Use the Python core only
+
+The core works without PI. Install it and create a target:
+
+```bash
+python3 -m pip install --pre penpal-enum
+penpal doctor
+penpal init 10.10.10.5 --name demo
+penpal parse-nmap demo ./scan.xml
+penpal suggest demo
+```
+
+The release wheel and source archive also include the Python core and bundled playbooks. Add the PI cockpit to a registry installation with:
+
+```bash
+pi install npm:@yousif_nazhat/penpal-pi@0.2.0-rc.2
+```
+
+### Diagnose setup
+
+```bash
+penpal doctor
+penpal doctor --json
+```
+
+Doctor checks the Python version, playbooks, workspace schemas, scope, plaintext sensitive parameters, missing environment variables, and PI status. It does not modify the workspace. Include the redacted JSON output in bug reports.
+
+## What PenPal Does
+
+- Stores scoped targets, services, evidence, parameters, notes, and jobs in a local workspace.
+- Parses Nmap XML and ingests pasted or saved tool output.
+- Masks credential-like evidence and sensitive parameters by default.
+- Uses deterministic suggestions, service modules, and reviewed playbooks to explain the next authorized check.
+- Uses environment references for secrets so values are not persisted in workspace JSON.
+- Provides a loopback-only JSON API for local integrations.
+
+## Everyday Commands
+
+```text
+penpal doctor
+penpal init <host> --name <name>
+penpal scope set --include <host-or-cidr> [--exclude <host-or-cidr>]
+penpal parse-nmap <name> <nmap.xml>
+penpal ingest <name> --file <output.txt> --source <tool-name> --service <proto/port>
+penpal services <name>
+penpal evidence <name>
+penpal suggest <name>
+penpal context <name> --json
+penpal mcp
+penpal playbooks playbooks
+penpal modules list
+penpal modules plan <name> <module>
+```
+
+`scan` prints commands by default. It runs them only with `--execute`. Use `params set-env` for passwords, tokens, and keys; `params set` keeps sensitive values in local plaintext for compatibility.
+
+## Safety
+
+Configure engagement scope before a real assessment. Keep the local API on its default loopback address. Review every suggested command and remain responsible for authorization. Playbooks require authorized use and operator approval.
+
+## Help And Contributing
+
+- [Support policy](SUPPORT.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+- [Playbook template](playbooks/TEMPLATE.md)
+
+Run the contributor checks with:
+
+```bash
+python3 -m pip install ".[dev]"
+python3 scripts/check.py
+```

penpal_enum-0.2.0rc2/README.md

@@ -0,0 +1,119 @@
+# PenPal
+
+PenPal is a local-first assistant for authorized enumeration. It turns services and tool output into stored evidence, clear next checks, and visible command syntax. The Python core is deterministic; PI is the optional conversational cockpit.
+
+PenPal does not execute exploits, hide commands, use credentials automatically, or provide C2 tasking.
+
+## Choose Your Path
+
+### Run the demo with PI
+
+Use this path when you want the conversational cockpit. Download a release archive or clone the repository. You need Python 3.11 or newer, Node.js 22.19 or newer, and npm.
+
+```bash
+git clone https://github.com/yousifnazhat/penpal.git
+cd penpal
+python3 -m penpal doctor
+python3 -m penpal --workspace penpal-workspace scope set --include 10.10.10.5
+python3 -m penpal --workspace penpal-workspace init 10.10.10.5 --name demo
+python3 -m penpal --workspace penpal-workspace parse-nmap demo examples/pi/demo-nmap.xml
+python3 -m penpal --workspace penpal-workspace suggest demo
+./scripts/setup-pi.sh
+pi
+```
+
+On Windows PowerShell, run `./scripts/setup-pi.ps1` instead. The setup scripts install the pinned PI version when it is missing, then verify the project package without using a model or provider credentials.
+
+Inside PI, approve project-local files if prompted, run `/login` when a provider is not configured, then try:
+
+```text
+Use PenPal to summarize target demo and recommend next checks.
+```
+
+Run `/penpal-status` for a provider-free check that PI, PenPal, and the bundled playbooks are connected.
+
+### Connect an MCP client
+
+Use this path when your existing agent supports MCP rather than PI. Install the optional local server, then configure the client to start the shown command over stdio:
+
+```bash
+python3 -m pip install --pre "penpal-enum[mcp]"
+penpal --workspace penpal-workspace mcp
+```
+
+The MCP server has the same seven read-only workflows as the PI cockpit. It masks sensitive values and does not execute commands or modify your workspace.
+
+### Use the Python core only
+
+The core works without PI. Install it and create a target:
+
+```bash
+python3 -m pip install --pre penpal-enum
+penpal doctor
+penpal init 10.10.10.5 --name demo
+penpal parse-nmap demo ./scan.xml
+penpal suggest demo
+```
+
+The release wheel and source archive also include the Python core and bundled playbooks. Add the PI cockpit to a registry installation with:
+
+```bash
+pi install npm:@yousif_nazhat/penpal-pi@0.2.0-rc.2
+```
+
+### Diagnose setup
+
+```bash
+penpal doctor
+penpal doctor --json
+```
+
+Doctor checks the Python version, playbooks, workspace schemas, scope, plaintext sensitive parameters, missing environment variables, and PI status. It does not modify the workspace. Include the redacted JSON output in bug reports.
+
+## What PenPal Does
+
+- Stores scoped targets, services, evidence, parameters, notes, and jobs in a local workspace.
+- Parses Nmap XML and ingests pasted or saved tool output.
+- Masks credential-like evidence and sensitive parameters by default.
+- Uses deterministic suggestions, service modules, and reviewed playbooks to explain the next authorized check.
+- Uses environment references for secrets so values are not persisted in workspace JSON.
+- Provides a loopback-only JSON API for local integrations.
+
+## Everyday Commands
+
+```text
+penpal doctor
+penpal init <host> --name <name>
+penpal scope set --include <host-or-cidr> [--exclude <host-or-cidr>]
+penpal parse-nmap <name> <nmap.xml>
+penpal ingest <name> --file <output.txt> --source <tool-name> --service <proto/port>
+penpal services <name>
+penpal evidence <name>
+penpal suggest <name>
+penpal context <name> --json
+penpal mcp
+penpal playbooks playbooks
+penpal modules list
+penpal modules plan <name> <module>
+```
+
+`scan` prints commands by default. It runs them only with `--execute`. Use `params set-env` for passwords, tokens, and keys; `params set` keeps sensitive values in local plaintext for compatibility.
+
+## Safety
+
+Configure engagement scope before a real assessment. Keep the local API on its default loopback address. Review every suggested command and remain responsible for authorization. Playbooks require authorized use and operator approval.
+
+## Help And Contributing
+
+- [Support policy](SUPPORT.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+- [Playbook template](playbooks/TEMPLATE.md)
+
+Run the contributor checks with:
+
+```bash
+python3 -m pip install ".[dev]"
+python3 scripts/check.py
+```

penpal_enum-0.2.0rc2/penpal/__init__.py

@@ -0,0 +1,3 @@
+"""PenPal: backend-first enumeration assistant for authorized pentesters."""
+
+__version__ = "0.2.0rc2"

penpal_enum-0.2.0rc2/penpal/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())