Metadata-Version: 2.4
Name: oryon-pentest
Version: 0.1.0
Summary: Autonomous pentesting runtime with explicit tool contracts and auditable evidence.
Author: Guayamose
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/Guayamose/Oryon-Pentest#readme
Project-URL: Issues, https://github.com/Guayamose/Oryon-Pentest/issues
Project-URL: Repository, https://github.com/Guayamose/Oryon-Pentest
Keywords: agent,cybersecurity,pentesting,security-testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: tree-sitter<0.26,>=0.25
Requires-Dist: tree-sitter-bash<0.26,>=0.25
Provides-Extra: bedrock
Requires-Dist: boto3<2,>=1.43; extra == "bedrock"
Requires-Dist: botocore[crt]<2,>=1.43; extra == "bedrock"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-cov<8,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Guayamose/Oryon-Pentest/master/assets/oryon/Imagotipo-White-Blue-gradient.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Guayamose/Oryon-Pentest/master/assets/oryon/Imagotipo-OffBlack-Blue-gradient.svg">
  <img src="https://raw.githubusercontent.com/Guayamose/Oryon-Pentest/master/assets/oryon/Imagotipo-OffBlack-Blue-gradient.svg" width="520" alt="Oryon">
</picture>

# Oryon Pentest

**Autonomous pentesting for authorized security assessments.**

A frontier model drives the investigation. A deterministic runtime owns scope,
tools, evidence, persistence and proof.

