praetorian-cli 2.6.2__tar.gz → 2.6.3__tar.gz

{praetorian_cli-2.6.2/praetorian_cli.egg-info → praetorian_cli-2.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praetorian-cli
-Version: 2.6.2
+Version: 2.6.3
 Summary: For interacting with the Guard API
 Home-page: https://github.com/praetorian-inc/praetorian-cli
 Author: Praetorian
@@ -16,7 +16,8 @@ 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: mcp>=2.0.0
+Requires-Dist: jsonschema>=4.20.0
 Requires-Dist: anyio>=3.0.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: textual>=0.47.0
@@ -529,8 +530,20 @@ guard run installed
 guard engagement list
 guard engagement create-customer --email ops@acme.com --name "ACME Corp"
 guard engagement create-vault --client acme --sow SOW-1234 --sku WAPT --github-user jdoe
+
+# Mobile testing: upload an APK, then run a capability against it on a device
+guard add apk --file ./bank-app.apk
+guard aegis list --details
+guard aegis job --package com.bank.app
+guard aegis job --package com.bank.app -c android-device-survey -e <endpoint-id>
 ```
 
+A mobile capability runs on an enrolled Aegis v2 endpoint, named with `--endpoint` from
+the IDs in `guard aegis list --details`. The target is the application rather than the
+device, so the findings are filed on the `#apk#<package>` asset. Pinning a job to a
+specific endpoint is reserved for Praetorian users: for everyone else Guard drops the pin
+and selects an endpoint automatically.
+
 # Developers
 
 Both CLI and SDK is open-source in this repository. The SDK is installed along with the `praetorian-cli`

{praetorian_cli-2.6.2 → praetorian_cli-2.6.3}/README.md

@@ -502,8 +502,20 @@ guard run installed
 guard engagement list
 guard engagement create-customer --email ops@acme.com --name "ACME Corp"
 guard engagement create-vault --client acme --sow SOW-1234 --sku WAPT --github-user jdoe
+
+# Mobile testing: upload an APK, then run a capability against it on a device
+guard add apk --file ./bank-app.apk
+guard aegis list --details
+guard aegis job --package com.bank.app
+guard aegis job --package com.bank.app -c android-device-survey -e <endpoint-id>
 ```
 
+A mobile capability runs on an enrolled Aegis v2 endpoint, named with `--endpoint` from
+the IDs in `guard aegis list --details`. The target is the application rather than the
+device, so the findings are filed on the `#apk#<package>` asset. Pinning a job to a
+specific endpoint is reserved for Praetorian users: for everyone else Guard drops the pin
+and selects an endpoint automatically.
+
 # Developers
 
 Both CLI and SDK is open-source in this repository. The SDK is installed along with the `praetorian-cli`

{praetorian_cli-2.6.2 → praetorian_cli-2.6.3}/praetorian_cli/handlers/add.py

@@ -195,11 +195,10 @@ def webhook(sdk):
               help='Existing asset key, hostname, IP, or friendly name')
 @click.option('-s', '--status', type=click.Choice([s.value for s in AddRisk]), required=True,
               help=f'Status of the risk')
-@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')
 @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):
+def risk(sdk, name, asset, status, capability, title, tags):
     """ Add a risk
 
     This command adds a risk to Guard. A risk must have an associated asset.
@@ -218,7 +217,33 @@ def risk(sdk, name, asset, status, comment, capability, title, tags):
         - guard add risk CVE-2024-23049 --asset "#asset#example.com#1.2.3.4" --status TI --tag critical --tag needs-review
     """
     asset_key = resolve_entity_reference(sdk, asset, 'asset')
-    sdk.risks.add(asset_key, name, status, comment, capability, title, tags)
+    sdk.risks.add(asset_key, name, status, capability, title, tags)
+
+
+@add.command()
+@cli_handler
+@click.option('-f', '--file', 'local_filepath', required=True,
+              type=click.Path(exists=True, dir_okay=False),
+              help='Path to the local .apk file')
+@click.option('-n', '--name', 'chariot_filepath',
+              help='Destination path in Guard storage. Defaults to the file name.')
+def apk(sdk, local_filepath, chariot_filepath):
+    """ Upload an Android APK and register it as an asset
+
+    Uploads the APK and registers it, creating an asset keyed '#apk#<package>'. The
+    package name is read from the APK's own manifest rather than supplied, so
+    re-uploading a newer build of the same application updates that asset instead of
+    creating a second one.
+
+    \b
+    Example usages:
+        - guard add apk --file ./bank-app.apk
+        - guard add apk --file ./bank-app.apk --name engagements/acme/bank-app.apk
+    """
+    result = sdk.apks.add(local_filepath, chariot_filepath)
+    key = result.get('key', '')
+    version = result.get('versionName', '')
+    click.echo(f"Registered {key}" + (f" (version {version})" if version else ""))
 
 
 @add.command()

