pawnlogic-security 0.1.0__tar.gz

pawnlogic_security-0.1.0/LICENSE

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

pawnlogic_security-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: pawnlogic-security
+Version: 0.1.0
+Summary: Scope-gated security tooling for the PawnLogic agent host
+Author: PawnLogic Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/john0123412/pawnlogic-security
+Project-URL: Issues, https://github.com/john0123412/pawnlogic-security/issues
+Keywords: pawnlogic,security,extension,reconnaissance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pawnlogic<0.4,>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# pawnlogic-security
+
+Scope-gated security tooling for the [PawnLogic](https://github.com/john0123412/PawnLogic)
+agent host, distributed independently of the core package.
+
+Installing this package does not authorize or enable it. The PawnLogic
+Extension stays disabled until an operator explicitly enables it, and its
+network tools remain unavailable until a valid Engagement Scope is active.
+
+## Status
+
+The current public release is `0.1.0`, published independently of the
+PawnLogic core package. It implements:
+
+- a versioned Engagement Scope file with exact hosts, CIDRs, exclusions,
+  explicit ports, passive/active actions, expiry, and request, concurrency, and
+  duration budgets
+- scope-gated passive DNS, TLS, HTTP-header, and technology reconnaissance
+- scope-gated bounded active port discovery
+- append-only redacted evidence records
+- two built-in, versioned workflows shared by `pawn-security` and `/security`
+- reproducible workflow plans and versioned local run records
+- an optional, default-disabled JSON child-process adapter with Operation Policy
+  checks, bounded I/O, timeout cleanup, environment isolation, and output
+  redaction
+
+It does not implement HTTP replay, external scanner adapters, workflow YAML
+loading, CIDR expansion, exploit or destructive workflows, MCP execution, or
+an AI-generated planner. No built-in workflow invokes the optional child
+adapter.
+
+## Requirements
+
+- Python 3.10 or newer
+- `pawnlogic>=0.3,<0.4`
+
+## Install
+
+Install the published package:
+
+```bash
+python -m pip install pawnlogic-security
+```
+
+For checkout development:
+
+```bash
+python -m pip install -e .
+```
+
+Nothing is loaded merely because the distribution is installed.
+
+## Enable in PawnLogic
+
+```text
+/extension list
+/extension enable security
+/extension status security
+```
+
+The Extension contributes `/security` after enablement:
+
+```text
+/security status
+/security scope show
+/security scope set <scope-file>
+/security scope clear
+/security plan <objective>
+/security run <workflow>
+/security evidence list
+/security evidence export <run-id>
+```
+
+`/security` is an async host command and writes through the active PawnLogic
+output sink. Scope changes rebuild the complete contribution set atomically:
+the command remains present while security tools appear or disappear.
+
+Disable the Extension with:
+
+```text
+/extension disable security
+```
+
+## Engagement Scope
+
+Every operation requires an explicit, unexpired Engagement Scope. A minimal
+passive scope file looks like:
+
+```json
+{
+  "version": 1,
+  "identifier": "authorized-review",
+  "authorized_by": "security-team",
+  "reference": "CHANGE-1234",
+  "expires_at": 4102444800,
+  "targets": ["app.example.com"],
+  "exclude": [],
+  "ports": ["443"],
+  "allow_active": false,
+  "actions": ["passive"],
+  "destructive": false,
+  "max_requests": 20,
+  "max_concurrency": 1,
+  "max_duration": 300,
+  "evidence_dir": "evidence"
+}
+```
+
+Active discovery additionally requires `allow_active: true`, the `active`
+action, and explicit ports, for example `"ports": ["443", "8000-8010"]`.
+Destructive authorization is rejected because destructive workflows are not
+implemented.
+
+The passive example explicitly authorizes port `443` because TLS inspection and
+HTTPS header collection make network connections even though they do not send
+active probes.
+
+Scope is necessary but never sufficient. The host Network Policy runs after
+scope validation and may still refuse the target. Resolved addresses and
+redirect changes must remain in scope. Model-provided tool arguments cannot
+grant authorization.
+
+## Workflows
+
+The built-in workflow manifests have schema version `1` and their own workflow
+version:
+
+- `passive-recon` runs `security_passive_recon`
+- `active-discovery` runs `security_active_discovery`
+
+Both direct and hosted commands call the same `WorkflowRunner` interface:
+
+```bash
+pawn-security scope validate <scope-file>
+pawn-security run passive-recon --scope <scope-file>
+```
+
+```text
+/security run passive-recon
+```
+
+The runner sorts explicit host targets and runs one workflow target at a time.
+The execution adapters consume the engagement-wide request budget before
+individual network requests. The runner does not expand a CIDR into hosts.
+`active-discovery` additionally requires an active scope; port-scan concurrency
+remains bounded by the scope.
+
+`/security plan <objective>` is deliberately conservative. It returns a
+deterministic suggestion to begin with `passive-recon`, reports that execution
+has not started, and performs no network work.
+
+## Evidence
+
+When the active scope sets `evidence_dir`, tool observations and run records
+are written there. A relative `evidence_dir` is resolved from the directory
+containing the scope file. Without `evidence_dir`, they fall back to:
+
+```text
+<runtime home>/security/evidence.jsonl
+```
+
+The direct command uses `PAWNLOGIC_HOME` when set, otherwise
+`~/.pawnlogic`, for that fallback only.
+
+Within the selected evidence directory, observations use `evidence.jsonl` and
+completed workflow records use canonical, schema-versioned JSON with
+restrictive permissions under:
+
+```text
+<evidence directory>/runs/<run-id>.json
+```
+
+`/security evidence list` shows run summaries. `/security evidence export
+<run-id>` writes the selected canonical run record to the active output sink.
+Export accepts only a fixed-format run ID; it does not accept an output path
+and does not create an evidence archive.
+
+## Trust boundaries
+
+- No scope, an expired scope, an excluded or unmatched target, an unauthorized
+  port, or an exhausted budget fails closed.
+- Active work requires explicit active authorization and ports.
+- Loopback, private, link-local, metadata, and credential-bearing targets are
+  still governed by PawnLogic Network Policy.
+- The package does not silently download scanners, wordlists, browsers,
+  containers, or system packages.
+- The optional child-process adapter is disabled by default. When explicitly
+  configured by an integrator, it executes a literal argument vector without a
+  shell only after the host Operation Policy allows it; current workflows do
+  not call it.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -m ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pawnlogic_security-0.1.0/README.md

@@ -0,0 +1,203 @@
+# pawnlogic-security
+
+Scope-gated security tooling for the [PawnLogic](https://github.com/john0123412/PawnLogic)
+agent host, distributed independently of the core package.
+
+Installing this package does not authorize or enable it. The PawnLogic
+Extension stays disabled until an operator explicitly enables it, and its
+network tools remain unavailable until a valid Engagement Scope is active.
+
+## Status
+
+The current public release is `0.1.0`, published independently of the
+PawnLogic core package. It implements:
+
+- a versioned Engagement Scope file with exact hosts, CIDRs, exclusions,
+  explicit ports, passive/active actions, expiry, and request, concurrency, and
+  duration budgets
+- scope-gated passive DNS, TLS, HTTP-header, and technology reconnaissance
+- scope-gated bounded active port discovery
+- append-only redacted evidence records
+- two built-in, versioned workflows shared by `pawn-security` and `/security`
+- reproducible workflow plans and versioned local run records
+- an optional, default-disabled JSON child-process adapter with Operation Policy
+  checks, bounded I/O, timeout cleanup, environment isolation, and output
+  redaction
+
+It does not implement HTTP replay, external scanner adapters, workflow YAML
+loading, CIDR expansion, exploit or destructive workflows, MCP execution, or
+an AI-generated planner. No built-in workflow invokes the optional child
+adapter.
+
+## Requirements
+
+- Python 3.10 or newer
+- `pawnlogic>=0.3,<0.4`
+
+## Install
+
+Install the published package:
+
+```bash
+python -m pip install pawnlogic-security
+```
+
+For checkout development:
+
+```bash
+python -m pip install -e .
+```
+
+Nothing is loaded merely because the distribution is installed.
+
+## Enable in PawnLogic
+
+```text
+/extension list
+/extension enable security
+/extension status security
+```
+
+The Extension contributes `/security` after enablement:
+
+```text
+/security status
+/security scope show
+/security scope set <scope-file>
+/security scope clear
+/security plan <objective>
+/security run <workflow>
+/security evidence list
+/security evidence export <run-id>
+```
+
+`/security` is an async host command and writes through the active PawnLogic
+output sink. Scope changes rebuild the complete contribution set atomically:
+the command remains present while security tools appear or disappear.
+
+Disable the Extension with:
+
+```text
+/extension disable security
+```
+
+## Engagement Scope
+
+Every operation requires an explicit, unexpired Engagement Scope. A minimal
+passive scope file looks like:
+
+```json
+{
+  "version": 1,
+  "identifier": "authorized-review",
+  "authorized_by": "security-team",
+  "reference": "CHANGE-1234",
+  "expires_at": 4102444800,
+  "targets": ["app.example.com"],
+  "exclude": [],
+  "ports": ["443"],
+  "allow_active": false,
+  "actions": ["passive"],
+  "destructive": false,
+  "max_requests": 20,
+  "max_concurrency": 1,
+  "max_duration": 300,
+  "evidence_dir": "evidence"
+}
+```
+
+Active discovery additionally requires `allow_active: true`, the `active`
+action, and explicit ports, for example `"ports": ["443", "8000-8010"]`.
+Destructive authorization is rejected because destructive workflows are not
+implemented.
+
+The passive example explicitly authorizes port `443` because TLS inspection and
+HTTPS header collection make network connections even though they do not send
+active probes.
+
+Scope is necessary but never sufficient. The host Network Policy runs after
+scope validation and may still refuse the target. Resolved addresses and
+redirect changes must remain in scope. Model-provided tool arguments cannot
+grant authorization.
+
+## Workflows
+
+The built-in workflow manifests have schema version `1` and their own workflow
+version:
+
+- `passive-recon` runs `security_passive_recon`
+- `active-discovery` runs `security_active_discovery`
+
+Both direct and hosted commands call the same `WorkflowRunner` interface:
+
+```bash
+pawn-security scope validate <scope-file>
+pawn-security run passive-recon --scope <scope-file>
+```
+
+```text
+/security run passive-recon
+```
+
+The runner sorts explicit host targets and runs one workflow target at a time.
+The execution adapters consume the engagement-wide request budget before
+individual network requests. The runner does not expand a CIDR into hosts.
+`active-discovery` additionally requires an active scope; port-scan concurrency
+remains bounded by the scope.
+
+`/security plan <objective>` is deliberately conservative. It returns a
+deterministic suggestion to begin with `passive-recon`, reports that execution
+has not started, and performs no network work.
+
+## Evidence
+
+When the active scope sets `evidence_dir`, tool observations and run records
+are written there. A relative `evidence_dir` is resolved from the directory
+containing the scope file. Without `evidence_dir`, they fall back to:
+
+```text
+<runtime home>/security/evidence.jsonl
+```
+
+The direct command uses `PAWNLOGIC_HOME` when set, otherwise
+`~/.pawnlogic`, for that fallback only.
+
+Within the selected evidence directory, observations use `evidence.jsonl` and
+completed workflow records use canonical, schema-versioned JSON with
+restrictive permissions under:
+
+```text
+<evidence directory>/runs/<run-id>.json
+```
+
+`/security evidence list` shows run summaries. `/security evidence export
+<run-id>` writes the selected canonical run record to the active output sink.
+Export accepts only a fixed-format run ID; it does not accept an output path
+and does not create an evidence archive.
+
+## Trust boundaries
+
+- No scope, an expired scope, an excluded or unmatched target, an unauthorized
+  port, or an exhausted budget fails closed.
+- Active work requires explicit active authorization and ports.
+- Loopback, private, link-local, metadata, and credential-bearing targets are
+  still governed by PawnLogic Network Policy.
+- The package does not silently download scanners, wordlists, browsers,
+  containers, or system packages.
+- The optional child-process adapter is disabled by default. When explicitly
+  configured by an integrator, it executes a literal argument vector without a
+  shell only after the host Operation Policy allows it; current workflows do
+  not call it.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -m ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pawnlogic_security-0.1.0/pawnlogic_security/__init__.py

@@ -0,0 +1,5 @@
+"""Scope-gated security tooling distributed independently of PawnLogic core."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]