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
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
andpap
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
Built Distribution
Hashes for colander_client-1.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 79e75a5e76c5e0116c14b86103fe57472b81ceecbe43bae6b193a0455b824929 |
|
MD5 | 45fa483c68cb20590332b2b4c603d813 |
|
BLAKE2b-256 | 22e189588837f7cefbd38ef7301ae13ef90f73a32c5c90cf160b16bfdd77742f |