Skip to main content

Colander REST API Python client

Project description

Python 3 Colander REST client

Brings your project the ability to populate your Colander server with collected data.

License: GPLv3

Website | Documentation | Support

Installation

pip install colander-client

Project status

  • Cases : Query / Create
  • Devices : Query / Create
  • Observables : Query / Create
  • PiRogueExperiment : Query / Create
  • Artifacts : Query / Create
  • Teams : Query

Refer to Colander documentation for data type explanation.

For a quick overview of changes, take a look at revisions

[!WARNING] Deprecation warnings have been introduced. Keep an eye on those. Backward compatibilities support will be dropped sooner of later.

Usage example

Instancing

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:

from colander_client.client import Client

client = Client()

Case management

Before all, you need a case to work with:

# 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:

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:

client.switch_case(case)

Then you may avoid mentioning case in futur creation calls:

artifact = client.upload_artifact(filepath='/tmp/dump', ...)
experiment = client.create_pirogue_experiment(pcap=pcap_artifact, ...)

To disable case switching:

client.switch_case(None)

In any state, Case presence at function call takes precedence.

Case creation

You may want to create a case on the fly. Since v1.0.4, you can create a case like this:

from colander_client.domain import TlpPap

fresh_case = client.create_case(name='My beaufiful new case',
                                description='Sensitive stuff',
                                tlp=TlpPap.AMBER,
                                pap=TlpPap.RED)

[!IMPORTANT] Even if it is optional, we encourage you to specify tlp and pap levels for new cases.

You may want to specify which teams you want to share this case with. For that, you have to query for teams beforehand:

my_team_list = client.get_teams(name='my team')

shared_fresh_case = client.create_case(name='My beaufiful new case',
                                description='Sensitive stuff',
                                teams=my_team_list,
                                tlp=TlpPap.WHITE,
                                pap=TlpPap.GREEN)

Or with a specific team:

my_team = client.get_team('a-team-id-i-know')

shared_fresh_case = client.create_case(name='My beaufiful new case',
                                description='Sensitive stuff',
                                teams=[my_team])

[!NOTE] Be careful to provide a list of team

Artifact uploads

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:

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:

client.set_global_progress_callback(progress)

In any state, callback presence at function call takes precedence.

PiRogue Experiment creation

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:

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:

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
    })

Relations

You can create entities relation like this:

artifact_1 = client.upload_artifact( [...] )
artifact_2 = client.upload_artifact( [...] )
device_1 = client.create_device( [...] )

relation_1 = client.creation_relation(name='internally refers',
                                      obj_from=artifact_1,
                                      obj_to=artifact_2)

relation_2 = client.creation_relation(name='mentions victim name',
                                      obj_from=artifact_2,
                                      obj_to=device_1)

Revisions

1.0.4 - August 1st 2024

  • Add teams basic support (query)
  • Add case creation support
  • Add entity relations support (query and creation)
  • Client domains refactor
  • Some minor deprecation introduction

1.0.3 - January 22th 2024

  • Add observables support (query and creation)

1.0.2 - January 16th 2023

  • Add case search by name
  • Add device creation support

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

colander-client-1.0.5.tar.gz (22.7 kB view details)

Uploaded Source

Built Distribution

colander_client-1.0.5-py3-none-any.whl (23.9 kB view details)

Uploaded Python 3

File details

Details for the file colander-client-1.0.5.tar.gz.

File metadata

  • Download URL: colander-client-1.0.5.tar.gz
  • Upload date:
  • Size: 22.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.8.18

File hashes

Hashes for colander-client-1.0.5.tar.gz
Algorithm Hash digest
SHA256 dc67fda385385a1e824fc5db82c3b5c95a4f7717ba4406ffe86ae47b2714006b
MD5 da7d5afb3a64dd0bb1c76c0a795598ab
BLAKE2b-256 9f364cb4693a46eefc95b12db0017a44bcdb62b164ec3d7554d3c0ef07359e49

See more details on using hashes here.

File details

Details for the file colander_client-1.0.5-py3-none-any.whl.

File metadata

File hashes

Hashes for colander_client-1.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 79e75a5e76c5e0116c14b86103fe57472b81ceecbe43bae6b193a0455b824929
MD5 45fa483c68cb20590332b2b4c603d813
BLAKE2b-256 22e189588837f7cefbd38ef7301ae13ef90f73a32c5c90cf160b16bfdd77742f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page