USER_GUIDE.md

OpenCTI CrowdSec internal enrichment connector

User Guide

Table of Contents

• Description
  • Configuration
  • Use case: enrich an observable
  • Additional information

Description

This is a OpenCTI connector which enriches your knowledge by using CrowdSec's CTI API.

Architecturally it is an independent python process which has access to the OpenCTI instance and CrowdSec's CTI API. It enriches knowledge about every incoming IP in OpenCTI by looking it up in CrowdSec CTI.

Configuration

Configuration parameters are provided using environment variables as described below. Some of them are placed directly in the docker-compose.yml since they are not expected to be modified by final users once that they have been defined by the developer of the connector.

Parameters meaning

Docker environment variable	Mandatory	Type	Description
OPENCTI_URL	Yes	String	The URL of the OpenCTI platform.
OPENCTI_TOKEN	Yes	String	The default admin token configured in the OpenCTI platform parameters file.
CONNECTOR_ID	Yes	String	A valid arbitrary UUIDv4 that must be unique for this connector.
CONNECTOR_NAME	Yes	String	Name of the CrowdSec connector to be shown in OpenCTI.
CONNECTOR_SCOPE	Yes	String	Supported scopes: IPv4-Addr, IPv6-Addr
CONNECTOR_CONFIDENCE_LEVEL	Yes	Integer	The default confidence level (an integer between 0 and 100).
CONNECTOR_AUTO	No	Boolean	Enable/disable auto-enrichment of observables. Default: false
CONNECTOR_UPDATE_EXISTING_DATA	No	Boolean	Enable/disable update of existing data in database. Default: false
CONNECTOR_LOG_LEVEL	No	String	The log level for this connector, could be debug, info, warn or error (less verbose). Default: info
CROWDSEC_KEY	Yes	String	CrowdSec CTI API key. See instructions to obtain it
CROWDSEC_API_VERSION	No	String	CrowdSec API version. Supported version: v2. Default: v2.
CROWDSEC_MAX_TLP	No	String	Do not send any data to CrowdSec if the TLP of the observable is greater than crowdsec_max_tlp. Default: TLP:AMBER
CROWDSEC_LABELS_SCENARIO_NAME	No	Boolean	Enable/disable labels creation based on CTI scenario's name. Default: true
CROWDSEC_LABELS_SCENARIO_LABEL	No	Boolean	Enable/disable labels creation based on CTI scenario's label. Default: true
CROWDSEC_LABELS_SCENARIO_COLOR	No	String	Color of scenario based labels. Default: #2E2A14
CROWDSEC_LABELS_CVE	No	Boolean	Enable/Disable CTI cve name based labels. Default: false
CROWDSEC_LABELS_CVE_COLOR	No	String	Color of cve based labels. Default: #800080
CROWDSEC_LABELS_MITRE	No	Boolean	Enable/Disable CTI mitre technique based labels. Default: false
CROWDSEC_LABELS_MITRE_COLOR	No	String	Color of mitre technique based labels. Default: #000080
CROWDSEC_LABELS_BEHAVIOR	No	Boolean	Enable/Disable CTI behavior based labels. Default: false
CROWDSEC_LABELS_BEHAVIOR_COLOR	No	String	Color of behavior based labels. Default: #808000
CROWDSEC_LABELS_REPUTATION	No	Boolean	Enable/Disable CTI reputation based labels. Default: false
CROWDSEC_LABELS_REPUTATION_MALICIOUS_COLOR	No	String	Color of malicious reputation label. Default: #FF0000
CROWDSEC_LABELS_REPUTATION_SUSPICIOUS_COLOR	No	String	Color of suspicious reputation label. Default: #FFA500
CROWDSEC_LABELS_REPUTATION_SAFE_COLOR	No	String	Color of safe reputation label. Default: #00BFFF
CROWDSEC_LABELS_REPUTATION_KNOWN_COLOR	No	String	Color of safe reputation label. Default: #808080
CROWDSEC_INDICATOR_CREATE_FROM	No	String	List of reputations to create indicators from (malicious, suspicious, known, safe) separated by comma. Default: empty ''. If an IP is detected with a reputation that belongs to this list, an indicator based on the observable will be created.
CROWDSEC_ATTACK_PATTERN_CREATE_FROM_MITRE	No	Boolean	Create attack patterns from MITRE techniques If an indicator has been created, there will be a targets relationship between the attack pattern and the indicator. Otherwise, there will be a related-to relationship between the attack pattern and the observable There will be a targets relationship between the attack pattern and a location created from targeted country. Default false
CROWDSEC_VULNERABILITY_CREATE_FROM_CVE	No	Boolean	Create vulnerability from CVE. There will be a related-to relationship between the vulnerabilty and the observable Default true
CROWDSEC_CREATE_NOTE	No	Boolean	Enable/disable creation of a note in observable for each enrichment. Default: false
CROWDSEC_CREATE_SIGHTING	No	Boolean	Enable/disable creation of a sighting of observable related to CrowdSec organization. Default: true
CROWDSEC_LAST_ENRICHMENT_DATE_IN_DESCRIPTION	No	Boolean	Enable/disable saving the last CrowdSec enrichment date in observable description. Default: true
CROWDSEC_MIN_DELAY_BETWEEN_ENRICHMENTS	No	Number	Minimum delay (in seconds) between two CrowdSec enrichments. Default: 300 Use it to avoid too frequent calls to CrowdSec's CTI API. Requires the last CrowdSec enrichment to be saved in the description, as we'll be comparing this date with the current one. If CONNECTOR_AUTO is true and if you are also using the CrowdSec External Import connector, please ensure to also set CROWDSEC_LAST_ENRICHMENT_DATE_IN_DESCRIPTION=truein the external import connector.
CROWDSEC_CREATE_TARGETED_COUNTRIES_SIGHTINGS	No	Boolean	Enable/Disable creation of a sighting of observable related to a targeted country Default: true Sighting count represents the percentage distribution of the targeted country among all the countries targeted by the attacker.

