praetorian-cli 2.3.3__tar.gz → 2.3.5__tar.gz

{praetorian_cli-2.3.3/praetorian_cli.egg-info → praetorian_cli-2.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praetorian-cli
-Version: 2.3.3
+Version: 2.3.5
 Summary: For interacting with the Guard API
 Home-page: https://github.com/praetorian-inc/praetorian-cli
 Author: Praetorian

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/handlers/add.py

@@ -145,7 +145,8 @@ def webhook(sdk):
 @click.option('-c', '--comment', default='', help='Comment for the risk')
 @click.option('-cap', '--capability', default='', help='Capability that discoverd the risk')
 @click.option('--title', '-t', default=None, help='Human-readable title for the risk')
-def risk(sdk, name, asset, status, comment, capability, title):
+@click.option('-g', '--tag', 'tags', multiple=True, help='Tag for the risk (can be specified multiple times)')
+def risk(sdk, name, asset, status, comment, capability, title, tags):
     """ Add a risk
 
     This command adds a risk to Guard. A risk must have an associated asset.
@@ -161,8 +162,9 @@ def risk(sdk, name, asset, status, comment, capability, title):
         - guard add risk CVE-2024-23049 --asset "#asset#example.com#1.2.3.4" --status TI
         - guard add risk CVE-2024-23049 --asset "#asset#example.com#1.2.3.4" --status TC
         - guard add risk CVE-2024-23049 --asset "#asset#example.com#1.2.3.4" --status TC --capability red-team
+        - guard add risk CVE-2024-23049 --asset "#asset#example.com#1.2.3.4" --status TI --tag critical --tag needs-review
     """
-    sdk.risks.add(asset, name, status, comment, capability, title)
+    sdk.risks.add(asset, name, status, comment, capability, title, tags)
 
 
 @add.command()

praetorian_cli-2.3.5/praetorian_cli/handlers/export.py

@@ -0,0 +1,102 @@
+import os
+
+import click
+
+from praetorian_cli.handlers.chariot import chariot
+from praetorian_cli.handlers.cli_decorators import cli_handler
+
+
+@chariot.group()
+def export():
+    """ Export data from Guard """
+    pass
+
+
+@export.command()
+@cli_handler
+@click.option('--title', required=True, help='Report title')
+@click.option('--client-name', required=True, help='Client organization name')
+@click.option('--status-filter', multiple=True, default=('O', 'T'),
+              help='Risk status filter (repeatable). Default: O T')
+@click.option('--risk-keys', multiple=True, default=(),
+              help='Specific risk keys to include (repeatable). Default: all')
+@click.option('--target', default='', help='Target/scope (e.g., example.com)')
+@click.option('--start-date', default='', help='Engagement start date (ISO format)')
+@click.option('--end-date', default='', help='Engagement end date (ISO format)')
+@click.option('--report-date', default='', help='Report date (ISO format). Default: today')
+@click.option('--draft/--no-draft', default=False, help='Add DRAFT watermark')
+@click.option('--version', 'report_version', default='1.0', help='Report version string')
+@click.option('--format', 'export_format', type=click.Choice(['pdf', 'zip']),
+              default='pdf', help='Export format')
+@click.option('--group-by', type=click.Choice(['attack_surface', 'tag']),
+              default='attack_surface', help='Finding grouping strategy')
+@click.option('--shared/--no-shared', default=False,
+              help='Copy report to customer shared files')
+@click.option('--executive-summary', default='',
+              help='Path to executive summary .md file in Guard storage')
+@click.option('--narratives', default='',
+              help='Path to narratives .md file in Guard storage')
+@click.option('--appendix', default='',
+              help='Path to appendix .md file in Guard storage')
+@click.option('--output', '-o', default=os.getcwd(),
+              help='Local directory to save the downloaded report')
+@click.option('--timeout', default=300, type=int,
+              help='Max seconds to wait for report generation. Default: 300')
+@click.option('--no-download', is_flag=True, default=False,
+              help='Skip downloading the file; just print the job result')
+def report(chariot, title, client_name, status_filter, risk_keys,
+           target, start_date, end_date, report_date, draft,
+           report_version, export_format, group_by, shared,
+           executive_summary, narratives, appendix, output,
+           timeout, no_download):
+    """ Generate and download a PDF or ZIP report.
+
+    Requires Praetorian engineer access. Initiates report generation,
+    polls until the job completes, then downloads the file.
+
+    The customer email is derived automatically from --account (the customer
+    you are viewing) or the logged-in user's email.
+
+    \b
+    Example usages:
+        guard --account customer@acme.com export report \\
+            --title "Pentest Report" --client-name "Acme"
+
+        guard --account customer@acme.com export report \\
+            --title "Q1 Assessment" --client-name "Acme" \\
+            --format zip --draft \\
+            --status-filter O --status-filter T --status-filter R
+    """
+    customer_email = chariot.reports.customer_email()
+
+    body = chariot.reports.build_export_body(
+        title=title,
+        client_name=client_name,
+        customer_email=customer_email,
+        status_filter=status_filter,
+        risk_keys=risk_keys,
+        target=target,
+        start_date=start_date,
+        end_date=end_date,
+        report_date=report_date,
+        draft=draft,
+        version=report_version,
+        export_format=export_format,
+        group_by=group_by,
+        shared_output=shared,
+        executive_summary_path=executive_summary,
+        narratives_path=narratives,
+        appendix_path=appendix,
+    )
+
+    click.echo(f'Starting {export_format.upper()} report generation for {customer_email}...')
+    job = chariot.reports.export(body, timeout=timeout)
+    click.echo('Report generation complete.')
+
+    if no_download:
+        click.echo(f'Output path: {chariot.reports.output_path(job)}')
+        return
+
+    click.echo(f'Downloading {chariot.reports.output_path(job)}...')
+    local_path = chariot.reports.download(job, output)
+    click.echo(f'Saved to {local_path}')

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/handlers/link.py

@@ -13,7 +13,10 @@ def link():
 @link.command()
 @cli_handler
 @click.argument('username')
-def account(chariot, username):
+@click.option('--role', '-r', required=True,
+              type=click.Choice(['admin', 'analyst', 'readonly'], case_sensitive=False),
+              help='Role to assign to the collaborator.')
+def account(chariot, username, role):
     """ Add a collaborator account to your account
 
     This allows them to assume access into your account
@@ -21,15 +24,14 @@ def account(chariot, username):
 
     \b
     Arguments:
-        - NAME: their email address
-
-
+        - USERNAME: their email address
 
     \b
     Example usages:
-        - guard link account john@praetorian.com
+        - guard link account john@praetorian.com --role admin
+        - guard link account analyst@example.com -r readonly
     """
-    chariot.accounts.add_collaborator(username)
+    chariot.accounts.add_collaborator(username, role=role)
 
 
 @link.command('webpage-source')

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/handlers/update.py

@@ -38,7 +38,8 @@ def asset(chariot, key, status, surface):
 @click.option('-c', '--comment', default='', help='Comment for the risk')
 @click.option('-r', '--remove-comment', type=int, default=None, help='Remove comment at index (0, 1, ... or -1 for most recent)')
 @click.option('--title', '-t', default=None, help='Human-readable title for the risk')
-def risk(chariot, key, status, comment, remove_comment, title):
+@click.option('-g', '--tag', 'tags', multiple=True, help='Tag for the risk (can be specified multiple times)')
+def risk(chariot, key, status, comment, remove_comment, title, tags):
     """ Update the status and comment of a risk
 
     \b
@@ -51,11 +52,12 @@ def risk(chariot, key, status, comment, remove_comment, title):
         - guard update risk "#risk#www.example.com#open-ssh-port" --status RH --comment "John stopped sshd on the server"
         - guard update risk "#risk#www.example.com#CVE-2024-23049" --remove-comment 0
         - guard update risk "#risk#www.example.com#CVE-2024-23049" --remove-comment -1
+        - guard update risk "#risk#www.example.com#CVE-2024-23049" --tag resolved --tag verified
     """
     if comment and remove_comment is not None:
         raise click.UsageError("Cannot use --comment and --remove-comment together")
 
-    chariot.risks.update(key, status, comment, remove_comment, title)
+    chariot.risks.update(key, status, comment, remove_comment, title, tags)
 
 
 @update.command()

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/main.py

@@ -5,6 +5,7 @@ import praetorian_cli.handlers.aegis
 import praetorian_cli.handlers.agent
 import praetorian_cli.handlers.delete
 import praetorian_cli.handlers.enrich
+import praetorian_cli.handlers.export
 import praetorian_cli.handlers.get
 import praetorian_cli.handlers.imports
 import praetorian_cli.handlers.link

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/sdk/chariot.py

@@ -15,6 +15,7 @@ from praetorian_cli.sdk.entities.integrations import Integrations
 from praetorian_cli.sdk.entities.jobs import Jobs
 from praetorian_cli.sdk.entities.keys import Keys
 from praetorian_cli.sdk.entities.preseeds import Preseeds
+from praetorian_cli.sdk.entities.reports import Reports
 from praetorian_cli.sdk.entities.risks import Risks
 from praetorian_cli.sdk.entities.scanners import Scanners
 from praetorian_cli.sdk.entities.schedules import Schedules
@@ -37,6 +38,7 @@ class Chariot:
         self.assets = Assets(self)
         self.seeds = Seeds(self)
         self.preseeds = Preseeds(self)
+        self.reports = Reports(self)
         self.risks = Risks(self)
         self.accounts = Accounts(self)
         self.integrations = Integrations(self)
@@ -183,8 +185,11 @@ class Chariot:
     def upsert(self, type: str, body: dict, params: dict = {}) -> dict:
         return self.put(type, body, params)
 
-    def link_account(self, username: str, value: str = '', config: dict = {}) -> dict:
-        resp = self.chariot_request('POST', self.url(f'/account/{username}'), json=dict(config=config, value=value))
+    def link_account(self, username: str, role: str = '', value: str = '', config: dict = {}) -> dict:
+        body = dict(config=config, value=value)
+        if role:
+            body['role'] = role
+        resp = self.chariot_request('POST', self.url(f'/account/{username}'), json=body)
         process_failure(resp)
         return resp.json()
 

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/sdk/entities/accounts.py

@@ -43,16 +43,18 @@ class Accounts:
 
         return results, next_offset
 
-    def add_collaborator(self, collaborator_email):
+    def add_collaborator(self, collaborator_email, role=''):
         """
         Add a collaborator to the account of the current principal.
 
         :param collaborator_email: Email address of the collaborator to add
         :type collaborator_email: str
+        :param role: Role to assign to the collaborator (admin, analyst, or readonly)
+        :type role: str
         :return: The created account entity with member information
         :rtype: dict
         """
-        return self.api.link_account(collaborator_email)
+        return self.api.link_account(collaborator_email, role=role)
 
     def delete_collaborator(self, collaborator_email):
         """

praetorian_cli-2.3.5/praetorian_cli/sdk/entities/reports.py

@@ -0,0 +1,194 @@
+from datetime import date
+from time import sleep, time
+
+
+class Reports:
+    """ The methods in this class are to be accessed from sdk.reports, where sdk
+    is an instance of Chariot. """
+
+    POLL_INTERVAL = 5
+    DEFAULT_TIMEOUT = 300
+
+    def __init__(self, api):
+        self.api = api
+
+    def customer_email(self):
+        """
+        Derive the customer email from the current SDK context.
+
+        Uses the --account (assumed account) if set, otherwise falls back
+        to the logged-in user's email. This mirrors the frontend logic of
+        ``friend || me``.
+
+        :return: The customer email address
+        :rtype: str
+        :raises Exception: If no customer email can be determined
+        """
+        email = self.api.keychain.account or self.api.keychain.username()
+        if not email:
+            raise Exception(
+                'Could not determine customer email. '
+                'Use --account or configure a username.'
+            )
+        return email
+
+    def build_export_body(self, title, client_name, customer_email,
+                          status_filter=('O', 'T'), risk_keys=(),
+                          target='', start_date='', end_date='',
+                          report_date='', draft=False, version='1.0',
+                          export_format='pdf', group_by='attack_surface',
+                          shared_output=False, executive_summary_path='',
+                          narratives_path='', appendix_path=''):
+        """
+        Build the request body for POST /export/report.
+
+        :param title: Report title
+        :type title: str
+        :param client_name: Client organization name
+        :type client_name: str
+        :param customer_email: Customer email address
+        :type customer_email: str
+        :param status_filter: Risk status codes to include
+        :type status_filter: tuple or list
+        :param risk_keys: Specific risk keys to include (empty for all)
+        :type risk_keys: tuple or list
+        :param target: Target/scope
+        :type target: str
+        :param start_date: Engagement start date (ISO format)
+        :type start_date: str
+        :param end_date: Engagement end date (ISO format)
+        :type end_date: str
+        :param report_date: Report date (ISO format). Defaults to today.
+        :type report_date: str
+        :param draft: Whether to add DRAFT watermark
+        :type draft: bool
+        :param version: Report version string
+        :type version: str
+        :param export_format: Output format ('pdf' or 'zip')
+        :type export_format: str
+        :param group_by: Finding grouping strategy ('attack_surface' or 'tag')
+        :type group_by: str
+        :param shared_output: Whether to copy to customer shared files
+        :type shared_output: bool
+        :param executive_summary_path: Path to executive summary .md in Guard storage
+        :type executive_summary_path: str
+        :param narratives_path: Path to narratives .md in Guard storage
+        :type narratives_path: str
+        :param appendix_path: Path to appendix .md in Guard storage
+        :type appendix_path: str
+        :return: Request body dict ready for POST /export/report
+        :rtype: dict
+        """
+        if not report_date:
+            report_date = date.today().isoformat()
+
+        body = {
+            'status_filter': list(status_filter),
+            'config': {
+                'title': title,
+                'client_name': client_name,
+                'report_date': report_date,
+                'draft': draft,
+                'version': version,
+            },
+            'shared_output': shared_output,
+            'customer_email': customer_email,
+            'export_format': export_format,
+            'group_by': group_by,
+        }
+
+        if risk_keys:
+            body['risk_keys'] = list(risk_keys)
+        if target:
+            body['config']['target'] = target
+        if start_date:
+            body['config']['start_date'] = start_date
+        if end_date:
+            body['config']['end_date'] = end_date
+        if executive_summary_path:
+            body['executive_summary_path'] = executive_summary_path
+        if narratives_path:
+            body['narratives_path'] = narratives_path
+        if appendix_path:
+            body['appendix_path'] = appendix_path
+
+        return body
+
+    def export(self, body, timeout=DEFAULT_TIMEOUT, poll_interval=POLL_INTERVAL):
+        """
+        Start a report export job, poll until completion, and return the job.
+
+        :param body: Request body from build_export_body()
+        :type body: dict
+        :param timeout: Max seconds to wait for completion
+        :type timeout: int
+        :param poll_interval: Seconds between status polls
+        :type poll_interval: int
+        :return: The completed job dict
+        :rtype: dict
+        :raises Exception: If the job fails, times out, or no job key is returned
+        """
+        resp = self.api.post('export/report', body)
+
+        job_key = resp.get('key')
+        if not job_key:
+            raise Exception('No job key returned from export/report endpoint.')
+
+        return self.poll_job(job_key, timeout, poll_interval)
+
+    def poll_job(self, job_key, timeout=DEFAULT_TIMEOUT, poll_interval=POLL_INTERVAL):
+        """
+        Poll a report generation job until it passes, fails, or times out.
+
+        :param job_key: The job key to poll
+        :type job_key: str
+        :param timeout: Max seconds to wait
+        :type timeout: int
+        :param poll_interval: Seconds between polls
+        :type poll_interval: int
+        :return: The completed job dict
+        :rtype: dict
+        :raises Exception: If the job fails or times out
+        """
+        start_time = time()
+        job = None
+        while time() - start_time < timeout:
+            job = self.api.jobs.get(job_key)
+            if self.api.jobs.is_failed(job):
+                message = job.get('message', 'unknown error')
+                raise Exception(f'Report generation failed: {message}')
+            if self.api.jobs.is_passed(job):
+                return job
+            sleep(poll_interval)
+
+        raise Exception(f'Report generation timed out after {timeout} seconds.')
+
+    def output_path(self, job):
+        """
+        Extract the output file path from a completed report job.
+
+        :param job: The completed job dict
+        :type job: dict
+        :return: The output file path in Guard storage
+        :rtype: str
+        :raises Exception: If the output path cannot be determined
+        """
+        config = job.get('config', {})
+        path = config.get('output') or job.get('dns', '')
+        if not path:
+            raise Exception('Could not determine output file path from job.')
+        return path
+
+    def download(self, job, download_directory):
+        """
+        Download the report file from a completed job to a local directory.
+
+        :param job: The completed job dict
+        :type job: dict
+        :param download_directory: Local directory to save the file
+        :type download_directory: str
+        :return: The local file path where the report was saved
+        :rtype: str
+        """
+        path = self.output_path(job)
+        return self.api.files.save(path, download_directory)

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/sdk/entities/risks.py

@@ -9,7 +9,7 @@ class Risks:
     def __init__(self, api):
         self.api = api
 
-    def add(self, asset_key, name, status, comment=None, capability='', title=None):
+    def add(self, asset_key, name, status, comment=None, capability='', title=None, tags=None):
         """
         Add a risk to an existing asset.
 
@@ -25,12 +25,16 @@ class Risks:
         :type capability: str
         :param title: Optional human-readable title for the risk
         :type title: str or None
+        :param tags: Optional tags for the risk
+        :type tags: tuple or list or None
         :return: The created risk object
         :rtype: dict
         """
         body = dict(key=asset_key, name=name, status=status, comment=comment, source=capability)
         if title is not None:
             body['title'] = title
+        if tags:
+            body['tags'] = list(tags)
         return self.api.upsert('risk', body)['risks'][0]
 
     def get(self, key, details=False):
@@ -49,7 +53,7 @@ class Risks:
             risk['affected_assets'] = self.affected_assets(key)
         return risk
 
-    def update(self, key, status=None, comment=None, remove_comment=None, title=None):
+    def update(self, key, status=None, comment=None, remove_comment=None, title=None, tags=None):
         """
         Update a risk's status and/or comment, or remove a comment.
 
@@ -63,6 +67,8 @@ class Risks:
         :type remove_comment: int or None
         :param title: Optional human-readable title for the risk
         :type title: str or None
+        :param tags: Optional tags for the risk
+        :type tags: tuple or list or None
         :return: API response containing update results
         :rtype: dict
         """
@@ -73,6 +79,8 @@ class Risks:
             params = params | dict(comment=comment)
         if title is not None:
             params['title'] = title
+        if tags:
+            params['tags'] = list(tags)
         if remove_comment is not None:
             index = self.resolve_comment_entry_index(key, remove_comment)
             params = params | dict(remove=index)

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/sdk/entities/webhook.py

@@ -48,7 +48,7 @@ class Webhook:
             ```
         """
         pin = str(uuid4())
-        self.api.link_account('hook', pin)
+        self.api.link_account('hook', role='readonly', value=pin)
         return self.webhook_url(pin)
 
     def get_url(self):

{praetorian_cli-2.3.3 → praetorian_cli-2.3.5}/praetorian_cli/sdk/test/test_job.py

@@ -12,6 +12,12 @@ class TestJob:
         self.sdk = setup_chariot()
         make_test_values(self)
 
+        self.was_frozen = False
+        frozen_setting = self.sdk.settings.get('#setting#frozen')
+        if frozen_setting and frozen_setting.get('value') == 'true':
+            self.was_frozen = True
+            self.sdk.settings.add('frozen', 'false')
+
     def test_add_job(self):
         result = self.sdk.assets.add(self.asset_dns, self.asset_dns)
         self.sdk.jobs.add(result['key'])
@@ -48,3 +54,5 @@ class TestJob:
 
     def teardown_class(self):
         clean_test_entities(self.sdk, self)
+        if self.was_frozen:
+            self.sdk.settings.add('frozen', 'true')