praetorian-cli 2.4.4__tar.gz → 2.4.7__tar.gz

{praetorian_cli-2.4.4/praetorian_cli.egg-info → praetorian_cli-2.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praetorian-cli
-Version: 2.4.4
+Version: 2.4.7
 Summary: For interacting with the Guard API
 Home-page: https://github.com/praetorian-inc/praetorian-cli
 Author: Praetorian
@@ -298,7 +298,8 @@ guard find "example.com"
 guard find "CVE-2024" --type risk
 
 # Evidence hydration
-guard get risk "#risk#example.com#CVE-2024-1234" --evidence
+guard get risk "#risk#example.com#CVE-2024-1234" --evidence basic
+guard get risk "#risk#example.com#CVE-2024-1234" --evidence full
 
 # Reports
 guard report generate --title "Q1 Pentest" --client "Acme Corp" --risks "status:OH"

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/README.md

@@ -274,7 +274,8 @@ guard find "example.com"
 guard find "CVE-2024" --type risk
 
 # Evidence hydration
-guard get risk "#risk#example.com#CVE-2024-1234" --evidence
+guard get risk "#risk#example.com#CVE-2024-1234" --evidence basic
+guard get risk "#risk#example.com#CVE-2024-1234" --evidence full
 
 # Reports
 guard report generate --title "Q1 Pentest" --client "Acme Corp" --risks "status:OH"

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/praetorian_cli/handlers/add.py

@@ -419,9 +419,97 @@ def credential_webauth(sdk, resource_key, label, headers):
         - guard add credential webauth -k "#webapplication#https://app.example.com" -l "Prod token" -H "Authorization=Bearer abc123" -H "X-Tenant=acme"
     """
     headers_dict = parse_kv_entries(headers, label='Header')
-    parameters = {'method': 'static-token', 'headers': headers_dict}
+    return _add_webauth(sdk, resource_key, label, {'method': 'static-token', 'headers': headers_dict})
+
+
+def _add_webauth(sdk, resource_key, label, parameters):
+    """Send a web-auth credential to the broker and echo the response. Returns the result."""
     try:
         result = sdk.credentials.add(resource_key, 'env-integration', 'web-auth', label, parameters)
-        click.echo(json.dumps(result, indent=2))
     except Exception as e:
         error(f'Unable to add web-auth credential. Error: {e}')
+    click.echo(json.dumps(result, indent=2))
+    return result
+
+
+@credential.command('webauth-discover')
+@cli_handler
+@click.option('-k', '--resource-key', required=True,
+              help='Web-application key (e.g., #webapplication#https://app.example.com)')
+@click.option('-l', '--label', required=True, help='A human-readable label for the credential')
+@click.option('--login-url', required=True, help='URL of the login page for the recorder agent to drive')
+@click.option('-i', '--input', 'inputs', multiple=True, required=True,
+              help='Login input as key=value (e.g. username=alice, password=s3cret). Repeatable.')
+@click.option('--hint', default=None,
+              help='Free-text guidance for the recorder agent (e.g. "MFA via authenticator app")')
+def credential_webauth_discover(sdk, resource_key, label, login_url, inputs, hint):
+    """ Add a discover-login web-auth credential (AI records the login flow).
+
+    A recorder agent drives a browser through the login at --login-url using
+    the supplied inputs, then commits a replayable recipe for you. This is the
+    recommended path for browser-based logins — far more reliable than
+    hand-authoring browser steps in a recipe. Follow the recorder run with
+    `guard get conversation <id> --watch` using the returned conversation_id.
+
+    \b
+    Example usage:
+        - guard add credential webauth-discover -k "#webapplication#https://app.example.com" -l "Admin" --login-url https://app.example.com/login -i username=alice -i password=s3cret
+    """
+    inputs_dict = parse_kv_entries(inputs, label='Input')
+    parameters = {'method': 'discover-login', 'login_url': login_url, 'inputs': inputs_dict}
+    if hint:
+        parameters['hint'] = hint
+    _add_webauth(sdk, resource_key, label, parameters)
+
+
+@credential.command('webauth-recipe')
+@cli_handler
+@click.option('-k', '--resource-key', required=True,
+              help='Web-application key (e.g., #webapplication#https://app.example.com)')
+@click.option('-l', '--label', required=True, help='A human-readable label for the credential')
+@click.option('--steps', 'steps_file', required=True, type=click.File('r'),
+              help='Path to a JSON file containing the recipe steps array (see step reference below)')
+@click.option('-i', '--input', 'inputs', multiple=True,
+              help='Recipe input as key=value, referenced as {{key}} in steps (e.g. username=alice). Repeatable.')
+def credential_webauth_recipe(sdk, resource_key, label, steps_file, inputs):
+    """ Add a dynamic-login web-auth credential from a recipe.
+
+    A recipe is a JSON array of steps that logs in and captures the resulting
+    auth header, replayed before each scan. PREFER HTTP-BASED STEPS
+    (http/extract/capture) — they replay reliably. For browser-driven logins
+    (SPAs, MFA, JS-set cookies) use `webauth-discover` instead; hand-authored
+    browser steps are brittle.
+
+    \b
+    HTTP-based step reference:
+        - http     {method, url, headers?, body?}  send a request; fields take {{vars}}
+        - extract  {from, save_as, jsonpath?|regex?}  bind a var from the last response
+                     from: "response_body" (needs jsonpath OR one-group regex),
+                           "response_header:<Name>", "response_cookie:<Name>",
+                           "request_header:<Name>"
+        - capture  {name, value}  write an output header (value takes {{vars}})  [required]
+    Browser steps (discouraged — use webauth-discover): navigate, click, type,
+    totp, cookie, load_request.
+
+    \b
+    Example recipe.json (POST login, pull token from JSON, set Authorization):
+        [
+          {"kind": "http", "method": "POST", "url": "https://app.example.com/api/login",
+           "headers": {"Content-Type": "application/json"},
+           "body": "{\\"user\\":\\"{{username}}\\",\\"pass\\":\\"{{password}}\\"}"},
+          {"kind": "extract", "from": "response_body", "jsonpath": "$.token", "save_as": "token"},
+          {"kind": "capture", "name": "Authorization", "value": "Bearer {{token}}"}
+        ]
+
+    \b
+    Example usage:
+        - guard add credential webauth-recipe -k "#webapplication#https://app.example.com" -l "API login" --steps recipe.json -i username=alice -i password=s3cret
+    """
+    inputs_dict = parse_kv_entries(inputs, label='Input') if inputs else {}
+    try:
+        steps = json.load(steps_file)
+    except json.JSONDecodeError as e:
+        error(f'--steps is not valid JSON: {e}')
+
+    # The backend validates the recipe schema; we only ensure it is valid JSON.
+    _add_webauth(sdk, resource_key, label, {'method': 'dynamic-login', 'steps': steps, 'inputs': inputs_dict})

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/praetorian_cli/handlers/delete.py

@@ -115,23 +115,6 @@ def file(chariot, filepath):
     chariot.files.delete(filepath)
 
 
-# Special command for deleting your account and all related information.
-@chariot.command()
-@cli_handler
-def purge(controller):
-    """ Delete account and all related information
-
-    Example usage:
-        - guard purge
-    """
-    if click.confirm('This will delete all your data and revoke access, are you sure?', default=False):
-        controller.purge()
-    else:
-        click.echo('Purge cancelled')
-        return
-    click.echo('Account deleted successfully')
-
-
 @delete.command()
 @cli_handler
 @click.argument('name', required=True)

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/praetorian_cli/handlers/get.py

@@ -1,4 +1,6 @@
+import json
 import os
+import time
 
 import click
 
@@ -36,7 +38,7 @@ def asset(chariot, key, details):
 @cli_handler
 @click.argument('key', required=True)
 @click.option('-d', '--details', is_flag=True, help='Further retrieve the attributes and affected assets of the risk')
-@click.option('-e', '--evidence', is_flag=True, help='Retrieve all evidence from all sources (attributes, webpages, files, definitions)')
+@click.option('-e', '--evidence', type=click.Choice(['off', 'basic', 'full']), default='off', show_default=True, help='Evidence hydration mode. "basic" inlines one proof file; "full" inlines all proof files.')
 def risk(chariot, key, details, evidence):
     """ Get risk details
 
@@ -48,12 +50,10 @@ def risk(chariot, key, details, evidence):
     Example usages:
         - guard get risk "#risk#api.example.com#CVE-2024-23049"
         - guard get risk "#risk#api.example.com#CVE-2024-23049" --details
-        - guard get risk "#risk#api.example.com#CVE-2024-23049" --evidence
+        - guard get risk "#risk#api.example.com#CVE-2024-23049" --evidence basic
+        - guard get risk "#risk#api.example.com#CVE-2024-23049" --evidence full
      """
-    if evidence:
-        print_json(chariot.risks.get(key, evidence=True))
-    else:
-        print_json(chariot.risks.get(key, details))
+    print_json(chariot.risks.get(key, details, evidence=evidence))
 
 
 @get.command()
@@ -389,3 +389,144 @@ def schedule(chariot, schedule_id):
         print_json(result)
     else:
         click.echo(f'Schedule not found: {schedule_id}')
+
+
+@get.command('ttl-status')
+@cli_handler
+@click.argument('key', required=True)
+@click.option('--format', 'fmt', type=click.Choice(['text', 'json']), default='text', show_default=True)
+def ttl_status(chariot, key, fmt):
+    """ Explain why the TTL cron would (or would not) collect an entity
+
+    \b
+    A :TTL node is deleted only when its ttl has expired AND it has no
+    outgoing HAS_VULNERABILITY / HAS_PORT / HAS_WEBPAGE / HAS_MEMBER edge.
+    This shows the node's ttl plus the exact edges pinning it alive, so you
+    can chase the chain (e.g. WebApplication -HAS_WEBPAGE-> Webpage
+    -HAS_VULNERABILITY-> Risk) by re-running against a blocker's key.
+
+    \b
+    Example usages:
+        - guard get ttl-status "#webapplication#https://example.com:443/"
+        - guard get ttl-status "#webpage#https://example.com/login" --format json
+    """
+    status = chariot.search.ttl_status(key)
+
+    if fmt == 'json':
+        print_json(status)
+        return
+
+    ttl, blockers = status['ttl'], status['blockers']
+    click.echo(f"key:          {status['key']}")
+    click.echo(f'ttl:          {ttl}' + (' (expired)' if status['ttl_expired']
+                                         else ' (not expired)' if ttl else ' (none)'))
+    if blockers:
+        click.echo(f'blocked by:   {len(blockers)} edge(s)')
+        for b in blockers:
+            click.echo(f"  {b['edge']} -> {b['target']}  (edge visited {b['visited']})")
+    else:
+        click.echo('blocked by:   none')
+    click.echo(f"would delete: {status['would_delete']}")
+
+
+@get.command()
+@cli_handler
+@click.argument('conversation_id', required=True)
+@click.option('--format', 'fmt', type=click.Choice(['text', 'json', 'live']), default='text', show_default=True,
+              help='text/json render the current transcript; live polls and streams new messages until the conversation is no longer active')
+@click.option('--full', is_flag=True, help='Do not truncate long tool inputs/responses in text mode')
+def conversation(chariot, conversation_id, fmt, full):
+    """ Get a full conversation transcript, including every tool call
+
+    \b
+    Argument:
+        - CONVERSATION_ID: the uuid of a conversation (see 'guard list conversations')
+
+    \b
+    Example usages:
+        - guard get conversation e5e8db7d-9116-4d7a-a16a-e36680a78c14
+        - guard get conversation e5e8db7d-9116-4d7a-a16a-e36680a78c14 --full
+        - guard get conversation e5e8db7d-9116-4d7a-a16a-e36680a78c14 --format json
+        - guard get conversation e5e8db7d-9116-4d7a-a16a-e36680a78c14 --format live
+    """
+    if fmt == 'live':
+        watch_conversation(chariot, conversation_id, full)
+        return
+    convo = chariot.conversations.get(conversation_id)
+    if fmt == 'json':
+        print_json(convo)
+        return
+    _render_conversation(convo, full)
+
+
+def watch_conversation(chariot, conversation_id, full=False, interval=3, timeout=600):
+    """Stream a conversation, printing new messages as they arrive. Stops when the
+    conversation leaves 'active' status or after `timeout` seconds."""
+    seen = 0
+    deadline = time.time() + timeout
+    while True:
+        convo = chariot.conversations.get(conversation_id)
+        ended = bool(convo.get('status')) and convo['status'] != 'active'
+        messages = convo['messages']
+        while seen < len(messages):
+            m = messages[seen]
+            # A tool call's response is folded into the same message and may
+            # arrive on a later poll; hold the message until it lands (unless
+            # the conversation has ended and nothing more is coming).
+            if not ended and m.get('tool') and m['tool'].get('response') is None:
+                break
+            _echo_message(m, full)
+            seen += 1
+        if ended:
+            click.secho(f"— conversation {convo['status']} —", fg='blue')
+            return
+        if time.time() >= deadline:
+            click.secho('— watch timed out (conversation still active) —', fg='yellow')
+            return
+        time.sleep(interval)
+
+
+def _render_conversation(convo, full):
+    click.echo(click.style(f"Conversation {convo['uuid']}", bold=True) + f"  ({convo['status']})")
+    if convo['topic']:
+        click.echo(f"Topic:   {convo['topic']}")
+    if convo['created']:
+        click.echo(f"Created: {convo['created']}")
+    click.echo('─' * 70)
+    for m in convo['messages']:
+        _echo_message(m, full)
+
+
+_ROLE_COLOR = {'user': 'cyan', 'chariot': 'green', 'system': 'magenta'}
+
+
+def _echo_message(m, full):
+    if m.get('tool'):
+        _echo_tool(m['tool'], full)
+    else:
+        click.secho(f"[{m['role']}]", fg=_ROLE_COLOR.get(m['role'], 'white'))
+        click.echo(_indent(m['content']))
+    click.echo()
+
+
+def _echo_tool(tool, full):
+    args = _as_text(tool['input'])
+    header = click.style(f"[tool call] {tool['name']}", fg='yellow')
+    click.echo(header + (f'  {_truncate(args, 200, full)}' if args else ''))
+    if tool['response'] is not None:
+        click.echo(_indent('→ ' + _truncate(_as_text(tool['response']), 800, full)))
+
+
+def _as_text(value):
+    if value is None or value == '':
+        return ''
+    return value if isinstance(value, str) else json.dumps(value, separators=(',', ':'))
+
+
+def _truncate(s, limit, full):
+    return s if full or len(s) <= limit else f'{s[:limit]}… ({len(s)} chars, --full for all)'
+
+
+def _indent(text):
+    return '\n'.join('    ' + line for line in str(text).splitlines())
+

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/praetorian_cli/handlers/list.py

@@ -31,7 +31,9 @@ def assets(chariot, filter, model_type, details, offset, page):
 
 @list.command()
 @list_params('group of the associated assets')
-def risks(chariot, filter, details, offset, page):
+@click.option('-s', '--sort', 'sort_by', type=click.Choice(['visited', 'created', 'updated', 'name', 'status', 'source', 'title']), default=None, help='Sort risks by a field')
+@click.option('-desc', '--desc', is_flag=True, default=False, help='Return data in descending order')
+def risks(chariot, filter, details, offset, page, sort_by, desc):
     """ List risks
 
     Retrieve and display a list of risks.
@@ -42,8 +44,9 @@ def risks(chariot, filter, details, offset, page):
         - guard list risks --filter api.example.com
         - guard list risks --details
         - guard list risks --page all
+        - guard list risks --sort visited --desc
     """
-    render_list_results(chariot.risks.list(filter, offset, pagination_size(page)), details)
+    render_list_results(chariot.risks.list(filter, offset, pagination_size(page), sort_by=sort_by, descending=desc), details)
 
 
 @list.command()
@@ -344,18 +347,22 @@ def keys(chariot, details, offset, page):
     render_list_results(chariot.keys.list(offset, pagination_size(page)), details)
 
 @list.command()
+@click.option('-k', '--resource-key', 'resource_key', default=None,
+              help='Scope to credentials attached to this WebApplication (via HAS_CREDENTIAL)')
 @list_params('credential ID', has_details=False, has_filter=False)
-def credentials(chariot, offset, page):
+def credentials(chariot, resource_key, offset, page):
     """ List credentials
 
-    Retrieve and display a list of credentials.
+    Retrieve and display a list of credentials, optionally scoped to one
+    WebApplication.
 
     \b
     Example usages:
         - guard list credentials
         - guard list credentials --page all
+        - guard list credentials -k "#webapplication#https://app.example.com"
     """
-    print_json(chariot.credentials.list(offset, pagination_size(page)))
+    print_json(chariot.credentials.list(offset, pagination_size(page), resource_key=resource_key))
 
 
 @list.command()
@@ -427,3 +434,30 @@ def schedules(chariot, details, offset, page):
         - guard list schedules --page all
     """
     render_list_results(chariot.schedules.list(pagination_size(page)), details)
+
+
+@list.command()
+@pagination
+@cli_handler
+@click.option('--scope', type=click.Choice(['user', 'tenant', 'all']), default='all', show_default=True,
+              help='user: your private conversations; tenant: shared public + hunt-owned; all: both')
+@click.option('--format', 'fmt', type=click.Choice(['text', 'json']), default='text', show_default=True)
+def conversations(chariot, offset, page, scope, fmt):
+    """ List Guard AI conversations, most recent first
+
+    \b
+    Example usages:
+        - guard list conversations
+        - guard list conversations --scope tenant
+        - guard list conversations --scope all --page all
+        - guard list conversations --format json
+    """
+    convos, offset = chariot.conversations.list(scope, offset or None, pagination_size(page))
+    if fmt == 'json':
+        print_json(dict(data=convos, offset=offset))
+    else:
+        for c in convos:
+            topic = ' '.join((c.get('topic') or '').split())
+            click.echo(f"{(c.get('uuid') or ''):38} {(c.get('created') or '')[:16]:16} "
+                       f"{(c.get('status') or ''):8} {topic}")
+    render_offset(offset)

praetorian_cli-2.4.7/praetorian_cli/handlers/query.py

@@ -0,0 +1,48 @@
+import click
+
+from praetorian_cli.handlers.chariot import chariot
+from praetorian_cli.handlers.cli_decorators import cli_handler
+from praetorian_cli.handlers.utils import render_list_results, print_json, error
+from praetorian_cli.sdk.model.globals import Kind
+
+
+@chariot.command()
+@cli_handler
+@click.option('--json', 'raw_json', help='Raw graph query as a JSON string (see sdk search.by_query)')
+@click.option('--anchor', help='Exact key of the node to traverse from (shorthand mode)')
+@click.option('--rel', 'rels', multiple=True,
+              help='Relationship label(s) to follow, e.g. HAS_WEBPAGE. Omit to follow the common core edges.')
+@click.option('--neighbor', type=click.Choice([k.value for k in Kind]), help='Constrain the neighbor kind')
+@click.option('-d', '--details', is_flag=True, default=False, help='Show full records instead of just keys')
+def query(chariot, raw_json, anchor, rels, neighbor, details):
+    """ Run an arbitrary graph query, including relationships.
+
+    \b
+    Two modes:
+
+    \b
+    - Raw: pass a full graph query as JSON (same shape the MCP tool uses).
+        guard query --json '{"node": {"labels": ["Asset"], "relationships": [
+          {"label": "HAS_VULNERABILITY", "target": {"labels": ["Risk"],
+           "filters": [{"field": "priority", "operator": ">=", "value": 70}]}}]}}'
+
+    \b
+    - Shorthand: one hop from an anchor node to its neighbors.
+        guard query --anchor "#webapplication#https://example.com"                         # every edge
+        guard query --anchor "#asset#example.com#1.2.3.4" --rel HAS_WEBPAGE
+        guard query --anchor "#webapplication#https://example.com" --rel HAS_WEBPAGE --neighbor webpage
+        guard query --anchor "#asset#example.com#1.2.3.4" --rel HAS_VULNERABILITY --neighbor risk --details
+    """
+    if raw_json:
+        render_list_results(chariot.search.by_query(raw_json), details)
+        return
+
+    if not anchor:
+        error('Provide either --json, or --anchor (with optional --rel).')
+
+    edges = chariot.search.relationships(anchor, list(rels), neighbor)
+    if details:
+        print_json(dict(data=edges))
+    else:
+        for e in edges:
+            click.echo(f"{e['label']:20} {e['target'].get('key', '')}")

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/praetorian_cli/handlers/search.py

@@ -15,7 +15,8 @@ from praetorian_cli.sdk.model.globals import Kind
 @click.option('-d', '--details', is_flag=True, default=False, help='Show detailed information')
 @click.option('-desc', '--desc', is_flag=True, default=False, help='Return data in descending order')
 @click.option('-g', '--global', 'global_', is_flag=True, default=False, help='Use the global data set')
-def search(chariot, term, count, kind, details, offset, page, desc, global_):
+@click.option('-a', '--all-tenants', 'all_tenants', is_flag=True, default=False, help='Search across all tenants you are authorized to access')
+def search(chariot, term, count, kind, details, offset, page, desc, global_, all_tenants):
     """ Query Guard for matches or counts using the search syntax
 
     \b
@@ -67,5 +68,6 @@ def search(chariot, term, count, kind, details, offset, page, desc, global_):
             error(f'Search term "{term}" requires the entity kind (--kind) argument.')
 
         render_list_results(
-            chariot.search.by_term(term, kind, offset, pagination_size(page), descending=desc, global_=global_),
+            chariot.search.by_term(term, kind, offset, pagination_size(page), descending=desc, global_=global_,
+                                   all_tenants=all_tenants),
             details)

{praetorian_cli-2.4.4 → praetorian_cli-2.4.7}/praetorian_cli/main.py

@@ -15,6 +15,7 @@ import praetorian_cli.handlers.run
 import praetorian_cli.handlers.imports
 import praetorian_cli.handlers.link
 import praetorian_cli.handlers.list
+import praetorian_cli.handlers.query
 import praetorian_cli.handlers.report
 import praetorian_cli.handlers.script
 import praetorian_cli.handlers.search