pretext-sim 0.3.2__py3-none-any.whl

pretext/render.py

@@ -0,0 +1,247 @@
+"""Rich rendering and plain-text export of simulations."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from rich.console import Console, Group, RenderableType
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.table import Table
+from rich.text import Text
+
+from .models import Profile, Settings, Simulation
+
+DISCLAIMER = (
+    "Fictional exercise. Domains, names, and systems are invented. "
+    "Use against authorized targets only."
+)
+DIFFICULTY_LABELS = {
+    1: "broad, high volume",
+    2: "lightly targeted",
+    3: "targeted",
+    4: "researched, multi-step",
+    5: "bespoke, multi-day",
+}
+
+
+def console(*, no_color: bool = False, width: int | None = None, stderr: bool = False) -> Console:
+    return Console(
+        no_color=no_color,
+        width=width,
+        highlight=False,
+        soft_wrap=False,
+        stderr=stderr,
+    )
+
+
+def _difficulty(value: int) -> Text:
+    filled = "●" * value + "○" * (5 - value)
+    label = DIFFICULTY_LABELS.get(value, "targeted")
+    return Text(f"{filled}  {value}/5 · {label}", style="magenta")
+
+
+SECTIONS = ("pretext", "opening", "escalation", "red_flags")
+
+
+def render_simulation(
+    simulation: Simulation,
+    profile: Profile,
+    out: Console,
+    *,
+    sections: tuple[str, ...] = SECTIONS,
+) -> None:
+    header = Table.grid(padding=(0, 2))
+    header.add_column(style="bold cyan", justify="right")
+    header.add_column()
+    header.add_row("Persona", profile.name)
+    header.add_row("Role", f"{profile.role} · {profile.company}")
+    header.add_row("Style", profile.communication_style)
+    header.add_row("Difficulty", _difficulty(simulation.difficulty))
+    if simulation.objective:
+        header.add_row("Objective", simulation.objective)
+
+    out.print(
+        Panel(
+            header,
+            title="[bold]Simulation[/bold]",
+            subtitle=f"[dim]{profile.name}[/dim]",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+
+    if "pretext" in sections:
+        out.print(Rule("[bold]Pretext narrative[/bold]", style="cyan"))
+        out.print(Markdown(simulation.pretext))
+
+    if "opening" not in sections:
+        return _render_tail(simulation, out, sections)
+
+    message_body: list[RenderableType] = []
+    if simulation.subject_line:
+        message_body.append(Text(f"Subject: {simulation.subject_line}", style="bold"))
+        message_body.append(Text(""))
+    message_body.append(Markdown(simulation.opening_message))
+    out.print(
+        Panel(
+            Group(*message_body),
+            title="[bold]Opening message[/bold]",
+            border_style="green",
+            expand=False,
+        )
+    )
+
+    _render_tail(simulation, out, sections)
+
+
+def _render_tail(simulation: Simulation, out: Console, sections: tuple[str, ...]) -> None:
+    if "escalation" in sections:
+        _render_escalation(simulation, out)
+    if "red_flags" in sections:
+        _render_red_flags(simulation, out)
+    out.print(Rule(style="dim"))
+    out.print(Text(DISCLAIMER, style="dim italic"))
+
+
+def _render_escalation(simulation: Simulation, out: Console) -> None:
+    out.print(Rule("[bold]Escalation path[/bold]", style="cyan"))
+    steps = Table(show_header=True, header_style="bold cyan", expand=True, box=None)
+    steps.add_column("#", width=3, justify="right")
+    steps.add_column("Channel", width=11)
+    steps.add_column("Action", ratio=3)
+    steps.add_column("Goal", ratio=2)
+    for step in simulation.escalation_path:
+        steps.add_row(
+            str(step.stage),
+            Text(step.channel.value, style="yellow"),
+            Text(step.action),
+            Text(step.goal, style="dim"),
+        )
+        if step.artifact:
+            steps.add_row("", "", Text(f"↳ {step.artifact}", style="dim italic"), "")
+    out.print(steps)
+
+
+def _render_red_flags(simulation: Simulation, out: Console) -> None:
+    out.print(Rule("[bold]Red flags for defenders[/bold]", style="cyan"))
+    for index, flag in enumerate(simulation.red_flags, start=1):
+        out.print(
+            Panel(
+                Group(
+                    Markdown(flag.why_it_matters),
+                    Text(""),
+                    Text(f"Defender action: {flag.defender_action}", style="bold green"),
+                ),
+                title=f"[bold]{index}. {flag.title}[/bold]",
+                border_style="red",
+                expand=False,
+            )
+        )
+
+
+def render_settings(settings: Settings, out: Console) -> None:
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="bold cyan", justify="right")
+    table.add_column()
+    table.add_row("Endpoint", settings.endpoint)
+    table.add_row("Model", settings.model)
+    table.add_row("Key", "set" if settings.api_key else "[red]missing[/red]")
+    table.add_row("Temperature", f"{settings.temperature:g}")
+    table.add_row("Max tokens", str(settings.max_tokens))
+    table.add_row("Timeout", f"{settings.timeout:g}s")
+    table.add_row("Retries", str(settings.retries))
+    if settings.seed is not None:
+        table.add_row("Seed", str(settings.seed))
+    out.print(
+        Panel(
+            table,
+            title="[bold]Resolved configuration[/bold]",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+
+
+def render_profile(profile: Profile, out: Console) -> None:
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="bold cyan", justify="right")
+    table.add_column()
+    for label, value in (
+        ("Name", profile.name),
+        ("Role", profile.role),
+        ("Company", profile.company),
+        ("Style", profile.communication_style),
+        ("Department", profile.department),
+        ("Tenure", profile.tenure),
+        ("Reports to", profile.reports_to),
+        ("Systems", ", ".join(profile.systems) or None),
+        ("Notes", profile.notes),
+    ):
+        if value:
+            table.add_row(label, value)
+    out.print(Panel(table, title="[bold]Profile OK[/bold]", border_style="green", expand=False))
+
+
+def to_markdown(
+    simulation: Simulation,
+    profile: Profile,
+    *,
+    sections: tuple[str, ...] = SECTIONS,
+) -> str:
+    lines = [
+        f"# Social-engineering simulation: {profile.name}",
+        "",
+        f"- **Role:** {profile.role} at {profile.company}",
+        f"- **Communication style:** {profile.communication_style}",
+        f"- **Difficulty:** {simulation.difficulty}/5",
+    ]
+    if simulation.objective:
+        lines.append(f"- **Objective:** {simulation.objective}")
+    if "pretext" in sections:
+        lines += ["", "## Pretext narrative", "", simulation.pretext]
+    if "opening" in sections:
+        lines += ["", "## Opening message", ""]
+        if simulation.subject_line:
+            lines += [f"**Subject:** {simulation.subject_line}", ""]
+        lines += [simulation.opening_message]
+    if "escalation" in sections:
+        lines += ["", "## Escalation path", ""]
+        for step in simulation.escalation_path:
+            lines.append(
+                f"{step.stage}. **{step.channel.value}** · {step.action} _(goal: {step.goal})_"
+            )
+            if step.artifact:
+                lines.append(f"   - Artifact: {step.artifact}")
+    if "red_flags" in sections:
+        lines += ["", "## Red flags for defenders", ""]
+        for index, flag in enumerate(simulation.red_flags, start=1):
+            lines += [
+                f"{index}. **{flag.title}**",
+                f"   - Why it matters: {flag.why_it_matters}",
+                f"   - Defender action: {flag.defender_action}",
+            ]
+    lines += ["", "---", "", f"_{DISCLAIMER}_", ""]
+    return "\n".join(lines)
+
+
+def to_json(
+    simulation: Simulation,
+    profile: Profile,
+    *,
+    sections: tuple[str, ...] = SECTIONS,
+) -> str:
+    payload: dict[str, object] = {
+        "profile": profile.model_dump(mode="json"),
+        "simulation": simulation.model_dump(mode="json"),
+        "sections": list(sections),
+        "disclaimer": DISCLAIMER,
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def render_warnings(warnings: Iterable[str], out: Console) -> None:
+    for warning in warnings:
+        out.print(Text(f"! {warning}", style="yellow"))

pretext_sim-0.3.2.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.5
+Name: pretext-sim
+Version: 0.3.2
+Summary: Generate labeled social-engineering simulations for security training
+Author: pretext contributors
+License: MIT
+License-File: LICENSE
+Keywords: cli,phishing,red-team,security,security-awareness,training
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# pretext
+
+**Turn a one-page persona into a runnable social-engineering exercise.**
+
+Narrative, opening message, escalation path, and the red flags defenders should
+have caught, generated, validated, then rendered where you need it.
+
+[![ci](https://github.com/sjdsjadjajdjsa/pretext/actions/workflows/ci.yml/badge.svg)](https://github.com/sjdsjadjajdjsa/pretext/actions/workflows/ci.yml)
+![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)
+![license](https://img.shields.io/badge/license-MIT-blue.svg)
+
+<img src="docs/demo.png" alt="pretext rendering a simulation in the terminal" width="820">
+
+</div>
+
+> **Authorized training only.** Everything produced is a fictional exercise.
+> Domains, names, and systems are invented unless you say otherwise. pretext never
+> sends anything to a target; it writes the material and the analysis. Run an
+> exercise against your own people only after your security team agrees to it, and
+> check the lures before sending.
+
+## Why
+
+Security-awareness decks are generic ("you receive an email with a typo"), so staff
+learn to spot a template rather than a technique. A useful exercise is grounded in
+one role at one company: what that person controls, who they trust, and what an
+operator would do next.
+
+Doing that by hand costs an afternoon per persona. `pretext` takes a YAML profile
+and produces the exercise in one call, defender's side included, so training value
+does not depend on whoever wrote the scenario remembering to add it.
+
+## What you get
+
+| Section | Content |
+| ------- | ------- |
+| Pretext narrative | The operation, attacker-side: harvested detail, forged artifact, why contact lands today |
+| Opening message | Usable verbatim, in the sender's voice, carrying the sending address and one lure |
+| Escalation path | 3-6 stages across channels, each handing over a new prop or introducing a new person |
+| Red flags | Observable tells tied to this exercise, each with a defender action, including one only clear in hindsight |
+
+`docs/running-an-exercise.md` covers authorization, delivery, scoring and the
+debrief, which is the half the tool cannot do.
+
+Every output carries a disclaimer. [`sample-output.md`](sample-output.md) is a
+complete Markdown export; [`docs/demo.png`](docs/demo.png) is the terminal view.
+
+## Install
+
+```sh
+uvx pretext-sim generate persona.yaml     # no install
+pipx install pretext-sim                  # or a permanent command
+```
+
+Python 3.10+. The distribution is `pretext-sim`; the command is `pretext`. For the
+source tree: `uv sync --extra dev` then `uv run pretext`.
+
+## Quickstart
+
+```sh
+pretext example -o persona.yaml            # fictional profile to edit
+pretext validate persona.yaml              # schema check, no API call
+pretext generate persona.yaml --dry-run    # resolved config + exact prompt, no call
+pretext generate persona.yaml -f markdown -o exercise.md
+```
+
+Point it at any OpenAI-compatible chat completions endpoint with a flag, env var, or
+`.env`:
+
+```sh
+export PRETEXT_API_KEY=sk-...
+export PRETEXT_BASE_URL=http://localhost:11434/v1   # local proxy, if you prefer
+export PRETEXT_MODEL=gpt-oss:20b
+```
+
+Or name a known host instead of the URL: `--provider openai|openrouter|venice|ollama|lmstudio`
+(`PRETEXT_PROVIDER`), which fills the base URL. An explicit `--base-url` wins. Local
+providers need no key.
+
+`pretext config` shows what resolves, with the key masked.
+
+## Profile
+
+Only four fields are required (`name`, `role`, `company`, `communication_style`).
+The rest sharpen the result.
+
+```yaml
+name: Dana Iyer
+role: Senior Payroll Analyst
+company: Northwind Logistics
+communication_style: Brisk and formal, mixes payroll shorthand with chatty asides
+department: People Operations
+tenure: 3 months
+reports_to: Marta Kwan
+systems: [Workday, the payroll mailbox]
+notes: New enough to the team to be unsure of process.
+```
+
+Optional: `department`, `tenure`, `reports_to`, `systems`, `notes`. Unknown keys are
+rejected so typos surface early. Fixture personas live in
+[`tests/fixtures/profiles`](tests/fixtures/profiles).
+
+## Command reference
+
+| Command | Purpose |
+| ------- | ------- |
+| `generate PROFILE` | Produce one exercise |
+| `validate PROFILE` | Validate without calling the API |
+| `example` | Print the bundled fictional profile |
+| `batch DIR` | One exercise per `*.yaml` in DIR (files starting `_` are skipped) |
+| `doctor` | Probe the endpoint: config, TLS, reachability, model, JSON mode |
+| `schema` | Print the JSON Schema model output must satisfy (`--all` adds the profile) |
+| `config` | Show resolved settings, key masked |
+
+Flags on `generate`:
+
+| Flag | Effect |
+| ---- | ------ |
+| `--channel` | Force the opening channel (email, phone, sms, chat, in_person, linkedin) |
+| `--extra` | Extra direction for the model |
+| `--format` | `rich` (default), `markdown`, `json` |
+| `--out` | Write to a file; plain text unless a format is chosen |
+| `--sections` | Render only some of `pretext,opening,escalation,red_flags` |
+| `--from-file` | Replay a saved response; no API call, no key |
+| `--dry-run` | Print resolved config and prompt, send nothing; `--out` writes the prompt |
+| `--usage` | Token counts on stderr |
+| `--base-url`, `--model`, `--api-key` | Override endpoint settings |
+| `--temperature`, `--max-tokens`, `--timeout`, `--retries`, `--seed` | Sampling and transport |
+| `--no-color` | Plain terminal output |
+
+Exit codes: `0` success, `1` bad profile/config/API/schema failure, `2` usage error,
+`130` interrupted.
+
+`--from-file` accepts a `--format json` export, a bare simulation object, or a raw
+chat completion body, so formatting work stays free and offline.
+
+## Diagnose first
+
+```sh
+pretext doctor              # config, TLS, /models, JSON mode
+pretext doctor --full       # also runs one real simulation through the schema
+```
+
+Exits `1` on any failure and prints the provider's own error, so a wrong model name
+or a blocked key shows up before a batch run wastes retries.
+
+## Batch runs
+
+For a whole team, point `batch` at a directory and it writes one file per profile,
+continuing past failures:
+
+```sh
+pretext batch profiles/ --out-dir packet/ --format markdown
+```
+
+Progress and a `wrote 7/9` summary go to stderr, the failure reasons are listed, and
+the exit code is `1` if anything failed. Endpoint flags are the same as `generate`;
+`--sections`, `--format` and `--usage` apply to the run as a whole.
+
+## Configuration
+
+First hit wins:
+
+1. Flags (`--base-url`, `--model`, `--api-key`, `--provider`)
+2. Environment: the same names under `PRETEXT_` (`PRETEXT_API_KEY`, `PRETEXT_MODEL`, ...)
+3. `.env` in the working directory
+4. `OPENAI_API_KEY` for the key, then `https://api.openai.com/v1` and `gpt-4o-mini`
+
+The key is never printed and never written to output.
+
+## How it works
+
+```
+profile.yaml ─> Profile ─> prompt ─> POST /chat/completions ─> extract JSON
+                                                                    │
+     rich | markdown | json  <─ render <─ validate <────────────────┘
+```
+
+Model output is untrusted. It is parsed out of fences or prose, validated against a
+strict pydantic schema, and only then rendered. Escalation stages must run 1..n with
+no gaps, `red_flags` needs at least two entries, and unknown keys are rejected, so a
+loose model fails loudly instead of producing a half-filled exercise.
+
+Diagnostics go to stderr, keeping stdout pipeable: `pretext generate p.yaml -f json | jq`.
+
+## Releasing
+
+Tagging `vX.Y.Z` runs `release.yml`: it checks the tag against `__version__`, gates
+on lint, format, types and tests, builds, then publishes a release whose notes come
+from `CHANGELOG.md`. Version bumps and changelog sections land before the tag.
+
+## Development
+
+```sh
+uv run pytest --cov=pretext # offline: MockTransport and a stubbed client
+uv run ruff check src tests
+uv run mypy
+```
+
+The suite needs no key. `conftest.py` chdirs each test into a temp directory so your
+own `.env` cannot leak in, and pins the terminal width so Rich reflow stays stable.
+
+`scripts/capture_corpus.py` refreshes `tests/fixtures/corpus`, which
+`tests/test_corpus.py` checks for structural promises.
+
+`AGENTS.md` documents the layout, the hardening rules, and the traps for agent
+contributors. `CONTRIBUTING.md` covers process; security reports follow `SECURITY.md`.
+
+## Status
+
+Pre-1.0: the CLI surface and JSON schema can still move between minor versions;
+`CHANGELOG.md` records what changed.
+
+Output has been checked against gpt-4o-mini, gemini-2.5-flash, claude-haiku-4.5 and
+llama-3.3-70b through OpenRouter, plus venice-uncensored-1-2 and
+qwen3-235b-a22b-instruct on Venice. All six held the JSON contract and used distinct
+channels. Weak models will still need prompt tuning, and the suite covers the
+pipeline rather than any one model's prose.
+
+Not planned: delivery to targets, click tracking, an SMTP client. pretext writes the
+exercise; sending stays your job.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

pretext_sim-0.3.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+pretext/__init__.py,sha256=b2SsiOk-VyOt7PxcuorCfQ7JSP5_geKBwAbSlWbyQfk,590
+pretext/cli.py,sha256=wp07Fg_DkeFIHnNfkbtfHbF0NWQAKGYH0_enK9WFZZg,20199
+pretext/client.py,sha256=sNFeBZLUzKg5AcVrwGscBE6lwS6e73e1Kbb12164Yrw,8143
+pretext/models.py,sha256=tmjPrqbswtxoybeOZQ9mI1W90gl9SdYA6QeuPvTu-5s,10474
+pretext/prompt.py,sha256=yQ49GF3F9jD_-xW_FiHCfW04Aq6bWNnVcHxVPztdb30,5559
+pretext/render.py,sha256=IYT6h6mO4TWKYJBHAOMjWAS1IqcFH6upHHZqoHL0730,8302
+pretext/data/example-profile.yaml,sha256=4Lspy5Wh0NH4XMUAo05Pd0RHbBWPxfVoVY5svqMd4Ac,419
+pretext_sim-0.3.2.dist-info/METADATA,sha256=uWhfeJOP6S_dRou4SVoy22OfdvVpJDbzWZV6yhOFbKE,10195
+pretext_sim-0.3.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pretext_sim-0.3.2.dist-info/entry_points.txt,sha256=hbPonwsPJ7IZoLDhG_VEcLa2kvWNe7ZYpE9pjCvz4L8,44
+pretext_sim-0.3.2.dist-info/licenses/LICENSE,sha256=ax7hQ3Ou5brcygpbq86G4ndIiwolij1Fhs1RHVBdfZ0,1077
+pretext_sim-0.3.2.dist-info/RECORD,,

pretext_sim-0.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pretext_sim-0.3.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pretext = pretext.cli:app

pretext_sim-0.3.2.dist-info/licenses/LICENSE

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