praetorian-cli 2.2.3__py3-none-any.whl → 2.2.5__py3-none-any.whl

praetorian_cli/sdk/entities/webpage.py

@@ -0,0 +1,180 @@
+from praetorian_cli.sdk.model.query import Query, Node, Filter, Relationship
+
+
+class Webpage:
+    """The methods in this class are to be accessed from sdk.webpage, where sdk
+    is an instance of Chariot."""
+
+    def __init__(self, api):
+        self.api = api
+
+    def add(self, url, parent_key=None):
+        """
+        Add a Webpage to the Chariot database.
+
+        WebPages represent individual pages or endpoints that can be optionally
+        associated with a parent WebApplication. The backend uses a WebpageRequest
+        structure with embedded webpage data and optional parent key.
+
+        :param url: The full URL of the page
+        :type url: str
+        :param parent_key: Optional key of the parent WebApplication 
+        :type webapp_key: str or None
+        :return: The created WebPage object
+        :rtype: dict
+        :raises Exception: If the URL is invalid or the request fails
+
+        **Example Usage:**
+            >>> # Add a simple page without parent
+            >>> page = sdk.webpage.add("https://app.example.com/login")
+
+            >>> # Add a page with parent WebApplication
+            >>> page = sdk.webpage.add(
+            ...     url="https://app.example.com/admin",
+            ...     parent_key="#webapplication#https://app.example.com")
+
+        **WebPage Object Structure:**
+            The returned Webpage object contains:
+            - key: Webpage identifier in format #webpage#{url}
+            - url: Full URL of the page
+            - status: Current status
+            - parent: Parent WebApplication relationship (if applicable)
+            - created: Creation timestamp
+        """
+        if not url:
+            raise Exception("URL is required for Webpage")
+
+        if parent_key and not parent_key.startswith('#webapplication#'):
+            raise Exception("Invalid WebApplication key format")
+
+        payload = {
+            'webpage': {
+                'url': url,
+                'status': 'A'  # Active status
+            }
+            
+        }
+
+        if parent_key:
+            payload['parent_key'] = parent_key
+
+        return self.api.post('webpage', payload)
+
+    def get(self, key):
+        """
+        Get details of a specific Webpage by its key.
+
+        :param key: The WebPage key identifier
+        :type key: str
+        :return: Webpage object with detailed information, or None if not found
+        :rtype: dict or None
+
+        **Example Usage:**
+            >>> # Get a specific Webpage
+            >>> page = sdk.webpage.get("webpage_key_123")
+
+        **Webpage Object Structure:**
+            The returned Webpage object contains:
+            - key: Webpage identifier
+            - url: Full URL of the page
+            - created: Creation timestamp
+            - updated: Last update timestamp
+        """
+        query = Query(node=Node(labels=[Node.Label.WEBPAGE], filters=[Filter(field=Filter.Field.KEY, operator=Filter.Operator.EQUAL, value=key)]))
+        return self.api.search.by_query(query)[0][0]
+
+    def list(self, parent_key=None, filter=None, offset=0, pages=100000) -> tuple:
+        """
+        List Webpages, optionally filtered by parent WebApplication.
+
+        Retrieve Webpage entities with optional filtering capabilities. Can filter by
+        parent WebApplication.
+
+        :param parent_key: Filter pages by specific WebApplication (optional)
+        :type parent_key: str or None
+        :param filter: Filter pages by specific URL (optional)
+        :type filter: str or None
+        :param offset: The offset for pagination to retrieve a specific page of results
+        :type offset: str or None
+        :param pages: Maximum number of pages to retrieve (default: 100000 for all results)
+        :type pages: int
+        :return: A tuple containing (list of matching Webpages, next page offset)
+        :rtype: tuple
+
+        **Example Usage:**
+            >>> # List all WebPages
+            >>> pages, offset = sdk.webpage.list()
+
+            >>> # List pages for specific WebApplication
+            >>> pages, offset = sdk.webpage.list(
+            ...     webapp_key="#asset#webapp#https://app.example.com#https://app.example.com")
+
+        **WebPage Filtering:**
+            - parent_key: Filters by parent WebApplication
+            - filter: Filters by specific URL
+        """
+        if parent_key and not parent_key.startswith('#webapplication#'):
+            raise Exception("Invalid WebApplication key format")
+
+        relationships = []
+        filters = []
+        if parent_key:
+            parentFilter = Filter(field=Filter.Field.KEY, operator=Filter.Operator.EQUAL, value=parent_key)
+            relationship = Relationship(label=Relationship.Label.HAS_WEBPAGE, target=Node(labels=[Node.Label.WEBAPPLICATION], filters=[parentFilter]))
+            relationships.append(relationship)
+        if filter:
+            urlFilter = Filter(field=Filter.Field.KEY, operator=Filter.Operator.CONTAINS, value=filter)
+            filters.append(urlFilter)
+        node = Node(labels=[Node.Label.WEBPAGE], filters=filters, relationships=relationships)
+        query = Query(node=node, page=offset, limit=pages)
+        return self.api.search.by_query(query, pages)
+
+    def delete(self, key):
+        """
+        Delete a webpage by its key.
+
+        :param key: The WebPage key identifier
+        :type key: str
+        """
+        body = {
+            'webpage': {
+                'key': key
+            }
+        }
+        self.api.delete('webpage', params={}, body=body)
+
+    def link_source(self, webpage_key, entity_key):
+        """
+        Link a file or repository to a webpage as source code.
+
+        :param webpage_key: The webpage key in format #webpage#{url}
+        :type webpage_key: str
+        :param entity_key: The entity key (file or repository) to link. Format: #file#{path} or #repository#{url}#{name}
+        :type entity_key: str
+        :return: The updated webpage with linked artifacts
+        :rtype: dict
+        """
+        data = {
+            'webpageKey': webpage_key,
+            'entityKey': entity_key
+        }
+        
+        return self.api.put('webpage/link', data, {})
+
+    def unlink_source(self, webpage_key, entity_key):
+        """
+        Unlink a file or repository from a webpage's source code.
+
+        :param webpage_key: The webpage key in format #webpage#{url}
+        :type webpage_key: str
+        :param entity_key: The entity key (file or repository) to unlink. Format: #file#{path} or #repository#{url}#{name}
+        :type entity_key: str
+        :return: The updated webpage with artifacts removed
+        :rtype: dict
+        """
+        data = {
+            'webpageKey': webpage_key,
+            'entityKey': entity_key
+        }
+    
+        return self.api.delete('webpage/link', data, {})

