Admin Guide
Synapse-TeamCymru Admin Guide
Configuration
Synapse-TeamCymru requires a TeamCymru API key. For information on how to sign up, please visit the Team-Cymru website.
Setting API key for global use
To set-up a global API key:
> teamcymru.recon.setup.apikey myapikey
Setting Team-Cymru RECON API key for all users.
Using per-user API keys
A user may set-up their own API key:
> teamcymru.recon.setup.apikey --self myapikey
Setting Team-Cymru RECON API key for the current user.
Permissions
Package (synapse-teamcymru) defines the following permissions:
power-ups.teamcymru.user : Controls user access to Synapse-TeamCymru. ( default: false )
You may add rules to users/roles directly from storm:
> auth.user.addrule visi power-ups.teamcymru.user
Added rule power-ups.teamcymru.user to user visi.
or:
> auth.role.addrule ninjas power-ups.teamcymru.user
Added rule power-ups.teamcymru.user to role ninjas.
Exported APIs
APIs within the module teamcymru are exported and considered stable. They can be
accessed by importing the module with $lib.import(teamcymru). For example, to
retrieve a page of jobs from the API and print the returned JSON objects for the jobs:
> $teamcymru=$lib.import(teamcymru) $jobs=$teamcymru.getReconJobs() for $job in $jobs.data { $lib.pprint($job) }
{'created_at': '2023-06-07 20:21:15',
'description': None,
'group_id': None,
'group_name': None,
'id': 5117925,
'input': '{"uuid": "518d7b67-2881-4958-8593-25e82e5f1fdf", "limit": 2000000, '
'"queries": {"36": {"c": "", "o": "", "cn": "", "email": "", '
'"issuer": "", "serial": "", "subject": "", "version": "", '
'"altnames": "", "any_port": "", "hostname": "", "issuer_c": "", '
'"issuer_o": "", "sig_algo": "", "x509_md5": "", "issuer_cn": "", '
'"x509_sha1": "", "query_type": "x509", "any_ip_addr": "8.8.8.8", '
'"exclude_version": "", "exclude_any_port": "", "exclude_x509_md5": '
'"", "exclude_x509_sha1": "", "exclude_any_ip_addr": ""}}, '
'"timeout": 14400, "end_date": "2023-06-07 23:59:59", "job_name": '
'"Example x509 Job", "start_date": "2023-05-31 00:00:00", '
'"system_origin": "web", "limit_realtime": 2000000, '
'"job_description": "", "limit_flowsonar": 2000000}',
'name': 'Example x509 Job',
'organization_id': 125588,
'organization_name': 'Vertex Project',
'origin': 'web',
'scheduled_interval': (),
'status': 'Completed',
'total_bytes': 32768,
'updated_at': '2023-06-07 20:21:19',
'user_id': 129636,
'username': '[email protected]'}
Module Functions
getReconJobs(page=(1))
----------------------
Retrieve a page of job definitions.
Args:
page (int): Page number to retrieve.
Returns:
dict: Dictionary containing the response.
getReconJobDetails(jobid)
-------------------------
Retrieve details for a job by id.
Args:
jobid (int): The id of the job.
Returns:
dict: Dictionary containing the job details.
getReconJobQuery(jobid)
-----------------------
Get the it:exec:query node for a job.
Args:
jobid (int): The id of the job.
Returns:
node: it:exec:query node for the job if it exists.
ingestReconJob(jobid)
---------------------
Ingest a completed job.
Args:
jobid (int): The id of the job.
Yields:
nodes: Nodes created from ingesting the job.
addReconJob(jdef)
-----------------
Submit a job definition to the TeamCymru API.
Args:
jdef (dict): A job definition JSON dictionary.
Returns:
dict: Dictionary containing the response from the API.
delReconJob(jobid)
------------------
Delete a job.
Args:
jobid (int): The id of the job.
Returns:
dict: Dictionary containing the response from the API.
isJobComplete(details)
----------------------
Check a job details dictionary to determine if it is fully completed.
Args:
details (dict): A job details dictionary.
Returns:
bool: true if all the results are completed, false otherwise.
waitForJob(jobid, poll=(2))
---------------------------
Poll the API until a job is complete.
Args:
jobid (int): The id of the job.
poll (int): Number of seconds to wait between each check.
Returns:
bool: true once the job is complete.
isSizeOverLimit(size)
---------------------
Check and display a warning if a value is above the job result size limit.
Args:
size (int): The value to check.
Returns:
bool: true if the value is above the limit, false otherwise.
submitJob(name, queries, tbox=$lib.null, size=(10000), timeout=(60), poll=(2))
------------------------------------------------------------------------------
Create a job, submit it, and ingest the results once it is complete.
Args:
name (str): A name for the job.
queries (list): A list of dictionaries containing the query defs for the job.
tbox (tuple): A tuple containing a start/end time filter to apply to the job (defaults to the last 7 days).
size (int): The maximum number of results to produce.
timeout (int): The job timeout value.
poll (int): Number of seconds to wait when polling job completion.
Returns:
nodes: Nodes created from ingesting the job.
Node Actions
Synapse-TeamCymru provides the following node actions in Optic:
Name : Flows
Desc : Lookup network flows.
Forms: inet:ipv4, inet:cidr4
Name : Passive DNS
Desc : Lookup PDNS results.
Forms: inet:fqdn, inet:ipv4, inet:cidr4
Name : x509 Certs
Desc : Lookup x509 certificates.
Forms: inet:email, inet:fqdn, inet:ipv4, inet:cidr4, hash:md5, hash:sha1