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