{praetorian_cli-2.6.2 → praetorian_cli-2.6.3}/praetorian_cli/handlers/aegis.py

@@ -1,6 +1,7 @@
 import click
 from praetorian_cli.handlers.chariot import chariot
 from praetorian_cli.handlers.cli_decorators import cli_handler
+from praetorian_cli.sdk.model.aegis import is_v2_agent
 from praetorian_cli.ui.aegis.commands.enrollment import (
     enrollment_error_message,
     pending_enrollment_lines,
@@ -339,25 +340,62 @@ def _raise_network_policy_error(exc):
 
 @aegis.command('job')
 @cli_handler
-@click.option('-c', '--capability', 'capabilities', multiple=True, help='Capability to run (e.g., windows-smb-snaffler)')
+@click.option('-c', '--capability', 'capabilities', multiple=True,
+              help='Capability to run (e.g., windows-smb-snaffler, android-device-survey)')
 @click.option('--config', help='JSON configuration string for the job')
-@click.argument('client_id', required=True)
+@click.option('-p', '--package',
+              help='Android application ID to target, e.g. com.bank.app. Upload the APK first with "guard add apk".')
+@click.option('-e', '--endpoint', 'endpoint_id',
+              help='Enrolled Aegis v2 endpoint to run the job on, as shown by "guard aegis list --details"')
+@click.argument('client_id', required=False)
 @click.pass_context
-def job(ctx, sdk, capabilities, config, client_id):
-    """Run a job on an Aegis agent"""
-    agent = sdk.aegis.get_by_client_id(client_id)
-    if not agent:
-        click.echo(f"Agent not found: {client_id}", err=True)
-        return
-    
+def job(ctx, sdk, capabilities, config, package, endpoint_id, client_id):
+    """Run a job on an Aegis agent or an enrolled endpoint
+
+    Name the target with either CLIENT_ID, for an agent's own host, or --package, for
+    an Android application already registered with "guard add apk". Without -c, the
+    capabilities available for that target are listed instead of a job being run.
+
+    \b
+    Example usages:
+        - guard aegis job C.6e012b467f9faf82-OG9F0 -c linux-enum
+        - guard aegis job --package com.bank.app
+        - guard aegis job --package com.bank.app -c android-device-survey -e 16169bc5-7943-4783-af81-c4735616f7e9
+        - guard aegis job --package com.bank.app -c android-device-command -e 16169bc5-7943-4783-af81-c4735616f7e9 --config '{"command": "getprop ro.build.fingerprint"}'
+    """
+    if client_id and package:
+        raise click.UsageError('A job has one target: pass either CLIENT_ID or --package, not both.')
+
+    if not client_id and not package:
+        raise click.UsageError('No target. Pass an agent CLIENT_ID, or --package to target an APK.')
+
+    agent = None
+    if client_id:
+        agent = sdk.aegis.get_by_client_id(client_id)
+        if not agent:
+            raise click.ClickException(f"Agent not found: {client_id}")
+        # CLIENT_ID names a legacy agent's host. A v2 endpoint has no host target on this
+        # path and is only ever reached through the --endpoint pin, so refuse here rather
+        # than hand the SDK a bare hostname that would lose the agent's v2 identity.
+        if is_v2_agent(agent):
+            endpoint = getattr(agent, 'endpoint_id', None) or '<endpoint id>'
+            raise click.UsageError(
+                f'{client_id} is an Aegis v2 endpoint, which the legacy job path cannot target. '
+                f'To run a mobile capability on it, pass --package <application id> -e {endpoint}.')
+
     try:
         result = sdk.aegis.run_job(
             agent,
-            list(capabilities) if capabilities else None,
-            config
+            capabilities=list(capabilities) if capabilities else None,
+            package=package,
+            endpoint_id=endpoint_id,
+            config=config,
         )
 
         if 'capabilities' in result:
+            if not result['capabilities']:
+                click.echo('No capabilities available for this target.')
+                return
             click.echo("Available capabilities:")
             for cap in result['capabilities']:
                 name = cap.get('name', 'unknown')
@@ -366,6 +404,9 @@ def job(ctx, sdk, capabilities, config, client_id):
         elif result.get('success'):
             click.echo("✓ Job queued successfully")
             click.echo(f"  Job ID: {result.get('job_id', 'unknown')}")
+            click.echo(f"  Target: {result.get('target_key', 'unknown')}")
+            if result.get('endpoint_id'):
+                click.echo(f"  Endpoint: {result['endpoint_id']}")
             click.echo(f"  Status: {result.get('status', 'unknown')}")
         else:
             click.echo("Error: Unknown error", err=True)

{praetorian_cli-2.6.2 → praetorian_cli-2.6.3}/praetorian_cli/handlers/update.py

@@ -67,10 +67,9 @@ def credential_active_directory(sdk, credential_id, endpoint_ids):
 @click.argument('key', required=True)
 @click.option('-s', '--status', type=click.Choice([s.value for s in Risk]), help=f'Status of the risk')
 @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')
 @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):