You could also use the config.ymlfile of the connector to set the variable.

In this case, please put the variable name in lower case and separate it into 2 parts using the first underscore _. For example, the docker setting CROWDSEC_MAX_TLP=TLP:AMBER becomes :

crowdsec:
    max_tlp: 'TLP:AMBER'

You will find a config.yml.sample file as example.

Recommended settings

• CROWDSEC_LABELS_SCENARIO_NAME=true
• CROWDSEC_LABELS_SCENARIO_LABEL=false
• CROWDSEC_LABELS_CVE=true
• CROWDSEC_LABELS_MITRE=true
• CROWDSEC_LABELS_REPUTATION=true
• CROWDSEC_INDICATOR_CREATE_FROM='malicious,suspicious,known'
• CROWDSEC_CREATE_NOTE=true
• CROWDSEC_CREATE_SIGHTING=true
• CROWDSEC_CREATE_TARGETED_COUNTRIES_SIGHTINGS=false

Use case: enrich an observable

If you create a IPv4 address or IPv6 address observable, this connector will enable you to enrich it with data retrieved from CrowdSec's CTI.

If CONNECTOR_AUTO configuration is set to true, the observable will be automatically enriched when created. Otherwise, you'll need to enrich it manually by clicking on the enrichment icon and selecting the CrowdSec connector.

Example: Enrichment with recommended settings

In this example, we chose 146.70.186.190 as it is currently reported for cve and mitre techniques.

Assuming you have an observable whose IPv4-Addr value is equal to 146.70.186.190 and you have set the settings recommended above, the result of a CrowdSec's enrichment should be similar to the following description:

• With regard to the observable itself, you should see:
  • a list of dark olive green scenario name labels (crowdsecurity/http-admin-interface-probing, crowdsecurity/http-bad-user-agent, etc.)
  • a list of purple cve labels (cve-2021-41773, etc.)
  • a red maliciousreputation label
  • An external reference to the CrowdSec CTI's url
  • A note with some content (confidence, first seen, last seen, behaviors, targeted countries, etc.)
  • A list of relationships:
    • related relationships leading to vulnerabilities created from CVEs
    • based-on relationship leading to a CrowdSec CTI indicator
  • A sighting related to CrowdSec with the first and last seen information
• As the CROWDSEC_INDICATOR_CREATE_FROM recommended setting contains malicious reputation, an indicator has been created with:
  • An external reference to the blocking list from which the flagged IP originates.
  • A list of indicates relationship leading to attack patterns created using mitre techniques
    • If you follow one of this relationship, you can navigate to the attack pattern created, where you will see
      • An external reference to the MITRE ATT&CK url
      • A list of targets relationships leading to location created from targeted countries (Canada, Poland, etc.)

Additional information

This connector will lookup and edit incoming IPv4-Addr or Ipv6-Addr observable entity. Note that CrowdSec's CTI has quotas, this connector will poll it if quota is exceeded following exponential backoff.