praetorian-cli 2.4.8__tar.gz → 2.6.0__tar.gz

{praetorian_cli-2.4.8/praetorian_cli.egg-info → praetorian_cli-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praetorian-cli
-Version: 2.4.8
+Version: 2.6.0
 Summary: For interacting with the Guard API
 Home-page: https://github.com/praetorian-inc/praetorian-cli
 Author: Praetorian
@@ -14,17 +14,20 @@ License-File: LICENSE
 Requires-Dist: click>=8.1.7
 Requires-Dist: boto3>=1.34.0
 Requires-Dist: requests>=2.31.0
+Requires-Dist: truststore>=0.10.0
 Requires-Dist: pytest>=8.0.2
 Requires-Dist: mcp>=1.12.2
 Requires-Dist: anyio>=3.0.0
+Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: textual>=0.47.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: prompt_toolkit>=3.0.0
+Requires-Dist: websocket-client>=1.0.0
 Dynamic: license-file
 
 # Praetorian CLI and SDK
 
-[![Python Version](https://img.shields.io/badge/Python-v3.9+-blue)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/Python-v3.10+-blue)](https://www.python.org/)
 [![pip Version](https://img.shields.io/badge/pip-v23.0+-blue)](https://pypi.org/project/praetorian-cli/)
 [![License](https://img.shields.io/badge/License-MIT-007EC6.svg)](LICENSE)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20covenant-2.1-007EC6.svg)](CODE_OF_CONDUCT.md)
@@ -44,6 +47,12 @@ Dynamic: license-file
     - [Signing up](#signing-up)
     - [Authentication](#authentication)
 - [Using the CLI](#using-the-cli)
+    - [Aegis v2 endpoints](#aegis-v2-endpoints)
+    - [AI Hunts](#ai-hunts)
+    - [Aegis endpoint network policy](#aegis-endpoint-network-policy)
+    - [Engineer VMs](#engineer-vms)
+    - [File upload partitions](#file-upload-partitions)
+    - [Update checks](#update-checks)
 - [Operators](#operators)
     - [Interactive Console](#interactive-console)
     - [Install local security tools (optional)](#install-local-security-tools-optional)
@@ -52,6 +61,7 @@ Dynamic: license-file
 - [Developers](#developers)
     - [SDK](#sdk)
     - [Developing external scripts](#developing-external-scripts)
+    - [Running the test suite](#running-the-test-suite)
     - [Contributing](#contributing)
     - [Support](#support)
     - [License](#license)
@@ -69,7 +79,7 @@ offensive security platform.
 
 ## Prerequisites
 
-- Python v3.9 or above
+- Python v3.10 or above
 - pip v23.0 or above
 
 ## Installation
@@ -80,7 +90,7 @@ Install the Python package:
 pip install praetorian-cli
 ```
 
-### Install from source (for console branch features)
+### Install from source
 
 ```zsh
 git clone https://github.com/praetorian-inc/praetorian-cli.git
@@ -146,6 +156,10 @@ export PRAETORIAN_CLI_API_KEY_ID=your-api-key-id-here
 export PRAETORIAN_CLI_API_KEY_SECRET=your-api-key-here
 ```
 
+The backend API URL and the Cognito emulator endpoint (`aws_endpoint_url`)
+must be HTTPS; the CLI refuses to send credentials over plaintext HTTP. For local development against a loopback endpoint (`localhost`,
+`127.0.0.1`, `::1`), set `PRAETORIAN_CLI_ALLOW_HTTP_LOOPBACK=1`.
+
 For more advanced configuration options or managing access in SSO organizations see
 [the documentation on configuration](https://github.com/praetorian-inc/praetorian-cli/blob/main/docs/configure.md).
 
@@ -174,6 +188,185 @@ To get detailed information about a specific asset, run:
 guard --account guard+example@praetorian.com get asset <ASSET_KEY>
 ```
 
+## Aegis v2 endpoints
+
+List Aegis endpoints or open the interactive endpoint console:
+
+```zsh
+guard aegis list --details
+guard aegis
+```
+
+Aegis v2 support includes durable online/offline inventory, enrollment approval,
+endpoint-compatible capability execution, Linux user and Cloudflare tunnel
+management and status diagnostics, endpoint-bound Hunts, host egress policy,
+verified artifact downloads, and explicit session/task/operation cancellation.
+
+```zsh
+guard aegis enrollment inspect <USER_CODE>
+guard aegis enrollment approve <USER_CODE>
+guard agent endpoint status <CONVERSATION_ID>
+```
+
+See [Aegis endpoints](docs/aegis.md) for enrollment, interactive commands,
+endpoint execution, tunnels, users, and policy management.
+
+## AI Hunts
+
+Launch Hunts across External, Internal, Cloud, Web Application, and LLM Application surfaces:
+
+```zsh
+guard hunt launch
+guard hunt launch --scope-mode specific --scope example.com --yes
+guard hunt launch --internal --endpoint <ENDPOINT_ID> \
+  --scope 10.20.30.0/24 --confirm-endpoint --yes
+```
+
+Use `guard hunt open <HUNT_ID>` for the unified Overview, Vulnerabilities,
+Workflow, Log, Memory, Chat, and Approvals interface. Static commands provide
+findings/evidence, finalized logs, memory CRUD, live chat and steering,
+interactions, workflow status, projected cost, and pause/resume/stop/delete
+lifecycle controls.
+
+See [AI Hunts](docs/hunts.md) for launch options, scoped credentials, keyboard
+controls, human-in-the-loop (HITL) approvals, and scriptable commands.
+
+## Aegis endpoint network policy
+
+Aegis v2 endpoint policies restrict egress from every active and future
+workload on an endpoint, including agentic Hunt workloads. View the desired and
+applied revisions, protected gateway/DNS connectivity, built-in rules, and
+custom rules with:
+
+```zsh
+guard aegis network-policy show <ENDPOINT_ID>
+```
+
+Add address-wide or TCP-port-specific denies using canonical IP addresses or CIDRs:
+
+```zsh
+guard aegis network-policy deny add <ENDPOINT_ID> 10.20.30.0/24
+guard aegis network-policy deny add <ENDPOINT_ID> 198.51.100.7 --tcp-ports 22,443
+guard aegis network-policy deny remove <ENDPOINT_ID> 1
+```
+
+The remove command accepts either the rule number shown by `show`, or an exact destination plus matching `--tcp-ports`.
+
+Guard supplies four built-in rules: `deny-unspecified`, `deny-loopback`,
+`deny-docker-api`, and `deny-control-plane`. They can be removed or restored
+explicitly:
+
+```zsh
+guard aegis network-policy default remove <ENDPOINT_ID> deny-loopback
+guard aegis network-policy default restore <ENDPOINT_ID> deny-loopback
+```
+
+Changes require confirmation unless `--yes` is supplied. Guard rejects
+policies that conflict with protected gateway or DNS connectivity, and
+revisions prevent one operator from silently overwriting another operator's
+changes.
+
+The interactive `guard aegis` interface exposes the same operations for the
+selected endpoint through `policy`, `policy default ...`, and `policy deny ...`.
+See [Host egress network policy](docs/aegis.md#host-egress-network-policy) for
+all built-in rules, safety behavior, and SDK access.
+
+## Engineer VMs
+
+Praetorian engineers can manage ad-hoc cloud workspaces with the `vm` command group:
+
+```zsh
+guard vm launch --tier general
+guard vm list
+guard vm ssh <VM_ID>
+guard vm code-server <VM_ID>
+guard vm pause <VM_ID>
+guard vm archive <VM_ID>
+guard vm revive <VM_ID>
+```
+
+SSH uses an ephemeral keypair and short-lived VM-bound certificate through
+Guard's authenticated gateway. See [Engineer VMs](docs/engineer-vms.md) for
+lifecycle, access, and security details.
+
+## File upload partitions
+
+Praetorian operators can place an upload in the Praetorian-only partition independently of its destination path:
+
+```zsh
+guard add file ./narratives.md \
+  --name "reports/narratives.md" \
+  --praetorian
+```
+
+`--praetorian` and `--public` are mutually exclusive. Guard enforces operator authorization server-side; customer users cannot write to the Praetorian partition.
+
+## Update checks
+
+After a command finishes, the CLI may check PyPI for a newer release of
+`praetorian-cli` and print a three-line upgrade advisory to stderr. The check is
+deliberately quiet and infrequent:
+
+- **At most once every 24 hours.** Every attempt is recorded at
+  `${XDG_CACHE_HOME:-~/.cache}/praetorian-cli/update-check.json` *before* the
+  request is made, so a refresh that fails — offline, DNS, timeout, a malformed
+  response — is rate-limited exactly like one that succeeds, and keeps
+  advertising the last version it did learn. Between refreshes the check reads
+  that file and makes no network request at all — as long as the record is a
+  plain file that belongs to you and is no larger than 64 KiB. Anything else at
+  that path is ignored as though it were absent, so the next invocation refreshes
+  and replaces it rather than trusting what it found. Commands that start at the
+  same instant are excluded by a marker file created beside that record, so eight
+  concurrent invocations perform one refresh rather than eight — including when
+  the request fails instantly, since the attempt is recorded before it is made.
+  A process killed mid-refresh leaves the marker behind, which defers the next
+  refresh that is actually due rather than permitting an extra one — by up to a
+  minute, or up to two if the clock steps backwards in between, since a marker
+  counts as held while its age is within a minute in *either* direction. A
+  relative `XDG_CACHE_HOME` is
+  ignored in favour of `~/.cache`, as the base-directory spec requires —
+  honouring it would put a separate cache in every working directory and so
+  defeat the limit outright. If the cache directory cannot be written at all (a
+  read-only home, one owned by another user, or one reached through a symlink),
+  the check does not run: a probe whose rate we cannot limit is one we do not
+  send.
+- **Only when a human is watching.** It is skipped unless **both** stdout and
+  stderr are a terminal, and skipped when `CI` or `GITHUB_ACTIONS` is set or
+  `TERM=dumb`. Piping either stream — `guard list assets | jq` — turns it off.
+  A script you launch by hand from your own terminal inherits your terminal, so
+  treat the opt-out below, not this gate, as the way to guarantee silence.
+- **Never in place of your command's work.** A command that raises skips the
+  check, and a group that is only delegating to a subcommand leaves the check to
+  the subcommand that does the work. A command that reports an error but still
+  exits `0` is the one case where an advisory can follow a visible error.
+- **Not on the path you run day to day.** The daily refresh passes a 2-second
+  timeout to `requests`, which bounds how long the server may go without
+  sending data — not total wall-clock, so DNS, TLS, redirects and a slow trickle
+  are outside it. Ordinary failures are swallowed and cannot change your exit
+  code; `Ctrl-C` and process-control exceptions raised during the check still
+  propagate, by design, so that interrupting the CLI always works.
+
+### Disabling it
+
+```zsh
+export PRAETORIAN_CLI_DISABLE_UPDATE_CHECK=1
+```
+
+`1`, `true`, `yes` or `on` (any case). Nothing is read or written — no request,
+no cache file.
+
+### Privacy
+
+A refresh is an unauthenticated `GET` to `https://pypi.org/pypi/praetorian-cli/json`.
+It sends no account, profile, command, or argument — only what any HTTPS request
+inherently reveals to the server: your IP address and the fact that some
+`praetorian-cli` install asked for the package index at that moment. Because
+every attempt is recorded before it is made and concurrent attempts are
+excluded, that happens at most once per day per user account on the machine —
+several users each get their own cache — so your per-command usage cadence is
+not exposed. If contacting
+pypi.org at all is unacceptable in your environment, set the variable above.
+
 # Operators
 
 ## Interactive Console
@@ -190,7 +383,9 @@ The console provides:
 - **Engagement management** — switch between accounts, view stats (seeds/assets/risks), create customers, manage vaults
 - **Metasploit-style tool selection** — `use <tool>`, `show targets`, `set target`, `execute`
 - **All 141 backend capabilities** — any capability can be selected via `use <name>` or `use <#>`
-- **Marcus Aurelius AI** — inline queries (`ask`) and multi-turn conversation (`marcus`)
+- **Marcus Aurelius AI** — inline queries, supervised multi-agent operations, HITL approvals, and secure credential prompts
+- **Aegis v2 operations** — endpoint inventory, capability execution, tunnels, users, egress policy, and lifecycle controls
+- **AI Hunts** — all-surface launch, unified monitoring, steering, memory, findings, workflows, and approvals
 - **Fulltext search** — `find` for Neo4j graph search across all entity types
 - **Evidence hydration** — `evidence <risk>` fetches all scattered evidence in one view
 - **Report generation** — `report generate` / `report validate`
@@ -245,12 +440,23 @@ Marcus is Guard's AI operator, accessible from both the CLI and the interactive
 guard ask "how many critical risks are there?"
 guard ask "show me all assets with port 22 open" --mode query
 
+# Supervised multi-agent operations
+guard agent conversation --mode agent
+
 # File analysis and ingestion
 guard marcus read "vault/engagement/sow.pdf"
 guard marcus ingest "vault/nessus-export.csv" --findings
 guard marcus do "generate an executive summary"
 ```
 
+Agent mode shows named tool and delegated-agent progress. Use `/agents`,
+`/focus`, and `/guide` to navigate and steer the tree; `/stop <id-prefix>` stops
+one branch, while `stop` or Ctrl+X stops Marcus and all correlated work.
+Endpoint approvals and masked one-time credential/MFA prompts are handled in
+the terminal without persisting secret values in conversation history.
+
+See [Guard Interactive Console](docs/console.md#supervised-agent-mode) for the complete command set.
+
 In the console, Marcus shows live tool execution:
 ```
 guard > ask "analyze the top risks"
@@ -350,7 +556,14 @@ guard.add('asset', dict(name='example.com', dns='example.com'))
 The best place to explore the SDK is the code of the CLI, especially
 [the handlers of the CLI](https://github.com/praetorian-inc/praetorian-cli/tree/main/praetorian_cli/handlers)
 
-You can inspect the handler code to see how each CLI command is implemented with the SDK.
+You can inspect the handler code to see how each CLI command is implemented
+with the SDK. The 2.6.0 release adds structured APIs under `sdk.aegis`,
+`sdk.hunts`, `sdk.conversations`, `sdk.endpoint_executions`, and
+`sdk.credentials`.
+
+For higher-level examples and safety requirements, see
+[Aegis endpoints](docs/aegis.md), [AI Hunts](docs/hunts.md), and
+[Engineer VMs](docs/engineer-vms.md).
 
 ## Developing external scripts
 
@@ -370,6 +583,49 @@ For developing scripts, you can refer to
 this [readme file](https://github.com/praetorian-inc/praetorian-cli/blob/main/docs/script-development.md).
 
 
+## Running the test suite
+
+`guard test` runs the integration suites that ship with the package. **Some of
+those suites create, modify and delete real entities in whatever account the
+selected profile points at**, so the command is gated.
+
+Suites are selected with `-s`/`--suite`:
+
+| Suite | What it runs | Touches a live account? |
+| --- | --- | --- |
+| `safe` *(default)* | Local, offline unit tests | No |
+| `coherence` | End-to-end entity lifecycle tests | **Yes — creates and deletes assets, risks, settings, configurations** |
+| `cli` | CLI-level integration tests | **Yes — mutating** |
+| `tui` | Terminal UI tests | No |
+
+A bare `guard test` runs the `safe` suite only. It executes with a temporary
+`HOME` and with credential environment variables stripped, so it cannot reach
+your real credentials.
+
+The mutating suites additionally require:
+
+1. **An explicit profile and account.** Both must be given and non-empty —
+   `guard --profile <profile> --account <account> test --suite coherence`.
+   There is no fallback: an unset or blank value is an error, so the suite can
+   never quietly run against a default profile.
+2. **Interactive confirmation.** The command prints the suite, profile, account,
+   and whether the suite is live and mutating, then asks you to confirm.
+   Declining — or a non-interactive invocation, which cannot confirm — exits
+   non-zero without running any test.
+
+```zsh
+# Safe by default — no account is touched.
+guard test
+
+# Mutating suite: target must be explicit, and you must confirm.
+guard --profile "United States" --account guard+scratch@praetorian.com \
+    test --suite coherence
+```
+
+Never point a mutating suite at a production account. Use a dedicated scratch
+account whose contents you are willing to lose.
+
+
 ## Contributing
 
 We welcome contributions from the community, from scripts, to the core CLI and SDK. To contribute, fork this