+def risk(chariot, key, status, comment, title, tags):
     """ Update the status and comment of a risk
 
     \b
@@ -81,15 +80,10 @@ def risk(chariot, key, status, comment, remove_comment, title, tags):
     Example usages:
         - guard update risk "#risk#www.example.com#CVE-2024-23049" --status OH --comment "Open it as a high severity risk"
         - 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")
-
     key = resolve_entity_reference(chariot, key, 'risk')
-    chariot.risks.update(key, status, comment, remove_comment, title, tags)
+    chariot.risks.update(key, status, comment, title, tags)
 
 
 @update.command()

{praetorian_cli-2.6.2 → praetorian_cli-2.6.3}/praetorian_cli/sdk/chariot.py

@@ -5,6 +5,7 @@ from praetorian_cli.sdk.entities.ad import AD
 from praetorian_cli.sdk.entities.aegis import Aegis
 from praetorian_cli.sdk.entities.agents import Agents
 from praetorian_cli.sdk.entities.assets import Assets
+from praetorian_cli.sdk.entities.apks import Apks
 from praetorian_cli.sdk.entities.attributes import Attributes
 from praetorian_cli.sdk.entities.capabilities import Capabilities
 from praetorian_cli.sdk.entities.configurations import Configurations
@@ -70,6 +71,7 @@ class Chariot:
         self.schema = Schema(self)
         self.schedules = Schedules(self)
         self.vms = EngineerVms(self)
+        self.apks = Apks(self)
         self.proxy = proxy
 
         if self.proxy == '' and os.environ.get('CHARIOT_PROXY'):

{praetorian_cli-2.6.2 → praetorian_cli-2.6.3}/praetorian_cli/sdk/entities/aegis.py

@@ -1,13 +1,13 @@
 from typing import List, Optional
-from urllib.parse import quote
+import json
 import logging
+from urllib.parse import quote
 import shlex
 import shutil
 import subprocess
 import time
 from praetorian_cli.sdk.model.aegis import Agent, is_v2_agent, validate_agent_for_ssh
 
-
 def normalize_to_list(value, item_keys: List[str] = None) -> List:
     keys = item_keys or ["items", "data", "capabilities", "assets"]
     if value is None:
@@ -115,6 +115,10 @@ CLOUDFLARE_TUNNEL_STATUS_PATH = 'aegis/management/cloudflare/tunnel/status/{endp
 CLOUDFLARE_TUNNEL_CREATE_PATH = 'aegis/management/cloudflare/tunnel/create'
 CLOUDFLARE_TUNNEL_REMOVE_PATH = 'aegis/management/cloudflare/tunnel/remove'
 ENDPOINT_PIN_CONFIG_KEY = 'endpoint_agent_id'
+# The endpoint kind that runs Aegis capabilities, mobile ones included.
+ENDPOINT_KIND_AEGIS = 'aegis'
+# Connection state in which an endpoint can pick up work.
+ENDPOINT_STATE_ONLINE = 'online'
 LINUX_SYSTEM_ADDUSER = 'linux-system-adduser'
 LINUX_SYSTEM_DELUSER = 'linux-system-deluser'
 
@@ -412,17 +416,29 @@ class Aegis:
             ),
         )
 
-    def get_capabilities(self, surface_filter: str = None, agent_os: str = None) -> List[dict]:
+    def get_capabilities(self, surface_filter: str = None, agent_os: str = None,
+                         target: str = None, endpoint_kind: str = None,
+                         executor: str = 'aegis') -> List[dict]:
         """
         Get Aegis capabilities with optional filtering.
 
         Retrieves available capabilities that can be executed by Aegis agents,
         with optional filtering by attack surface and operating system.
 
