Metadata-Version: 2.1
Name: colander-client
Version: 1.0.2
Summary: Colander REST API Python client
Home-page: https://github.com/PiRogueToolSuite/colander-python-client.git
Author: U+039b
Author-email: esther@pts-project.org
License: UNKNOWN
Description: # Colander Python 3 client
        
        Colander REST API python implementation.
        
        Brings your project the ability to populate your [Colander](https://github.com/PiRogueToolSuite/colander) instance with interesting collected datas.
        
        License: GPLv3
        
        ## Project status
        
        * Case : Query
        * Devices : Query / Create / Update
        * PiRogueExperiment : Query / Create / Update
        * Artifacts : Query / Create / Update
        
        _Refer to Colander documentation for data type explanation._
        
        ## Usage example
        
        ### Instancing
        
        ```python
        from colander_client.client import Client
        
        base_url = 'https://my-colander-server'
        api_key = 'my-user-api-key'
        
        client = Client(base_url=base_url, api_key=api_key)
        ```
        
        The library also support the following environment variables :
        * `COLANDER_PYTHON_CLIENT_BASE_URL`
        * `COLANDER_PYTHON_CLIENT_API_KEY`
        
        Having such environment variables set, you can just do:
        
        ```python
        from colander_client.client import Client
        
        client = Client()
        ```
        
        ### Case management
        
        Before all, you need a case to work with:
        
        ```python
        # Assuming the given case id :
        case_id = 'current-case-id-im-working-on'
        
        case = client.get_case(case_id)
        ```
        
        Your Case will be asked for each futur creation calls:
        
        ```python
        artifact = client.upload_artifact(case=case, filepath='/tmp/dump', ...)
        experiment = client.create_pirogue_experiment(case=case, pcap=pcap_artifact, ...)
        ```
        
        Since, the Case is somehow the workspace you are working on during a Colander populating session,
        you can use the following handy function:
        
        ```python
        client.switch_case(case)
        ```
        
        Then you may avoid mentioning case in futur creation calls:
        ```python
        artifact = client.upload_artifact(filepath='/tmp/dump', ...)
        experiment = client.create_pirogue_experiment(pcap=pcap_artifact, ...)
        ```
        
        To disable case switching:
        ```python
        client.switch_case(None)
        ```
        
        In any state, Case presence at function call takes precedence.
        
        ### Artifact uploads
        
        ```python
        a_type = client.get_artifact_type_by_short_name( 'SAMPLE' )
        # Assuming we have switched to a Case
        artifact = client.upload_artifact(
            filepath='/tmp/captured.file', artifact_type=a_type)
        ```
        
        Large file upload progression can be followed with a progress callback:
        ```python
        def progress(what, percent, status):
            print(f"{what} is at {percent}%, currently it is: {status}")
            # in case of artifact upload progress 'what' is the given filepath
        
        a_type = client.get_artifact_type_by_short_name( 'SAMPLE' )
        # Assuming we have switched to a Case
        artifact = client.upload_artifact(
            filepath='/tmp/captured.file', artifact_type=a_type, progress_callback=progress)
        ```
        
        When you have many uploads to proceed, you can globally set a callback on the client,
        avoiding repetitively passing it at function calls:
        ```python
        client.set_global_progress_callback(progress)
        ```
        
        In any state, callback presence at function call takes precedence.
        
        ### PiRogue Experiment creation
        
        ```python
        experiment = client.create_pirogue_experiment(
            name='My today investigation',
            pcap=pcap_artifact,
            socket_trace=socket_trace_artifact,
            sslkeylog=sslkeylog_artifact)
        ```
        
        ### Device creation
        
        Device can be specified on Artifact or PiRogue Experiment.
        The creation is as follow:
        ```python
        d_type = client.get_device_type_by_short_name('LAPTOP')
        
        pul_device = client.create_device(name='Potential unsecure laptop', device_type=d_type)
        ```
        
        Then specified at Artifact or PiRogue Experiment creation:
        ```python
        artifact = client.upload_artifact(
            filepath='/tmp/captured.file', artifact_type=a_type,
            extra_params={
                'extracted_from': pul_device
            })
        
        experiment = client.create_pirogue_experiment(
            name='My today investigation',
            pcap=pcap_artifact,
            socket_trace=socket_trace_artifact,
            sslkeylog=sslkeylog_artifact,
            extra_params={
                'target_device': pul_device
            })
        ```
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Natural Language :: English
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