praetorian_cli/sdk/model/globals.py

@@ -108,7 +108,10 @@ class Kind(Enum):
     SEED = 'seed'
     PRESEED = 'preseed'
     OTHERS = 'others'
+    WEBAPPLICATION = 'webapplication'
+    WEBPAGE = 'webpage'
 
 EXACT_FLAG = {'exact': 'true'}
 DESCENDING_FLAG = {'desc': 'true'}
 GLOBAL_FLAG = {'global': 'true'}
+USER_FLAG = {'user': 'true'}

praetorian_cli/sdk/model/query.py

@@ -49,6 +49,8 @@ class Filter:
         KEV = 'kev'
         EXPLOIT = 'exploit'
         PRIVATE = 'private'
+        PRIMARY_URL = 'primary_url'
+        URL = 'url'
 
     def __init__(self, field: Field, operator: Operator, value: str, not_: bool = False):
         self.field = field
@@ -65,6 +67,7 @@ class Relationship:
         HAS_VULNERABILITY = 'HAS_VULNERABILITY'
         DISCOVERED = 'DISCOVERED'
         HAS_ATTRIBUTE = 'HAS_ATTRIBUTE'
+        HAS_WEBPAGE = 'HAS_WEBPAGE'
 
     def __init__(self, label: Label, source: 'Node' = None, target: 'Node' = None, optional: bool = False, length: int = 0):
         self.label = label
@@ -97,6 +100,8 @@ class Node:
         PRESEED = 'Preseed'
         SEED = 'Seed'
         TTL = 'TTL'