-        :param surface_filter: Filter by attack surface type (e.g., 'internal', 'external')
+        :param surface_filter: Filter by attack surface type (e.g., 'internal', 'external', 'mobile')
         :type surface_filter: str or None
         :param agent_os: Filter by agent operating system (e.g., 'windows', 'linux')
         :type agent_os: str or None
+        :param target: Filter by target type (e.g., 'asset', 'addomain', 'apk')
+        :type target: str or None
+        :param endpoint_kind: Filter to capabilities dispatchable to an enrolled endpoint of
+            this kind (e.g., 'aegis')
+        :type endpoint_kind: str or None
+        :param executor: Filter by executor. Defaults to 'aegis', which is the executor for
+            capabilities that run on an SSH-reachable Aegis agent. Endpoint-dispatched
+            capabilities -- including every mobile one -- are registered against Guard's own
+            executor instead, so pass '' to include them.
+        :type executor: str
         :return: List of capability dictionaries
         :rtype: list
 
@@ -436,6 +452,9 @@ class Aegis:
             >>> # Get Windows capabilities for internal surface
             >>> win_caps = sdk.aegis.get_capabilities(surface_filter='internal', agent_os='windows')
 
+            >>> # Get the mobile capabilities dispatchable to an enrolled Android endpoint
+            >>> mobile_caps = sdk.aegis.get_capabilities(target='apk', endpoint_kind='aegis', executor='')
+
         **Capability Object Properties:**
             Each capability contains:
             - name: Capability name (e.g., 'windows-smb-snaffler')
@@ -445,7 +464,8 @@ class Aegis:
             - parameters: List of configurable parameters
         """
         try:
-            capabilities_response = self.api.capabilities.list(executor='aegis')
+            capabilities_response = self.api.capabilities.list(
+                target=target or '', executor=executor or '', endpoint_kind=endpoint_kind or '')
             
             # Handle different response formats
             if isinstance(capabilities_response, tuple):
@@ -829,30 +849,88 @@ class Aegis:
         else:
             print(f"\033[31m✗ Transfer failed (exit code {returncode})\033[0m")
 
-    def run_job(self, agent: Agent, capabilities: list = None, config: str = None):
+    def run_job(self, agent: Agent = None, capabilities: list = None, config: str = None,
+                hostname: str = None, package: str = None, endpoint_id: str = None) -> dict:
         """
-        Run a job on an Aegis agent.
+        Run a job on an Aegis agent or on an enrolled endpoint.
+
+        Name the target with a hostname, for an agent's own host asset, or with a package,
+        for an Android application already registered by sdk.apks.add(). A package targets
+        '#apk#<package>' -- what every mobile capability matches against, and the asset its
+        findings are filed on.
+
+        An Aegis v2 endpoint runs the job only when endpoint_id names it. The endpoint is
+        not taken from a v2 agent automatically: dispatching to a device is a decision the
+        caller makes rather than a consequence of which row they had selected.
+
+        Apart from the legacy agent argument, every parameter is a string or a list, so
+        this method is callable over the MCP server as well as from Python. There is no
+        second code path for MCP.
+
+        :param agent: Agent object from sdk.aegis.list(), naming a v1 agent's host as the
+            target. Prefer hostname; this exists so existing positional callers keep working.
+        :type agent: Agent or None
+        :param capabilities: Capability names to run. When omitted, no job is created and
+            the capabilities available for the named target are returned instead.
+        :type capabilities: list or None
+        :param config: JSON object string of capability parameters, e.g.
+            '{"command": "getprop ro.build.fingerprint"}'
+        :type config: str or None
+        :param hostname: Hostname of an Aegis agent, to target that agent's host asset
+        :type hostname: str or None
+        :param package: Android application ID, e.g. 'com.bank.app', to target '#apk#<package>'
+        :type package: str or None
+        :param endpoint_id: Enrolled Aegis v2 endpoint to run the job on, as shown by
+            "guard aegis list --details". Passed to Guard as the job's endpoint_agent_id.
+            Guard reserves that key for Praetorian users and silently drops it for everyone
+            else, in which case the job falls back to automatic endpoint selection.
+        :type endpoint_id: str or None
+        :return: When capabilities are given, a dict with 'success', 'job_id', 'job_key',
+            'status', 'target_key' and 'endpoint_id'. Otherwise a dict with 'capabilities'.
+        :rtype: dict
+        :raises Exception: If no target is named, if two are, if a v2 agent is named without
+            an endpoint_id, or if the named endpoint is not enrolled, connected and accepting work
+
+        **Example Usage:**
+            >>> # What can run against an APK on an enrolled endpoint
+            >>> sdk.aegis.run_job(package='com.bank.app')
 
