Skip to content

Collective Insights

Introduction

The CollectiveInsights class of the collective_insights module allows you to submit indicators from a detection coming from any of your internal tools to your Recorded Future enterprise. Collective Insights enriches submissions with Recorded Future intelligence to provide your organisation's enterprise with enhanced and actionable intelligence.

When using the collective_insights module, you have to create an Insight object and then submit it. The CollectiveInsights class provide access to the modules needed to perform these actions. The examples below will show how to use them.

See the API Reference for internal details of the module.

Notes

  1. There are some limitations around the number of submissions allowed per day, see the Collective Insight API documentation.

  2. The insights submitted requires some fields to be filled with specific values. For example the detection_type can be either sigma, yara or snort. To help you there are some constants values defined in collective_insights.constants. See a usage example below.

Examples

Warning

Below are some examples of usage of the module. Consider adding error handling as necessary. All the errors that can be raised by each method or function are specified in the API Reference page.

Also, you need to configure the RF_TOKEN environment variable before starting. See Learn.

Example 1: Submit a detection of an hash linked to a Wiper malware speciment.

The create method only requires the following arguments to be specified:

  • ioc_value
  • ioc_type
  • detection_type
  • timestamp

Every other value can optionally be provided and add more context to the detection. In the example we have a detection coming from Symantec. The hash is coming from a Recorded Future Insikt note defined by the id doc:o6_lui. The other information are retrieved by both the note (example the malware type and MITRE codes) or the incident itself.

In our case the timestamp has been mocked to "now", but in a real scenario it would be taken from the incident.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import datetime

from psengine.collective_insights import (
    DETECTION_SUB_TYPE_SIGMA,
    DETECTION_TYPE_RULE,
    ENTITY_HASH,
    CollectiveInsights,
)

ci = CollectiveInsights()

now = datetime.datetime.utcnow().isoformat()[:-3] + 'Z'

insight1 = ci.create(
    ioc_value='fbee00cb1d1ea4d7e0604436d9a36def71a9f3be804f1e2b8d117fd5d35aeabc',
    ioc_type=ENTITY_HASH,
    detection_type=DETECTION_TYPE_RULE,
    detection_sub_type=DETECTION_SUB_TYPE_SIGMA,
    detection_id='doc:o6_lui',
    detection_name='Instance of Alleged New Wiper Malware',
    ioc_field='hash',
    ioc_source_type='symantec',
    timestamp=now,
    incident_id='Incident 001',
    incident_name='Malware detected',
    incident_type='RF Sigma Rule',
    mitre_codes=['T1542', 'T1485'],
    malwares=['Aesthetic Wiper'],
)

insights = [insight1]
ci.submit(insight=insights)

The create method return a Insight object, which can be passed to the submit method.

The submit method take a single Insight or a list of Insight objects.