+        WEBAPPLICATION = 'WebApplication'
+        WEBPAGE = 'Webpage'
 
     def __init__(self, labels: list[Label] = None, filters: list[Filter] = None,
                  relationships: list[Relationship] = None):
@@ -157,6 +162,8 @@ KIND_TO_LABEL = {
     Kind.REPOSITORY.value: Node.Label.REPOSITORY,
     Kind.INTEGRATION.value: Node.Label.INTEGRATION,
     Kind.ADDOMAIN.value: Node.Label.ADDOMAIN,
+    Kind.WEBAPPLICATION.value: Node.Label.WEBAPPLICATION,
+    Kind.WEBPAGE.value: Node.Label.WEBPAGE,
 }
 
 

praetorian_cli/sdk/test/test_asset.py

@@ -71,11 +71,47 @@ class TestAsset:
         deleted_assets, _ = self.sdk.search.by_status(Asset.DELETED.value, Kind.ADDOMAIN.value)
         assert any([a['key'] == self.ad_domain_key for a in deleted_assets])
 
+    def test_add_webapplication(self):
+        asset = self.sdk.assets.add(self.webapp_name, self.webapp_url, status=Asset.ACTIVE.value, surface='test-surface', type=Kind.WEBAPPLICATION.value)
+        assert asset['key'] == self.webapp_key
+        assert len(asset['attackSurface']) == 1
+        assert 'test-surface' in asset['attackSurface']
+        assert asset['status'] == Asset.ACTIVE.value
+    
+    def test_get_webapplication(self):
+        asset = self.sdk.assets.get(self.webapp_key)
+        assert asset['key'] == self.webapp_key
+        assert asset['group'] == self.webapp_name
+        assert asset['identifier'] == self.webapp_url
+        assert asset['status'] == Asset.ACTIVE.value
+    
+    def test_list_webapplication(self):
+        results, _ = self.sdk.assets.list(asset_type=Kind.WEBAPPLICATION.value)
+        assert len(results) > 0
+        assert any([a['key'] == self.webapp_key for a in results])
+        assert any([a['group'] == self.webapp_name for a in results])
+        assert any([a['identifier'] == self.webapp_url for a in results])
+    
+    def test_update_webapplication(self):
+        self.sdk.assets.update(self.webapp_key, status=Asset.FROZEN.value, surface='abc')
+        asset = self.get_webapplication()
+        assert asset['status'] == Asset.FROZEN.value
+        assert 'abc' in asset['attackSurface']
+    
+    def test_delete_webapplication(self):
+        self.sdk.assets.delete(self.webapp_key)
+        assert self.get_webapplication()['status'] == Asset.DELETED.value
+        deleted_assets, _ = self.sdk.search.by_status(Asset.DELETED.value, Kind.WEBAPPLICATION.value)
+        assert any([a['key'] == self.webapp_key for a in deleted_assets])
+
     def get_asset(self):
         return self.sdk.assets.get(self.asset_key)
     
     def get_ad_domain(self):
         return self.sdk.assets.get(self.ad_domain_key)
 
+    def get_webapplication(self):
+        return self.sdk.assets.get(self.webapp_key)
+
     def teardown_class(self):
         clean_test_entities(self.sdk, self)

praetorian_cli/sdk/test/test_conversation.py