-        If no capabilities are provided, returns available capability dicts under
-        the 'capabilities' key. When capabilities are provided, returns a dict
-        with keys: 'success', 'job_id', 'job_key', 'status'. Errors raise.
+            >>> # Dispatch a mobile capability to a named device
+            >>> sdk.aegis.run_job(capabilities=['android-device-survey'],
+            >>>                   package='com.bank.app',
+            >>>                   endpoint_id='16169bc5-7943-4783-af81-c4735616f7e9')
+
+            >>> # Dispatch a host capability to an Aegis agent, as before
+            >>> sdk.aegis.run_job(capabilities=['linux-enum'], hostname='agent01')
         """
-        if is_v2_agent(agent):
+        # A v2 endpoint is reached only through the pin. Without one this is the legacy
+        # path, which has no way to route to a device, so it refuses rather than quietly
+        # running the job somewhere else.
+        if is_v2_agent(agent) and not endpoint_id:
             raise Exception(
                 "Aegis v2 endpoint job execution is not supported by the legacy "
                 "Aegis job path; refusing to run without endpoint_agent_id"
             )
 
+        if agent is not None and not hostname and not package and not is_v2_agent(agent):
+            hostname = agent.hostname or 'unknown'
+
+        if hostname and package:
+            raise Exception('A job has one target: pass either hostname or package, not both.')
+
         if not capabilities:
-            caps = self.get_capabilities(surface_filter='internal')
-            return {
-                'capabilities': sorted(caps, key=lambda x: x.get('name', '')),
-            }
+            return {'capabilities': sorted(self._offerable_capabilities(package, endpoint_id),
+                                           key=lambda capability: capability.get('name', ''))}
+
+        target_key = self._target_key(hostname, package)
 
-        hostname = agent.hostname or 'unknown'
-        target_key = f"#asset#{hostname}#{hostname}"
+        # Checked before the job is created, not after. Guard queues a job for an endpoint
+        # that cannot run it just as readily as for one that can, and the job then sits at
+        # its initial status with nothing saying why -- which reads as a silent success.
+        if endpoint_id:
+            self._verify_endpoint_can_accept_work(endpoint_id)
 
-        jobs = self.api.jobs.add(target_key, list(capabilities), config)
+        jobs = self.api.jobs.add(target_key, list(capabilities), self._job_config(config, endpoint_id))
         if not jobs:
             raise Exception("No job returned from API")
 
@@ -865,8 +943,75 @@ class Aegis:
             'job_id': job_key.split('#')[-1][:12] if job_key else 'unknown',
             'job_key': job_key,
             'status': status,
+            'target_key': target_key,
+            'endpoint_id': endpoint_id or '',
         }
-    
+
+    def _offerable_capabilities(self, package: str = None, endpoint_id: str = None) -> List[dict]:
+        """Capabilities worth offering for the target the caller has named.
+
+        An APK target gets the capabilities registered against APKs and dispatchable to an
+        enrolled endpoint, so a host capability is never offered for an application. With
+        no target named, the host capabilities are listed as before.
+        """
+        if package:
+            return self.get_capabilities(target='apk', endpoint_kind=ENDPOINT_KIND_AEGIS, executor='')
+        if endpoint_id:
+            return self.get_capabilities(endpoint_kind=ENDPOINT_KIND_AEGIS, executor='')
+        return self.get_capabilities(surface_filter='internal')
+
+    @staticmethod
+    def _target_key(hostname: str = None, package: str = None) -> str:
+        if package:
+            return f"#apk#{package}"
+        if hostname:
+            return f"#asset#{hostname}#{hostname}"
+        raise Exception('No target for the job. Pass hostname to target an Aegis agent, or '
+                        'package to target an APK, e.g. package="com.bank.app".')
+
+    def _endpoint_row(self, endpoint_id: str) -> Optional[dict]:
+        """The durable inventory row for one endpoint, or None if it is not enrolled."""
+        for row in self._list_endpoint_inventory_rows():
+            if _endpoint_row_id(row) == endpoint_id:
+                return row
+        return None
+
+    def _verify_endpoint_can_accept_work(self, endpoint_id: str) -> dict:
+        endpoint = self._endpoint_row(endpoint_id)
+        if endpoint is None:
+            raise Exception(f'Endpoint "{endpoint_id}" is not enrolled. '
+                            f'Run "guard aegis list --details" to see the enrolled endpoints.')
+
+        state = endpoint.get('connectionState') or 'unknown'
+        if state != ENDPOINT_STATE_ONLINE:
+            raise Exception(f'Endpoint "{endpoint_id}" is {state}, so it cannot pick up this job. '
+                            f'Bring the device back online and try again.')
+
+        if endpoint.get('taskDispatchPaused'):
+            raise Exception(f'Endpoint "{endpoint_id}" is online but has task dispatch paused, '
+                            f'so it would not pick up this job.')
+
+        return endpoint
+
+    @staticmethod
+    def _job_config(config: str = None, endpoint_id: str = None) -> Optional[str]:
+        """Merge the endpoint pin into the caller's config, without losing what they set."""
+        merged = {}
+        if isinstance(config, dict):
+            merged = dict(config)
+        elif config and config.strip():
+            try:
+                merged = json.loads(config)
+            except json.JSONDecodeError as e:
+                raise Exception(f'config is not valid JSON: {e}')
+            if not isinstance(merged, dict):
+                raise Exception('config must be a JSON object, e.g. \'{"command": "id"}\'')
+
+        if endpoint_id:
+            merged[ENDPOINT_PIN_CONFIG_KEY] = endpoint_id
+
+        return json.dumps(merged) if merged else None
+
     def format_agents_list(self, details: bool = False, filter_text: str = None):
         """
         Format agents list for display with optional filtering and details.
@@ -928,3 +1073,4 @@ class Aegis:
             for i, agent in enumerate(agents_data, 1):
                 lines.append(f"{i:>4}  {agent.version:<7}  {(agent.hostname or 'Unknown')[:30]:<30}  {agent.display_id}")
             return warning_text + '\n'.join(lines)
+

praetorian_cli-2.6.3/praetorian_cli/sdk/entities/apks.py

@@ -0,0 +1,53 @@
+import os
+
+
+class Apks:
+    """ The methods in this class are to be accessed from sdk.apks, where sdk is an instance
+    of Chariot. """
+
+    def __init__(self, api):
+        self.api = api
+
+    def add(self, local_filepath: str, chariot_filepath: str = None) -> dict:
+        """
+        Upload an Android APK and register it as an asset.
+
+        This is two calls, because that is what Guard expects: the bytes go straight to
+        storage with a presigned PUT, then POST /apk registers the stored object as an
+        asset. No request carries the binary through the API.
+
+        The package name is not a parameter. It is read server-side from the APK's
+        AndroidManifest.xml, so the asset key is always '#apk#<package>' as declared by
+        the binary itself, and a caller cannot register an arbitrary identity for an
+        arbitrary file. Re-uploading a new build of the same app updates the existing
+        asset rather than forking a second one.
+
+        :param local_filepath: Path to the local .apk file to upload
+        :type local_filepath: str
+        :param chariot_filepath: Destination path in Guard storage. Defaults to the
+            local file's base name.
+        :type chariot_filepath: str or None
+        :return: The registered APK asset, including its key, package and version
+        :rtype: dict
+        :raises Exception: If the file is missing, is not named .apk, or does not hold a
+            readable Android manifest
+
+        **Example Usage:**
+            >>> apk = sdk.apks.add('./bank-app.apk')
+            >>> print(apk['key'])
+            #apk#com.bank.app
+        """
+        if not os.path.isfile(local_filepath):
+            raise Exception(f'APK not found: {local_filepath}')
+
+        if not chariot_filepath:
+            chariot_filepath = os.path.basename(local_filepath)
+
+        # POST /apk rejects an artifact_key that does not end in .apk, but only after
+        # the upload has already happened. Checking here means a mis-named file costs
+        # nothing instead of costing the whole transfer.
+        if not chariot_filepath.lower().endswith('.apk'):
+            raise Exception(f'the storage path must end in .apk, got "{chariot_filepath}"')
+
+        self.api.upload(local_filepath, chariot_filepath)
+        return self.api.post('apk', dict(artifact_key=chariot_filepath))