diff --git a/README.md b/README.md index 9b2e22e0e9..b5a7e28537 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ # Splunk Security Content -![security_content](docs/static/logo.png) +![security_content](docs/static/escu_sb.png) ===== Welcome to the Splunk Security Content @@ -27,39 +27,88 @@ This project gives you access to our repository of Analytic Stories, security gu **Note:** We have sister projects that enable us to build the industry's best security content. These projects are the Splunk Attack Range, an attack simulation lab built around Splunk, and Contentctl, the tool that enables us to build, test, and package our content for distribution. -- [Splunk Attack Range](https://github.com/splunk/attack_range): An attack simulation lab built around Splunk. +# Tools 🧰 + +- [Splunk Attack Range](https://github.com/splunk/attack_range): The Splunk Attack Range is an open-source project maintained by the Splunk Threat Research Team. It builds instrumented cloud (AWS, Azure) and local environments (Virtualbox), simulates attacks, and forwards the data into a Splunk instance. This environment can then be used to develop and test the effectiveness of detections. - [Contentctl](https://github.com/splunk/contentctl): The tool that enables us to build, test, and package our content for distribution. +- [Attack data](https://github.com/splunk/attack_data): The is a collection of attack data that is used to test our content. +- [Atomic Red Team](https://github.com/redcanaryco/atomic-red-team): Atomic Red Team™ is a library of tests mapped to the MITRE ATT&CK® framework. Security teams can use Atomic Red Team to quickly, portably, and reproducibly test their environments. # Get Content🛡 The latest Splunk Security Content can be obtained via: -### 🌐 [Website](https://research.splunk.com/) +#### 🌐 [Website](https://research.splunk.com/) Best way to discover and access our content is by using the [research.splunk.com](https://research.splunk.com/) website. -### 🖥️ [Splunk Enterprise Security (ES) Content Update](https://docs.splunk.com/Documentation/ES/latest/Admin/Usecasecontentlibrary?#Update_the_Analytic_Stories) +#### 🖥️ [Splunk Enterprise Security (ES) Content Update](https://docs.splunk.com/Documentation/ES/latest/Admin/Usecasecontentlibrary?#Update_the_Analytic_Stories) Splunk security content ships as part of ESCU directly into, if you are an ES user, good news, you already have it! -### 📦 [ESCU App](https://github.com/splunk/security_content/releases) +#### 📦 [ESCU App](https://github.com/splunk/security_content/releases) To manually download the latest release of Splunk Security Content (named DA-ESS-ContentUpdate.spl), you can visit the [splunkbase](https://splunkbase.splunk.com/app/3449/) page or the [release page](https://github.com/splunk/security_content/releases) on GitHub. -# Tools 🧰 -The key tool that drives our content development is [contentctl](https://github.com/splunk/contentctl). Contentctl offers the following features: +# Getting Started 🛠️ -- Creating new detections -- Validating the correctness of all necessary components for detections -- Testing detections -- Generating deployable apps from detections +Follow these steps to get started with Splunk Security Content. -To learn more about contentctl and its capabilities, please visit the [contentctl repository](https://github.com/splunk/contentctl). +1. Clone this repository using `git clone https://github.com/splunk/security_content.git` +2. Navigate to the repository directory using `cd security_content` +3. Install contentctl using `pip install contentctl` to install the latest version of contentctl, this is a pre-requisite to validate, build and test the content like the Splunk Threat Research team -# MITRE ATT&CK ⚔️ -### Detection Coverage -To view an up-to-date detection coverage map for all the content tagged with MITRE techniques visit: [https://mitremap.splunkresearch.com/](https://mitremap.splunkresearch.com/) under the **Detection Coverage** layer. Below is a snapshot in time of what technique we currently have some detection coverage for. +# Quick Start 🚀 -![](docs/mitre-map/coverage.png) +1. Setup the environment +``` +git clone https://github.com/splunk/security_content.git +cd security_content +python3.11 -m venv .venv +source .venv/bin/activate +pip install contentctl + +``` +2. Create a new **detection.yml** and answer the questions + ``` + contentctl new + ``` + + +**NOTE** - Make sure you update the detection.yml with the required fields and values. If you need help, please refer to the [yaml-spec](docs/yaml-spec) to check out the list of allowed values + +4. Validate your content +``` +contentctl validate +``` +**NOTE** - The contentctl validate command ensures that all YAML files adhere to the defined specifications and are up-to-date. It checks for required fields, correct data types, and overall consistency, helping maintain the integrity and quality of the content. + +5. Build an ESCU app with enrichments from Atomic Red Team and Mitre CTI repositories +``` +contentctl build --enrichments +``` + +6. Test the content - Our testing framework is based on [contentctl](https://github.com/splunk/contentctl) and is extensive and flexible. Refer to the [contentctl test documentation](https://github.com/splunk/contentctl?tab=readme-ov-file#contentctl-test) to learn more about the testing framework. + + +# Recommendations 💡 + +- 🚨 NOTE: If you are just getting started with managing your Splunk detection as code, we recommend that you keep the YAML structure of the detections as close as possible to the original structure of the detections. This will make it easier to manage your detections and will also make it easier to contribute back to the community by creating a pull request to the Splunk Security Content project. + +- In order to build an content app that specific for your organization, we strongly recommend that you start with keeping only the detections that are related to your organization and remove other yamls that are not related to your organization. This includes selecting detections, stories, macros, lookups that are used by the detection ymls. + +- If your detections are using macros and lookups, please make sure that you have the same macros and lookups in those directories.. This will ensure that the content app is self-contained and does not rely on external files. + +- We recommend that you follow the errors produced by the `contentctl` tool while developing this content. The errors are descriptive enough to guide you in getting the right values. If you need help, please open a GitHub issue in the `contentctl` repository or refer to the [yaml-spec](docs/yaml-spec) to check out the list of allowed values + + +# YAML Specs 📄 + +YAML specs define the structure and required fields for various YAML configuration files used in the project. These specifications ensure consistency and validation across different types of YAML files, such as macros, lookups, and analytic stories. Each spec outlines the expected data types, descriptions, and whether the fields are mandatory, providing a clear schema for developers to follow. + +- [detection](https://github.com/splunk/security_content/blob/develop/docs/yaml-spec/detection_spec.yml) +- [stories](https://github.com/splunk/security_content/blob/develop/docs/yaml-spec/stories_spec.yml) +- [macros](https://github.com/splunk/security_content/blob/develop/docs/yaml-spec/macros_spec.yml) +- [lookups](https://github.com/splunk/security_content/blob/develop/docs/yaml-spec/lookups_spec.yml) # Content Parts 🧩 @@ -73,6 +122,11 @@ To view an up-to-date detection coverage map for all the content tagged with MIT * [lookups/](lookups/): Implements Splunk’s lookup, usually to provide a list of static values like commonly used ransomware extensions. * [data_sources/](data_sources/): Defines the data sources, the necessary TA or App to collect them and the fields provided that can be used by the detections. + +# MITRE ATT&CK ⚔️ +### Detection Coverage +To view an up-to-date detection coverage map for all the content tagged with MITRE techniques visit: [https://mitremap.splunkresearch.com/](https://mitremap.splunkresearch.com/) under the **Detection Coverage** layer. Below is a snapshot in time of what technique we currently have some detection coverage for. + # Contribution 🥰 We welcome feedback and contributions from the community! Please see our [contributing to the project](./.github/CONTRIBUTING.md) for more information on how to get involved. diff --git a/docs/static/escu_app_logo.png b/docs/static/escu_app_logo.png new file mode 100644 index 0000000000..c78333b42d Binary files /dev/null and b/docs/static/escu_app_logo.png differ diff --git a/docs/static/escu_sb.png b/docs/static/escu_sb.png new file mode 100644 index 0000000000..ee2578df2c Binary files /dev/null and b/docs/static/escu_sb.png differ diff --git a/docs/yaml-spec/detection_spec.yml b/docs/yaml-spec/detection_spec.yml new file mode 100644 index 0000000000..b94dd282b3 --- /dev/null +++ b/docs/yaml-spec/detection_spec.yml @@ -0,0 +1,160 @@ +#### Spec for detection yaml file +name: + type: str + description: Name of the detection, this is the name that will be displayed in the Splunk UI. Naming convention is __. Ref - https://github.com/splunk/security_content/wiki/Detection-Naming-Convention + required: true +id: + type: str + description: Unique identifier for the detection, UUID + required: true +version: + type: int + description: Version of the detection, update this every time a change is made to the file + required: true +date: + type: str + description: Date of the detection, update this every time a change is made to the file + required: true +author: + type: str + description: Author of the detection + required: true +status: + type: str + description: Status of the detection + enum: [production, experimental, deprecated] + required: true +type: + type: str + description: Type of the detection + enum: [TTP, Anomaly, Baseline, Hunting, Correlation] + required: true +data_source: + type: list + description: Reference to the name from the data_sources folder. + required: false +description: + type: str + description: Description of the detection + required: true +search: + type: str + description: Splunk search to be executed. search should end with a _filter macro to filter out the false positives. + required: true +how_to_implement: + type: str + description: Details on how to implement the detection + required: true +known_false_positives: + type: str + description: Details on known false positives triggered in this detection + required: true +references: + type: list + description: List of references to the MITRE ATT&CK, details of attack vector, blog posts, vulnerabilities, etc. + required: false +tags: + type: dict + description: Tags are various metadata that can be used to categorize the detection + required: false + properties: + analytic_story: + type: list + description: Name of the analytic story that the detection is part of, use the exact name as in the stories/ folder. + required: true + asset_type: + type: list + description: Which assets are monitored by this detection + enum: ['AWS Account', 'AWS EKS Kubernetes cluster', 'AWS Federated Account', 'AWS Instance', 'Account', 'Amazon EKS Kubernetes cluster', 'Amazon EKS Kubernetes cluster Pod', 'Amazon Elastic Container Registry', 'Azure Tenant', 'Azure AKS Kubernetes cluster', 'Azure Active Directory', 'CircleCI', 'Cloud Compute Instance', 'Cloud Instance', 'DNS Servers', 'Database Server', 'Domain Server', 'EC2 Snapshot', 'Endpoint', 'GCP', 'GCP Account', 'GCP GKE EKS Kubernetes cluster', 'GCP GKE Kubernetes cluster', 'GCP Kubernetes cluster', 'GCP Storage Bucket', 'GDrive', 'GSuite', 'GitHub', 'Google Cloud Platform tenant', 'Identity', 'Infrastructure', 'Instance', 'Kubernetes', 'Network', 'O365 Tenant', 'Okta Tenant', 'Proxy', 'S3 Bucket', 'Splunk Server', 'VPN Appliance', 'Web Server', 'Web Proxy', 'Web Application','Windows'] + required: true + atomic_guid: + type: list + description: List of Atomic GUIDs from Atomic Red Team + required: false + confidence: + type: int + description: Confidence level of the detection between 1-100 + required: true + impact: + type: int + description: A number between 1-100 that represents the impact when the detection is triggered + required: true + message: + type: str + description: The risk message that will be displayed in the Splunk Enterprise Security + required: true + cve: + type: list + description: List of CVE IDs that are related to the detection + required: false + mitre_attack_id: + type: list + description: List of MITRE ATT&CK IDs that are related to the detection + required: false + observable: + type: list + description: List of observables that are related to the detection. Atleast one observable with Victim role is required. + required: true + items: + name: + type: str + description: Field name of the observable + required: true + type: + type: str + description: Type of the observable + enum: [Unknown, Hostname, IP Address, MAC Address, User Name, Email Address, URL String, File Name, File Hash, Process Name, Resource UID, Endpoint, User, Email, Uniform Resource Locator, File, Process, Geo Location, Container, Registry Key, Registry Value, Other] + required: true + role: + type: list + description: Role of the observable. Atleast one observable with Victim role is required. + enum: [Victim, Attacker] + required: true + product: + type: list + description: List of products that are related to the detection + enum: [Splunk Enterprise Security, Splunk Enterprise, Splunk Cloud] + required: true + risk_score: + type: int + description: A number between 1-100 that represents the risk score of the detection. The risk score will be calculated based on the confidence and impact. + required: true + required_fields: + type: list + description: List of required fields that are needed to execute the detection + required: true + security_domain: + type: str + description: The security domain that the detection is related to + enum: ['endpoint', 'network', 'threat', 'identity', 'access', 'audit', 'cloud'] + required: false +manual_test: + type: str + description: If the detection needs manual testing, set a message here so that contentctl will not run the test automatically. + required: false +tests: + type: list + description: List of tests for the detection + required: false + items: + name: + type: str + description: Name of the test, Example - True Positive Test + required: true + attack_data: + type: list + description: List of attack data used to test the detection + required: true + items: + data: + type: str + description: URL to the attack data, Example - https://media.githubusercontent.com/media/splunk/attack_data/master/datasets/attack_techniques/T1190/crushftp/crushftp.log + required: true + source: + type: str + description: source of the attack data in splunk + required: true + sourcetype: + type: str + description: sourcetype of the attack data extracted by the TAs in Splunk Example - crushftp:sessionlogs + required: true \ No newline at end of file diff --git a/docs/yaml-spec/lookups_spec.yml b/docs/yaml-spec/lookups_spec.yml new file mode 100644 index 0000000000..1c6ac207ea --- /dev/null +++ b/docs/yaml-spec/lookups_spec.yml @@ -0,0 +1,48 @@ +### Spec for File based lookups +name: + type: str + description: Name of the lookup + required: true +description: + type: str + description: Description of the lookup + required: true +filename: + type: str + description: Filename of the CSV file associated with the lookup + required: true +default_match: + type: str + description: Default match setting for the lookup + required: false +match_type: + type: str + description: Type of match used in the lookup + required: false +min_matches: + type: int + description: Minimum number of matches required + required: false +case_sensitive_match: + type: str + description: Case sensitivity setting for the match + required: false + + + #### Spec for Collections based lookups: +name: + type: str + description: Name of the lookup + required: true +collection: + type: str + description: Name of the collection associated with the lookup + required: true +description: + type: str + description: Description of the lookup + required: true +fields_list: + type: list + description: List of fields in the lookup + required: true \ No newline at end of file diff --git a/docs/yaml-spec/macros_spec.yml b/docs/yaml-spec/macros_spec.yml new file mode 100644 index 0000000000..c0bdd0e619 --- /dev/null +++ b/docs/yaml-spec/macros_spec.yml @@ -0,0 +1,12 @@ +name: + type: str + description: Name of the macro + required: true +definition: + type: str + description: Definition of the macro, replace with configurations for your Splunk Environment + required: true +description: + type: str + description: Description of the macro + required: true \ No newline at end of file diff --git a/docs/yaml-spec/stories_spec.yml b/docs/yaml-spec/stories_spec.yml new file mode 100644 index 0000000000..ad3bba6a26 --- /dev/null +++ b/docs/yaml-spec/stories_spec.yml @@ -0,0 +1,53 @@ +#### Spec for detection yaml file +name: + type: str + description: Name of the analytic story + required: true +id: + type: str + description: Unique identifier for the analytic story, UUID + required: true +version: + type: int + description: Version of the analytic story, update this every time a change is made to the file + required: true +date: + type: str + description: Date of the analytic story + required: true +author: + type: str + description: Author of the analytic story + required: true +description: + type: str + description: Description of the analytic story + required: true +narrative: + type: str + description: Narrative of the analytic story, what this usecase is about + required: true +references: + type: list + description: List of references to the analytic story + required: false +tags: + type: dict + description: Tags are various metadata that can be used to categorize the analytic story + required: true + properties: + category: + type: list + description: List of categories that the analytic story is related to + required: true + enum: ['Abuse', 'Adversary Tactics', 'Best Practices', 'Cloud Security', 'Compliance', 'Malware', 'Uncategorized', 'Vulnerability', 'Account Compromise', 'Data Destruction', 'Lateral Movement', 'Privilege Escalation', 'Ransomware' or 'Unauthorized Software'] + product: + type: list + description: List of products that the analytic story is related to + enum: [Splunk Enterprise Security, Splunk Enterprise, Splunk Cloud] + required: true +usecase: + type: str + description: Usecase of the analytic story + enum: ['Fraud Detection', 'Compliance', 'Application Security', 'Security Monitoring', 'Advanced Threat Detection', 'Insider Threat','Other'] + required: true \ No newline at end of file