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

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

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

{praetorian_cli-2.6.0 → praetorian_cli-2.6.2}/praetorian_cli/handlers/delete.py

@@ -103,8 +103,9 @@ def seed(chariot, key):
 
 @delete.command()
 @click.argument('filepath', required=True)
+@click.option('--praetorian', is_flag=True, default=False, help='Delete from the praetorian partition')
 @cli_handler
-def file(chariot, filepath):
+def file(chariot, filepath, praetorian):
     """ Delete a file
 
     \b
@@ -114,8 +115,9 @@ def file(chariot, filepath):
     \b
     Example usage:
         - guard delete file "home/report-dec-2024.pdf"
+        - guard delete file "home/internal/repo.zip" --praetorian
     """
-    chariot.files.delete(filepath)
+    chariot.files.delete(filepath, praetorian=praetorian)
 
 
 @delete.command()

{praetorian_cli-2.6.0 → praetorian_cli-2.6.2}/praetorian_cli/handlers/get.py

@@ -131,7 +131,8 @@ def job(chariot, key):
 @cli_handler
 @click.argument('name')
 @click.option('-p', '--path', default=os.getcwd(), help='Download path. Default: save to current directory')
-def file(chariot, name, path):
+@click.option('--praetorian', is_flag=True, default=False, help='Download from the praetorian partition')
+def file(chariot, name, path, praetorian):
     """ Download a file using key or name
 
     \b
@@ -143,11 +144,11 @@ def file(chariot, name, path):
         - guard get file "#file#proofs/example.azurewebsites.net/jira-unauthenticated-user-picker"
         - guard get file "proofs/example.azurewebsites.net/jira-unauthenticated-user-picker"
         - guard get file "proofs/example.azurewebsites.net/jira-unauthenticated-user-picker" --path ~/Downloads
+        - guard get file "home/internal/repo.zip" --praetorian
     """
     if name.startswith('#'):
-        downloaded_filepath = chariot.files.save(name.split('#')[-1], path)
-    else:
-        downloaded_filepath = chariot.files.save(name, path)
+        name = name.split('#')[-1]
+    downloaded_filepath = chariot.files.save(name, path, praetorian=praetorian)
     click.echo(f'Saved file at {downloaded_filepath}')
 
 

{praetorian_cli-2.6.0 → praetorian_cli-2.6.2}/praetorian_cli/handlers/list.py

@@ -69,8 +69,9 @@ def accounts(chariot, filter, details, offset, page):
 
 
 @list.command()
-@list_params('Aegis ID', has_filter=False)
-def aegis(chariot, details, offset, page):
+@cli_handler
+@click.option('-d', '--details', is_flag=True, help='Show detailed agent information')
+def aegis(chariot, details):
     """ List Aegis
 
     Retrieve and display a list of Aegis instances.
@@ -79,9 +80,8 @@ def aegis(chariot, details, offset, page):
     Example usages:
         - guard list aegis
         - guard list aegis --details
-        - guard list aegis --page all
     """
-    render_list_results(chariot.aegis.list(offset, pagination_size(page)), details)
+    click.echo(chariot.aegis.format_agents_list(details=details))
 
 
 @list.command()
@@ -141,7 +141,8 @@ def jobs(chariot, capability, status, target, summary, filter, details, offset,
 
 @list.command()
 @list_params('file path')
-def files(chariot, filter, details, offset, page):
+@click.option('--praetorian', is_flag=True, default=False, help='List the praetorian partition')
+def files(chariot, praetorian, filter, details, offset, page):
     """ List files
 
     Retrieve and display a list of files in the Guard file system.
@@ -152,8 +153,9 @@ def files(chariot, filter, details, offset, page):
         - guard list files --filter "home/reports/cloud-assessment-2024-"
         - guard list files --details
         - guard list files --page all
+        - guard list files --praetorian --filter "home/internal/"
      """
-    render_list_results(chariot.files.list(filter, offset, pagination_size(page)), details)
+    render_list_results(chariot.files.list(filter, offset, pagination_size(page), praetorian=praetorian), details)
 
 
 @list.command()

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

@@ -250,7 +250,7 @@ class Chariot:
         process_failure(resp)
         return resp
 
-    def download(self, name: str, global_=False) -> bytes:
+    def download(self, name: str, global_=False, praetorian=False) -> bytes:
         params = dict(name=name)
         # Encrypted files have _encrypted/ prefix in the path. Encrypted files do not use presigned URLs.
         # Instead, they use the /encrypted-file endpoint that directly gets and puts content.
@@ -263,6 +263,8 @@ class Chariot:
         # Regular files, use presigned URLs
         if global_:
             params |= GLOBAL_FLAG
+        if praetorian:
+            params['praetorian'] = 'true'
 
         resp = self.chariot_request('GET', self.url('/file'), params=params)
         process_failure(resp)

{praetorian_cli-2.6.0 → praetorian_cli-2.6.2}/praetorian_cli/sdk/entities/account_discovery.py

@@ -97,7 +97,7 @@ def discover_aegis_accounts(sdk, on_progress=None) -> List[dict]:
                 metadata,
             )
         except Exception as e:
-            logger.debug('Agent check failed for %s: %s', account_email, e)
+            logger.warning('Agent inventory failed for %s: %s', account_email, e)
             return _PROBE_FAILED
         finally:
             with lock:
@@ -184,18 +184,29 @@ def _fetch_account_agents(base_url: str, headers: dict) -> Optional[List[dict]]:
         timeout=30,
     )
     if resp.status_code != 200:
-        logger.debug('Agent fetch returned status %d', resp.status_code)
-        return None
+        raise RuntimeError(f'HTTP {resp.status_code} from /agent/enhanced: {resp.text}')
     return resp.json() or []
 
 
-def _fetch_account_endpoints(base_url: str, headers: dict) -> Optional[List[dict]]:
-    identity_rows = _fetch_account_endpoint_identities(base_url, headers)
-    live_rows = _fetch_account_live_endpoints(base_url, headers)
+def _fetch_account_endpoints(base_url: str, headers: dict, on_warning=None) -> Optional[List[dict]]:
+    identity_rows = _fetch_account_source(
+        lambda: _fetch_account_endpoint_identities(base_url, headers, on_warning),
+        headers, 'v2 endpoint identities', on_warning,
+    )
+    live_rows = _fetch_account_source(
+        lambda: _fetch_account_live_endpoints(base_url, headers),
+        headers, 'v2 live endpoints', on_warning,
+    )
     if identity_rows is None and live_rows is None:
         return None