[![CI](https://github.com/Guayamose/Oryon-Pentest/actions/workflows/ci.yml/badge.svg)](https://github.com/Guayamose/Oryon-Pentest/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12+-3776AB?logo=python&logoColor=white)](https://github.com/Guayamose/Oryon-Pentest/blob/master/pyproject.toml)
[![Node 20+](https://img.shields.io/badge/Node.js-20+-339933?logo=nodedotjs&logoColor=white)](https://github.com/Guayamose/Oryon-Pentest/blob/master/event_console/package.json)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-006BFF.svg)](https://github.com/Guayamose/Oryon-Pentest/blob/master/LICENSE)

[Quick start](#quick-start) · [Installation](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/installation.md) · [Operations](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/operations.md) · [Architecture](#architecture) · [Documentation](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/README.md) · [Benchmark](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/benchmarking.md)

</div>

> [!WARNING]
> Use Oryon Pentest only against systems you own or are explicitly authorized
> to test. You are responsible for defining and respecting the engagement scope.

## What Oryon is

Oryon is a long-horizon pentesting agent, not a fixed scanner pipeline. The
model can map a target, form hypotheses, execute tools, follow evidence and
continue across multiple attack paths. Strategy stays model-driven while facts
and safety-critical decisions stay outside the model.

| Model owns | Runtime owns |
| --- | --- |
| Hypotheses, prioritization and next actions | Authorization, scope and credential provenance |
| Adapting strategy from observed results | Tool contracts and execution lifecycle |
| Deciding which open paths deserve more work | Artifact storage and causal evidence references |
| Proposing findings and mission closure | Persistent state, replay and proof gates |

This separation keeps Oryon open-ended without making its factual state or
authorization depend on prompt compliance.

## Live mission console

<p align="center">
  <img src="https://raw.githubusercontent.com/Guayamose/Oryon-Pentest/master/assets/terminal-replay.png" width="980" alt="Oryon Pentest replaying a persisted assessment in the real terminal console">
</p>

<p align="center"><sub>Real terminal capture of a persisted run. The console renders runtime-emitted JSONL events; no synthetic preview data is used.</sub></p>

The console shows the active objective, current move, tool/evidence counts,
mission timeline and replay state. Runs remain usable without the console
through the canonical non-interactive Python entrypoint.

## Architecture

```mermaid
flowchart LR
    O[Operator brief] --> C[Mission console]
    C --> R[Canonical Python runner]
    R --> A[Agent runtime]
    A <--> P[Model provider]
    A --> G[Policy and proof gates]
    A --> T[Tool registry]
    T --> X[Authorized target]
    T --> E[Artifacts and evidence]
    E --> S[Persistent run state]
    S --> A
    A --> J[Mission events JSONL]
    J --> C
```

The runtime exposes the same tool contract to Bedrock, OpenAI and Vertex:

```text
bash · http · read · search · write · list · web_search · web_fetch
```

Provider adapters translate model APIs only. They do not rank attack paths,
weaken policy, invent findings or add benchmark-specific behavior. The console
is also presentation-only: authoritative state lives in the Python runtime.

## Quick start

Requirements:

- Python 3.12 or newer;
- Node.js 20 or newer for the mission console;
- Docker for the default isolated shell backend;
- credentials for one supported model provider.

```bash
git clone https://github.com/Guayamose/Oryon-Pentest.git
cd Oryon-Pentest

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[bedrock,dev]"
npm --prefix event_console ci
.venv/bin/oryon-pentest-build-sandbox --verify
cp .env.example .env
```

Configure one provider in `.env`, then start the interactive console:

```bash
./oryon-pentest
```

Start a non-interactive authorized assessment:

```bash
.venv/bin/oryon-pentest-agent https://target.example \
  --provider bedrock \
  --model eu.anthropic.claude-opus-4-6-v1 \
  --instructions "Authorized assessment of this origin."
```

Resume or replay a persisted run:

```bash
./oryon-pentest --resume-run-id 'run:...'
./oryon-pentest --replay --resume-run-id 'run:...'
```

See the [operations guide](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/operations.md)
for every CLI option, resume semantics, console commands, run files and
troubleshooting.

## Providers

| Provider | Required configuration | Setup |
| --- | --- | --- |
| Amazon Bedrock | AWS credentials, `BEDROCK_REGION`, `BEDROCK_MODEL_ID` | [Bedrock](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/providers/bedrock.md) |
| OpenAI | `OPENAI_API_KEY`, `OPENAI_MODEL` | [OpenAI](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/providers/openai.md) |
| Vertex / Gemini | `VERTEX_API_KEY`, `VERTEX_MODEL` | [Vertex](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/providers/vertex.md) |

Model identifiers are passed through exactly. Friendly aliases are a changing
console convenience rather than a compatibility promise; custom provider IDs
remain accepted. Presets never alter persisted or resumed runs. See
[model selection](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/models.md).

## Persistent, causal runs

Every mission is stored under `runs/<run-id>/`. The important records include:

| Record | Purpose |
| --- | --- |
| `run_state.json` | Compact checkpoint of current resumable facts |
| `run_events.jsonl` | Canonical append-only causal sequence |
| `mission_events.jsonl` | Read-only console projection of real runtime events |
| `llm_call_events.jsonl` | Provider attempts, model metadata, timing and status |
| `artifact_index.json` | Addressable outputs produced by tools |
| `proof_verification_events.jsonl` | Runtime decisions about claimed proof |

Evidence is referenced by stable artifact/evidence IDs instead of being reduced
to an unverifiable narrative. Replay reads persisted metadata, so changing the
current `.env` cannot rewrite the apparent history of an old run.

`run_state.json` is a compact checkpoint of current resumable facts. Exact
conversation, tool, policy, proof and model-call history lives once in its
append-only logs and is rehydrated on resume. A pending checkpoint journal
recovers an event that became durable immediately before an interruption.
Current facts come from the checkpoint; histories come from their named logs,
so resume never chooses between two copies of the same history.

## Distribution

The repository contains two explicit packages:

- `oryon-pentest`, the Python runtime and non-visual `oryon-pentest-agent` entrypoint;
- `@oryon/pentest-console`, the Node.js terminal UI and `oryon-pentest` entrypoint.

The console invokes the installed Python package from the current environment.
The repository launcher builds and runs that same publishable console output;
it does not use a separate runtime implementation.

Source, PyPI and npm installation paths are documented in the
[installation guide](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/installation.md).

## Verification

```bash
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
npm --prefix event_console run typecheck
npm --prefix event_console test
npm --prefix event_console run build
npm pack ./event_console --dry-run
.venv/bin/python -m build
git diff --check
```

The repository also checks import boundaries, semantic-enforcement rules,
provider protocol continuity, causal evidence, tool behavior and golden runs.

## Benchmark

Oryon Pentest scored **29/40 (72.5%)** on one CVE-Bench v2.1.0 zero-day run
using Claude Opus 4.6 through Bedrock. This is a Pass@1 result, not an official
leaderboard submission, and the interaction budget was larger than the
published default harness. The full methodology and limitations are in
[the benchmark report](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/benchmarking.md).

The benchmark is external test infrastructure. It is not imported by the
product and does not influence runtime strategy.

## Project status

Oryon Pentest is alpha software. Interfaces and persisted state may change
before 1.0. Changes must remain explicit, tested and auditable.

- Read the [documentation map](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/README.md).
- Review the [security policy](https://github.com/Guayamose/Oryon-Pentest/blob/master/SECURITY.md) before reporting a vulnerability.
- See [CONTRIBUTING.md](https://github.com/Guayamose/Oryon-Pentest/blob/master/CONTRIBUTING.md) for development and validation rules.
- Read the [code of conduct](https://github.com/Guayamose/Oryon-Pentest/blob/master/CODE_OF_CONDUCT.md) before participating.
- Follow [releases and versioning](https://github.com/Guayamose/Oryon-Pentest/blob/master/docs/releases.md) for package compatibility.
- Review the [changelog](https://github.com/Guayamose/Oryon-Pentest/blob/master/CHANGELOG.md) before upgrading.

Licensed under the [Apache License 2.0](https://github.com/Guayamose/Oryon-Pentest/blob/master/LICENSE).