@@ -0,0 +1,195 @@
+import pytest
+import json
+import time
+
+from praetorian_cli.sdk.test.utils import make_test_values, clean_test_entities, setup_chariot
+
+
+@pytest.mark.coherence
+class TestConversation:
+    """Test conversation functionality with the Chariot agent"""
+
+    def setup_class(self):
+        self.sdk = setup_chariot()
+        make_test_values(self)
+        self.conversation_id = None
+        self.message_keys = []
+
+    def test_start_conversation(self):
+        """Test starting a new conversation with the agent"""
+        url = self.sdk.url("/planner")
+        payload = {
+            "message": f"Test conversation started at {int(time.time())}",
+            "mode": "query"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=payload)
+        
+        # Should get successful response
+        assert response.status_code == 200
+        
+        result = response.json()
+        assert "conversation" in result
+        assert "uuid" in result["conversation"]
+        
+        self.conversation_id = result["conversation"]["uuid"]
+        assert self.conversation_id is not None
+        assert len(self.conversation_id) > 0
+
+    def test_send_message_with_existing_conversation(self):
+        """Test sending a message to an existing conversation"""
+        # First, start a new conversation
+        url = self.sdk.url("/planner")
+        initial_payload = {
+            "message": f"Initial message for follow-up test at {int(time.time())}",
+            "mode": "query"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=initial_payload)
+        assert response.status_code == 200
+        
+        result = response.json()
+        conversation_id = result["conversation"]["uuid"]
+        
+        # Now send a follow-up message to the existing conversation
+        follow_up_payload = {
+            "message": f"Follow-up message in existing conversation at {int(time.time())}",
+            "mode": "query",
+            "conversationId": conversation_id
+        }
+        
+        response = self.sdk._make_request("POST", url, json=follow_up_payload)
+        
+        # Should get successful response
+        assert response.status_code == 200
+
+    def test_read_conversation_messages(self):
+        """Test reading messages from a conversation"""
+        # First, create a conversation and send a message
+        url = self.sdk.url("/planner")
+        payload = {
+            "message": f"Test message for reading at {int(time.time())}",
+            "mode": "query"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=payload)
+        assert response.status_code == 200
+        
+        result = response.json()
+        conversation_id = result["conversation"]["uuid"]
+        
+        # Wait a moment for message to be stored
+        time.sleep(2)
+        
+        # Now try to read messages from this conversation
+        messages, offset = self.sdk.search.by_key_prefix(
+            f"#message#{conversation_id}#", user=True
+        )
+        
+        # Should have at least the user message
+        assert isinstance(messages, list)
+        # Note: messages might be empty immediately after creation due to async processing
+        # This is still a valid test as it verifies the search functionality works
+
+    def test_read_conversations_list(self):
+        """Test reading list of conversations"""
+        # First create a test conversation
+        url = self.sdk.url("/planner")
+        payload = {
+            "message": f"Test conversation for listing at {int(time.time())}",
+            "mode": "query"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=payload)
+        assert response.status_code == 200
+        
+        # Wait a moment for conversation to be stored
+        time.sleep(1)
+        
+        # Now search for conversations
+        conversations, offset = self.sdk.search.by_key_prefix(
+            "#conversation#", user=True
+        )
+        
+        # Should be able to search for conversations (list might be empty or contain conversations)
+        assert isinstance(conversations, list)
+
+    def test_conversation_api_error_handling(self):
+        """Test handling of malformed requests"""
+        url = self.sdk.url("/planner")
+        # Send malformed payload (missing required fields)
+        malformed_payload = {
+            "invalid_field": "should cause error"
+            # Missing required "message" field
+        }
+        
+        response = self.sdk._make_request("POST", url, json=malformed_payload)
+        
+        # Should get a 4xx error for bad request
+        assert response.status_code >= 400
+
+    def test_conversation_modes(self):
+        """Test different conversation modes (query vs agent)"""
+        url = self.sdk.url("/planner")
+        
+        # Test query mode
+        query_payload = {
+            "message": f"Test query mode at {int(time.time())}",
+            "mode": "query"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=query_payload)
+        assert response.status_code == 200
+        
+        result = response.json()
+        assert "conversation" in result
+        
+        # Test agent mode
+        agent_payload = {
+            "message": f"Test agent mode at {int(time.time())}",
+            "mode": "agent"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=agent_payload)
+        assert response.status_code == 200
+        
+        result = response.json()
+        assert "conversation" in result
+
+    def test_message_polling_integration(self):
+        """Test integration of message polling to check for new messages"""
+        # Create a conversation first
+        url = self.sdk.url("/planner")
+        payload = {
+            "message": f"Test message for polling at {int(time.time())}",
+            "mode": "query"
+        }
+        
+        response = self.sdk._make_request("POST", url, json=payload)
+        assert response.status_code == 200
+        
+        result = response.json()
+        conversation_id = result["conversation"]["uuid"]
+        
+        # Test polling for messages (first call)
+        messages, offset = self.sdk.search.by_key_prefix(
+            f"#message#{conversation_id}#", user=True
+        )
+        
+        initial_count = len(messages) if messages else 0
+        
+        # Wait a moment and check again (simulating polling)
+        time.sleep(1)
+        
+        messages, offset = self.sdk.search.by_key_prefix(
+            f"#message#{conversation_id}#", user=True
+        )
+        
+        # Should still return valid result (messages may or may not have changed)
+        assert isinstance(messages, list)
+
+    def teardown_class(self):
+        """Clean up test data"""
+        # Note: Conversations and messages are typically read-only in tests
+        # Real cleanup would depend on having delete methods for conversations
+        pass