-    tunnel_rows = _fetch_account_tunnel_states(base_url, headers)
-    status_rows = _fetch_account_aegis_statuses(base_url, headers)
+    tunnel_rows = _fetch_account_source(
+        lambda: _fetch_account_tunnel_states(base_url, headers),
+        headers, 'v2 tunnel states', on_warning,
+    )
+    status_rows = _fetch_account_source(
+        lambda: _fetch_account_aegis_statuses(base_url, headers),
+        headers, 'v2 endpoint statuses', on_warning,
+    )
     return merge_aegis_endpoint_rows(
         identity_rows or [],
         live_rows or [],
@@ -204,8 +215,11 @@ def _fetch_account_endpoints(base_url: str, headers: dict) -> Optional[List[dict
     )
 
 
-def _fetch_account_endpoint_identities(base_url: str, headers: dict) -> Optional[List[dict]]:
-    inventory_rows = _fetch_account_endpoint_inventory(base_url, headers)
+def _fetch_account_endpoint_identities(base_url: str, headers: dict, on_warning=None) -> Optional[List[dict]]:
+    inventory_rows = _fetch_account_source(
+        lambda: _fetch_account_endpoint_inventory(base_url, headers),
+        headers, 'v2 durable endpoints', on_warning,
+    )
     if inventory_rows is not None:
         return inventory_rows
 
@@ -215,8 +229,7 @@ def _fetch_account_endpoint_identities(base_url: str, headers: dict) -> Optional
         timeout=30,
     )
     if resp.status_code != 200:
-        logger.debug('Endpoint identity fetch returned status %d', resp.status_code)
-        return None
+        raise RuntimeError(f'HTTP {resp.status_code} from /endpoint: {resp.text}')
     return [
         normalize_active_endpoint_summary(endpoint)
         for endpoint in _flatten_response(resp.json())
@@ -237,8 +250,7 @@ def _fetch_account_endpoint_inventory(base_url: str, headers: dict) -> Optional[
             timeout=30,
         )
         if resp.status_code != 200:
-            logger.debug('Endpoint inventory fetch returned status %d', resp.status_code)
-            return None
+            raise RuntimeError(f'HTTP {resp.status_code} from /endpoint/list: {resp.text}')
 
         body = resp.json()
         rows = normalize_to_list(body, ['endpoints', 'data', 'items'])
@@ -289,8 +301,7 @@ def _fetch_account_my_rows(base_url: str, headers: dict, key: str) -> Optional[L
             timeout=30,
         )
         if resp.status_code != 200:
-            logger.debug('%s fetch returned status %d', key, resp.status_code)
-            return None
+            raise RuntimeError(f'HTTP {resp.status_code} from /my ({key}): {resp.text}')
 
         body = resp.json()
         rows.extend(_flatten_response(body))
@@ -305,12 +316,36 @@ def _fetch_account_my_rows(base_url: str, headers: dict, key: str) -> Optional[L
         params = {'key': key, 'offset': serialized_offset}
 
 
-def _fetch_account_records(base_url: str, headers: dict) -> Optional[tuple[List[dict], List[dict]]]:
-    agents_data = _fetch_account_agents(base_url, headers)
-    endpoints_data = _fetch_account_endpoints(base_url, headers)
-    if agents_data is None or endpoints_data is None:
-        return None
-    return agents_data, endpoints_data
+def _fetch_account_source(fetch, headers: dict, source: str, on_warning=None):
+    try:
+        rows = fetch()
+        if rows is not None:
+            return rows
+        error = 'inventory unavailable or pagination incomplete'
+    except Exception as exc:
+        error = str(exc)
+    warn = on_warning if on_warning is not None else logger.warning
+    warn(f"Account {headers.get('account', '(current)')}: {source} failed: {error}. "
+         "Agent inventory may be incomplete.")
+    return None
+
+
+def _fetch_account_records(
+    base_url: str, headers: dict, on_warning=None,
+) -> Optional[tuple[List[dict], List[dict]]]:
+    """Keep available rows; return None if empty results cannot be confirmed."""
+    agents_data = _fetch_account_source(
+        lambda: _fetch_account_agents(base_url, headers),
+        headers, 'legacy agents', on_warning,
+    )
+    endpoints_data = _fetch_account_source(
+        lambda: _fetch_account_endpoints(base_url, headers, on_warning),
+        headers, 'v2 endpoints', on_warning,
+    )
+    if not agents_data and not endpoints_data:
+        if agents_data is None or endpoints_data is None:
+            return None
+    return agents_data or [], endpoints_data or []
 
 
 def _aegis_endpoint_rows(rows: List[dict]) -> List[dict]:
@@ -444,18 +479,22 @@ def _friendly_name_from_email(email: str) -> str:
     return name.title() if name else email
 
 
-def load_agents_for_accounts(sdk, selected_accounts: List[dict], on_progress=None) -> List[tuple]:
+def load_agents_for_accounts(
+    sdk, selected_accounts: List[dict], on_progress=None, on_warning=None,
+) -> tuple[List[tuple], List[str]]:
     """Load agents from multiple accounts concurrently with retry.
 
     Args:
         sdk: Chariot SDK instance
         selected_accounts: List of account info dicts from discover_aegis_accounts
         on_progress: Optional callback(checked: int, total: int, display_name: str)
+        on_warning: Optional callback(message: str) for incomplete or failed loads.
+            Defaults to logger.warning.
 
     Returns:
         Tuple of (agent_tuples, failed_account_names) where agent_tuples is
         a list of (Agent, account_info) tuples and failed_account_names is
-        a list of display names for accounts that failed after retry.
+        a list of display names for failed or incomplete empty accounts after retry.
     """
     base_url = sdk.keychain.base_url()
     auth_headers = dict(sdk.keychain.headers())
@@ -463,60 +502,62 @@ def load_agents_for_accounts(sdk, selected_accounts: List[dict], on_progress=Non
     checked = 0
     failed_accounts = []
     lock = threading.Lock()
+    warn = on_warning if on_warning is not None else logger.warning
 
-    def _load_one(acct, attempt=1, track_progress=True):
+    def _load_one(acct, attempt):
         nonlocal checked
         email = acct['account_email']
+        warnings = []
         try:
             headers = dict(auth_headers)
             headers['account'] = email
-            records = _fetch_account_records(base_url, headers)
+            records = _fetch_account_records(base_url, headers, on_warning=warnings.append)
             if records is None:
                 logger.debug('Agent load for %s failed (attempt %d)', email, attempt)
-                return None  # Signal failure (distinct from empty account)
+                return None, warnings
             agents_data, endpoints_data = records
             agents = [(Agent.from_dict(d), acct) for d in agents_data]
             agents.extend(
                 (Agent.from_endpoint_dict(d), acct) for d in endpoints_data
             )
-            return agents
+            return agents, warnings
         except Exception as e:
-            logger.debug('Agent load failed for %s: %s (attempt %d)', email, e, attempt)
-            return None
+            warnings.append(f'Account {email}: agent inventory failed (attempt {attempt}): {e}')
+            return None, warnings
         finally:
-            if track_progress:
+            if attempt == 1:
                 with lock:
                     checked += 1
                     if on_progress:
                         on_progress(checked, total, acct.get('display_name', email))
 
     results = []
-    retry_accounts = []
-    with ThreadPoolExecutor(max_workers=4) as executor:
-        futures = {executor.submit(_load_one, acct): acct for acct in selected_accounts}
-        for future in as_completed(futures):
-            result = future.result()
-            if result is None:
-                retry_accounts.append(futures[future])
-            else:
-                results.extend(result)
-
-    # Retry failed accounts once (don't double-count progress)
-    if retry_accounts:
-        logger.debug('Retrying %d failed account(s)', len(retry_accounts))
+    pending = selected_accounts
+    for attempt in (1, 2):
+        if attempt == 2:
+            logger.debug('Retrying %d failed account(s)', len(pending))
+        retry_accounts = []
         with ThreadPoolExecutor(max_workers=4) as executor:
-            futures = {executor.submit(_load_one, acct, 2, False): acct for acct in retry_accounts}
+            futures = {executor.submit(_load_one, acct, attempt): acct for acct in pending}
             for future in as_completed(futures):
-                result = future.result()
+                acct = futures[future]
+                result, warnings = future.result()
                 if result is None:
-                    acct = futures[future]
-                    with lock:
-                        failed_accounts.append(acct.get('display_name', acct['account_email']))
+                    if attempt == 1:
+                        retry_accounts.append(acct)
+                        # A successful retry must not leave a partial-load warning.
+                        continue
+                    failed_accounts.append(acct.get('display_name', acct['account_email']))
                 else:
                     results.extend(result)
+                for message in warnings:
+                    warn(message)
+        if not retry_accounts:
+            break
+        pending = retry_accounts
 
     if failed_accounts:
-        logger.warning('Failed to load agents for: %s', ', '.join(failed_accounts))
+        warn(f"Failed to load agents for: {', '.join(failed_accounts)}")
 
     # Sort deterministically by account name then hostname to avoid
     # non-deterministic ordering from concurrent thread completion.

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

@@ -1,5 +1,6 @@
 from typing import List, Optional
 from urllib.parse import quote
+import logging
 import shlex
 import shutil
 import subprocess
@@ -187,56 +188,54 @@ class Aegis:
         self.api = api
 
 
-    def list(self) -> tuple:
-        """
-        List all Aegis agents.
-
-        Retrieves all Aegis agents from the account, returning them as Agent
-        objects with detailed information including system specs, network
-        interfaces, and tunnel connectivity status.
-
-        :return: A tuple containing (list of Agent objects, None for compatibility)
-        :rtype: tuple
+    def list(self, *, on_warning=None) -> tuple[List[Agent], None]:
+        """List legacy and v2 agents independently, returning (agents, None).
 
-        **Example Usage:**
-            >>> # List all Aegis agents
-            >>> agents, _ = sdk.aegis.list()
-            
-            >>> # Check agent properties
-            >>> for agent in agents:
-            >>>     print(f"Agent: {agent.hostname}")
-            >>>     print(f"OS: {agent.os}")
-            >>>     print(f"Has tunnel: {agent.has_tunnel}")
-            >>>     print(f"Online: {agent.is_online}")
-
-        **Agent Object Properties:**
-            - client_id: Unique identifier for v1 agents
-            - endpoint_id: Unique identifier for v2 endpoints
-            - version: Aegis protocol version (v1 or v2)
-            - hostname: Agent hostname
-            - os: Operating system (e.g., 'linux', 'windows')  
-            - network_interfaces: List of NetworkInterface objects
-            - has_tunnel: Boolean indicating if Cloudflare tunnel is active
-            - is_online: Boolean indicating if agent is currently online
+        Send partial failures to on_warning(message), or the logger if omitted.
+        Raise RuntimeError if both inventories fail. A successful empty response
+        still counts as a loaded inventory.
         """
-        agents = self._list_legacy_agents()
-        agents.extend(self._list_endpoint_agents())
+        agents = []
+        errors = []
+        loaded = False
+        try:
+            agents.extend(self._list_legacy_agents())
+            loaded = True
+        except Exception as exc:
+            errors.append(f'Legacy Aegis inventory: {exc}')
+        try:
+            endpoints, endpoint_errors = self._list_endpoint_agents()
+            agents.extend(endpoints)
+            errors.extend(endpoint_errors)
+            loaded = True
+        except Exception as exc:
+            errors.append(f'Aegis v2 inventory: {exc}')
+
+        if not loaded:
+            raise RuntimeError('Failed to load Aegis inventories: ' + '; '.join(errors))
+        if errors:
+            message = 'Incomplete Aegis inventory: ' + '; '.join(errors)
+            warn = on_warning if on_warning is not None else logging.getLogger(__name__).warning
+            warn(message)
         return agents, None
 
     def _list_legacy_agents(self) -> List[Agent]:
         agents_data = self.api.get('/agent/enhanced')
         return [Agent.from_dict(agent_data) for agent_data in agents_data]
 
-    def _list_endpoint_agents(self) -> List[Agent]:
+    def _list_endpoint_agents(self) -> tuple[List[Agent], List[str]]:
+        errors = []
         try:
             identity_rows = self._list_endpoint_inventory_rows()
-        except Exception:
+        except Exception as exc:
+            errors.append(f'Aegis v2 durable inventory: {exc}')
             try:
                 identity_rows = self._list_active_endpoint_rows()
-            except Exception:
-                identity_rows = []
+            except Exception as exc:
+                errors.append(f'Aegis v2 active inventory: {exc}')
+                identity_rows = None
 
-        live_rows = []
+        live_rows = None
         tunnel_rows = []
         status_rows = []
         if hasattr(self.api, 'search'):
@@ -246,8 +245,9 @@ class Aegis:
                     endpoints_data,
                     ["endpoints", "endpointInfos", "endpointinfos", "data", "items"],
                 )
-            except Exception:
-                pass
+            except Exception as exc:
+                if identity_rows is None:
+                    errors.append(f'Aegis v2 live inventory: {exc}')
             try:
                 tunnel_rows, _ = self.api.search.by_key_prefix(
                     '#endpointaegistunnelstate#'
@@ -261,16 +261,15 @@ class Aegis:
             except Exception:
                 pass
 
-        try:
-            rows = merge_aegis_endpoint_rows(
-                identity_rows,
-                live_rows,
-                tunnel_rows,
-                status_rows,
-            )
-            return [Agent.from_endpoint_dict(endpoint) for endpoint in rows]
-        except Exception:
-            return []
+        if identity_rows is None and live_rows is None:
+            raise RuntimeError('; '.join(errors))
+        rows = merge_aegis_endpoint_rows(
+            identity_rows or [],
+            live_rows or [],
+            tunnel_rows,
+            status_rows,
+        )
+        return [Agent.from_endpoint_dict(endpoint) for endpoint in rows], errors
 
     def list_hunt_endpoints(self) -> List[Agent]:
         """List active tenant-owned Aegis v2 identities for Internal Hunts."""
@@ -892,10 +891,15 @@ class Aegis:
             >>> result = sdk.aegis.format_agents_list(details=True, filter_text="windows")
             >>> print(result)
         """
-        agents_data, _ = self.list()
-        
+        warnings = []
+        agents_data, _ = self.list(on_warning=warnings.append)
+        warning_text = ''.join(f'Warning: {message}\n' for message in warnings)
+
         if not agents_data:
-            return "No agents found."
+            return warning_text + (
+                'No agents returned from available inventories.'
+                if warnings else 'No agents found.'
+            )
         
         if filter_text:
             filter_lower = filter_text.lower()
@@ -907,7 +911,7 @@ class Aegis:
             ]
 
         if not agents_data:
-            return f"No agents found matching filter: {filter_text}"
+            return warning_text + f"No agents found matching filter: {filter_text}"
         
         if details:
             detailed_lines = []
@@ -918,9 +922,9 @@ class Aegis:
                 if lines:
                     lines[0] = f"[{i:2d}] {lines[0].lstrip()}"
                 detailed_lines.append('\n'.join(lines))
-            return '\n\n'.join(detailed_lines)
+            return warning_text + '\n\n'.join(detailed_lines)
         else:
             lines = [f"{'#':>4}  {'VERSION':<7}  {'HOSTNAME':<30}  ID"]
             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 '\n'.join(lines)
+            return warning_text + '\n'.join(lines)