praetorian_cli/sdk/test/test_webpage.py

@@ -0,0 +1,46 @@
+import pytest
+
+from praetorian_cli.sdk.test.utils import make_test_values, setup_chariot
+
+
+@pytest.mark.coherence
+class TestWebpage:
+    """Test suite for the Webpage entity class."""
+
+    def setup_class(self):
+        self.sdk = setup_chariot()
+        make_test_values(self)
+
+    def test_add_webpage(self):
+        """Test adding a Webpage with URL provided."""
+        result = self.sdk.webpage.add(self.webpage_url)
+        
+        assert result is not None
+        webpage = result.get('webpages')[0]
+        assert webpage.get('key') == self.webpage_key
+        assert webpage.get('url') == self.webpage_url
+
+    def test_get_webpage(self):
+        """Test retrieving a Webpage by key."""
+        result = self.sdk.webpage.get(self.webpage_key)
+        assert result is not None
+        assert result.get('key') == self.webpage_key
+        assert result.get('url') == self.webpage_url
+
+    def test_list_webpages(self):
+        """Test listing Webpages."""
+        results, offset = self.sdk.webpage.list(filter=self.webpage_url[:len(self.webpage_url)//2])
+        assert isinstance(results, list)
+        assert len(results) > 0
+        assert any(r.get('key') == self.webpage_key for r in results)
+        assert any(r.get('url') == self.webpage_url for r in results)
+
+    def test_add_webpage_empty_url_raises_exception(self):
+        """Test that adding a Webpage with empty URL raises an exception."""
+        with pytest.raises(Exception, match="URL is required for Webpage"):
+            self.sdk.webpage.add("")
+
+    def test_add_webpage_none_url_raises_exception(self):
+        """Test that adding a Webpage with None URL raises an exception."""
+        with pytest.raises(Exception, match="URL is required for Webpage"):
+            self.sdk.webpage.add(None)

praetorian_cli/sdk/test/test_z_cli.py

@@ -5,6 +5,7 @@ from subprocess import run
 import pytest
 
 from praetorian_cli.sdk.model.globals import AddRisk, Asset, Risk, Seed, Preseed
+from praetorian_cli.sdk.model.utils import configuration_key
 from praetorian_cli.sdk.test.utils import epoch_micro, random_ip, make_test_values, clean_test_entities, setup_chariot
 
 
@@ -210,6 +211,21 @@ class TestZCli:
         self.verify(f'list accounts -f {o.email}', [o.email])
         self.verify(f'unlink account {o.email}')
         self.verify(f'list accounts -f {o.email}')
+        
+    def test_webpage_source_cli(self):
+        o = make_test_values(lambda: None)
+        
+        self.verify(f'add webpage --url "{o.webpage_url}"')
+        
+        file_key = f'"#file#test-nonexistent-{epoch_micro()}-2.txt"'
+        
+        self.verify(f'link webpage-source "{o.webpage_key}" {file_key}', 
+                   expected_stderr=['not found'])
+        self.verify(f'unlink webpage-source "{o.webpage_key}" {file_key}',
+                   expected_stdout=[o.webpage_key])
+        
+        # Clean up
+        self.verify(f'delete webpage "{o.webpage_key}"', ignore_stdout=True)
 
     def test_integration_cli(self):
         self.verify('list integrations', ignore_stdout=True)
@@ -258,6 +274,38 @@ class TestZCli:
 
         self.verify(f'delete configuration "{o.configuration_key}"', ignore_stdout=True)
 
+        string_name = f'{o.configuration_name}-string'
+        string_key = configuration_key(string_name)
+        self.verify(f'add configuration --name "{string_name}" --string PAID_MS')
+        self.verify(f'get configuration "{string_key}"', expected_stdout=[string_key, string_name, '"value": "PAID_MS"'])
+        self.verify(f'delete configuration "{string_key}"', ignore_stdout=True)
+
+        integer_name = f'{o.configuration_name}-integer'
+        integer_key = configuration_key(integer_name)
+        self.verify(f'add configuration --name "{integer_name}" --integer 123')
+        self.verify(f'get configuration "{integer_key}"', expected_stdout=[integer_key, integer_name, '"value": 123'])
+        self.verify(f'delete configuration "{integer_key}"', ignore_stdout=True)
+
+        float_name = f'{o.configuration_name}-float'
+        float_key = configuration_key(float_name)
+        self.verify(f'add configuration --name "{float_name}" --float 1.5')
+        self.verify(f'get configuration "{float_key}"', expected_stdout=[float_key, float_name, '"value": 1.5'])
+        self.verify(f'delete configuration "{float_key}"', ignore_stdout=True)
+
+    def test_webapplication_cli(self):
+        o = make_test_values(lambda: None)
+        self.verify(f'add asset --dns "{o.webapp_name}" --name "{o.webapp_url}" --type webapplication')
+        self.verify(f'get asset "{o.webapp_key}"', expected_stdout=[o.webapp_key, o.webapp_url, o.webapp_name, '"status"', '"A"'])
+        self.verify(f'list assets -f "{o.webapp_name}"', expected_stdout=[o.webapp_key])
+        self.verify(f'delete asset "{o.webapp_key}"', ignore_stdout=True)
+    
+    def test_webpage_cli(self):
+        o = make_test_values(lambda: None)
+        self.verify(f'add webpage --url "{o.webpage_url}"')
+        self.verify(f'get webpage "{o.webpage_key}"', expected_stdout=[o.webpage_key, o.webpage_url, '"status"', '"A"'])
+        self.verify(f'list webpages -p all -f "{o.webpage_url[:len(o.webpage_url)//2]}"', expected_stdout=[o.webpage_key])
+        self.verify(f'delete webpage "{o.webpage_key}"', ignore_stdout=True)
+
     def test_help_cli(self):
         self.verify('--help', ignore_stdout=True)
         self.verify('list --help', ignore_stdout=True)
@@ -310,9 +358,16 @@ class TestZCli:
 
         self.verify('link --help', ignore_stdout=True)
         self.verify('link account --help', ignore_stdout=True)
+        
+        # Agent commands
+        self.verify('agent --help', ignore_stdout=True)
+        self.verify('agent conversation --help', ignore_stdout=True)
+        self.verify('agent mcp --help', ignore_stdout=True)
+        self.verify('link webpage-source --help', ignore_stdout=True)
 
         self.verify('unlink --help', ignore_stdout=True)
         self.verify('unlink account --help', ignore_stdout=True)
+        self.verify('unlink webpage-source --help', ignore_stdout=True)
 
         self.verify('delete --help', ignore_stdout=True)
         self.verify('delete asset --help', ignore_stdout=True)

praetorian_cli/sdk/test/utils.py

@@ -66,6 +66,11 @@ def make_test_values(o):
     o.configuration_value = {o.configuration_name: o.configuration_name}
     o.configuration_key = configuration_key(o.configuration_name)
     o.key_name = f'test-key-name-{epoch_micro()}'
+    o.webapp_name = f'test-webapp-name-{epoch_micro()}'
+    o.webapp_url = f'https://test-webapp-{epoch_micro()}.com/'
+    o.webapp_key = f'#webapplication#{o.webapp_url}'
+    o.webpage_url = f'https://test-webpage-{epoch_micro()}.com/index.html'
+    o.webpage_key = f'#webpage#{o.webpage_url}'
     return o
 
 

praetorian_cli/ui/conversation/__init__.py

@@ -0,0 +1,3 @@
+from .textual_chat import run_textual_conversation
+
+__all__ = ['run_textual_conversation']