diff --git a/Makefile b/Makefile index 948884b..bff38c4 100644 --- a/Makefile +++ b/Makefile @@ -1,2 +1,2 @@ all: - @./tools/gendoc.sh + @./scripts/gendoc.sh diff --git a/README.md b/README.md index 6061710..781c317 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,80 @@ - + # Security Intents for Intent Driven Security + ![CI status](https://github.com/5GSEC/security-intents/actions/workflows/ci-verify.yml/badge.svg) Repository to hold Security Intents in standard template format. ![](res/nimbus.png) -## Security Intents - - [blockAsset](intents/core/blockAsset.yaml) - - [blockRawSocket](intents/core/blockRawSocket.yaml) - - [protectAsset](intents/core/protectAsset.yaml) - - [protectPort](intents/core/protectPort.yaml) - ## Security Threat Template -``` -title: # Scenario-title -description: # Detailed description of the scenario -severity: # High/Medium/Low -tags: [oran, 5gcore, generic, oranThreatId] -detectionMethods: #Mechanisms to detect the threat - https://fight.mitre.org/data%20sources - - name: applicationlog - tag: [mitre, ds0015] - description: desc - url: https://fight.mitre.org/data%20sources/DS0015 - - name: myapplicationlog - tag: [accuknox, ax0015] - description: desc - url: https://... -mitigationMethods: #Mechanisms to mitigate the threat - https://fight.mitre.org/mitigations - - name: applicationlog - tag: [mitre, ds0015] - description: desc - url: https://fight.mitre.org/data%20sources/DS0015 - - name: myapplicationlog - tag: [accuknox, ax0015] - description: desc - url: https://... +```yaml +title: Scenario-title +description: Detailed description of the scenario +severity: High/Medium/Low +tags: + - oran + - 5gcore + - generic +detectionMethods: # Mechanisms to detect the threat + - name: Application log + tag: + - mitre/ds0015 + description: Description # Optional + url: https://... + - name: Process + tag: + - accuknox/ax0015 + description: Description # Optional + url: https://... +mitigationMethods: # Mechanisms to mitigate the threat + - name: Update Software + tag: + - mitre/ds0015 + description: desc + url: https://... + - name: User Account Management + tag: + - accuknox/ax0015 + description: desc + url: https://... securityIntents: - - sample-si-1 # no params for now - - sample-si-2 -securityIntentBinding: sample-si-binding.yaml -preDeploymentConsiderations: #Anything that can be done in CI/CD pipelines that can alleviate this threat + - sample-si-1.yaml + - sample-si-2.yaml +securityIntentBinding: # Set of labels, annotations describing workloads who would be impacted by this threat + - sample-si-binding.yaml +preDeploymentConsiderations: [ ] # Anything that can be done in CI/CD pipelines that can alleviate this threat references: - - name: ref1 - url: + - name: ref1 + url: https://... - name: ref2 - url: + url: https://... ``` ## Security Threats - - [threatPackageInstallation](threats/execution/threatPackageInstallation.yaml) - - [threatTemplate](threats/threatTemplate.yaml) + +| Title | Description | Severity | Security Intents | References | +|:-----:|-------------|----------|------------|------------| ## Contributions welcome... -### Adding a new Security Intent +### Adding a new Security Threat 1. Fork and clone this repository -2. Create `security-intent-name.yaml` and `security-intent-binding-name.yaml` files -3. Copy the `intent.example` file and update it accordingly +2. Copy `res/threatTemplate.yaml` template file in [threats](threats)/`tactic` directory and edit the file's contents to + accurately reflect the specific threat information. For e.g., `execution` tactic from MITRE FiGHT. ```shell - cp intent.example intent + cp res/threatTemplate.yaml threats/execution/threat-name.yaml ``` +3. Create the Security Intent file(s) you listed in the `.securityIntents` field of the `threat-name.yaml` file, and + place them within the [intents](intents) directory. For e.g., + ```yaml + ... + securityIntents: + - sample-si.yaml + - sample-si-2.yaml + ... + ``` 4. Run `make` 5. Raise a PR diff --git a/intent.example b/intent.example deleted file mode 100644 index 03b3b26..0000000 --- a/intent.example +++ /dev/null @@ -1,10 +0,0 @@ -TITLE="Scenario-title" -DESCRIPTION="Detailed description of the scenario" -SEVERITY=High/Medium/Low -THREAT_ID="mapping to Threat IDs defined in O-RAN WG11 Threat Model document" -DETECTION_METHODS="Mechanisms to detect the threat" -MITIGATION_METHODS="Mechanisms to mitigate the threat" -SI_FILE=sample-si.yaml -SIB_FILE=sample-si-binding.yaml -PRE_DEPLOYMENT_CONSIDERATIONS="Anything that can be done in CI/CD pipelines that can alleviate this threat" -REFERENCES="ref1, ref2" diff --git a/res/footer.md b/res/footer.md new file mode 100644 index 0000000..6af166a --- /dev/null +++ b/res/footer.md @@ -0,0 +1,21 @@ +## Contributions welcome... + +### Adding a new Security Threat + +1. Fork and clone this repository +2. Copy `res/threatTemplate.yaml` template file in [threats](threats)/`tactic` directory and edit the file's contents to + accurately reflect the specific threat information. For e.g., `execution` tactic from MITRE FiGHT. + ```shell + cp res/threatTemplate.yaml threats/execution/threat-name.yaml + ``` +3. Create the Security Intent file(s) you listed in the `.securityIntents` field of the `threat-name.yaml` file, and + place them within the [intents](intents) directory. For e.g., + ```yaml + ... + securityIntents: + - sample-si.yaml + - sample-si-2.yaml + ... + ``` +4. Run `make` +5. Raise a PR diff --git a/tools/header.md b/res/header.md similarity index 100% rename from tools/header.md rename to res/header.md index 7d7759c..21747fe 100644 --- a/tools/header.md +++ b/res/header.md @@ -1,7 +1,7 @@ # Security Intents for Intent Driven Security + ![CI status](https://github.com/5GSEC/security-intents/actions/workflows/ci-verify.yml/badge.svg) Repository to hold Security Intents in standard template format. ![](res/nimbus.png) - diff --git a/res/threatTemplate.yaml b/res/threatTemplate.yaml new file mode 100644 index 0000000..d2f7133 --- /dev/null +++ b/res/threatTemplate.yaml @@ -0,0 +1,40 @@ +title: Scenario-title +description: Detailed description of the scenario +severity: High/Medium/Low +tags: + - oran + - 5gcore + - generic +detectionMethods: # Mechanisms to detect the threat + - name: Application log + tag: + - mitre/ds0015 + description: Description # Optional + url: https://... + - name: Process + tag: + - accuknox/ax0015 + description: Description # Optional + url: https://... +mitigationMethods: # Mechanisms to mitigate the threat + - name: Update Software + tag: + - mitre/ds0015 + description: desc + url: https://... + - name: User Account Management + tag: + - accuknox/ax0015 + description: desc + url: https://... +securityIntents: + - sample-si-1.yaml + - sample-si-2.yaml +securityIntentBinding: # Set of labels, annotations describing workloads who would be impacted by this threat + - sample-si-binding.yaml +preDeploymentConsiderations: [ ] # Anything that can be done in CI/CD pipelines that can alleviate this threat +references: + - name: ref1 + url: https://... + - name: ref2 + url: https://... diff --git a/scripts/gendoc.sh b/scripts/gendoc.sh new file mode 100755 index 0000000..b24b015 --- /dev/null +++ b/scripts/gendoc.sh @@ -0,0 +1,115 @@ +#!/usr/bin/env bash + +INTENTS_DIR=intents +THREATS_DIR=threats +HDR_MD=res/header.md +FTR_MD=res/footer.md +MD="README.md" + +prerequisites(){ + if [ ! `command -v yq` ]; then + echo "Please install yq https://github.com/mikefarah/yq#install" + exit 1 + fi + if [ ! `command -v jq` ]; then + echo "Please install jq https://github.com/jqlang/jq#installation" + exit 1 + fi +} + +writeThreatTemplateFile() { + cat >>$MD <>${MD} + cat res/threatTemplate.yaml >>${MD} + echo '```' >>${MD} +} + +extractRefs(){ + if [[ "$1" == "" ]]; then + printf "invalid use of extractRefs" + exit 1 + fi + REFERENCES="" + # https://stackoverflow.com/a/62899715 + while IFS=$'\t' read -r name url; do + ref="[$name]($url)" + if [[ $ref == "[]()" ]];then + continue + fi + REFERENCES="$ref, $REFERENCES" + done < <(yq e '.references[] | [.name, .url] | @tsv' $1) + # Remove trailing comma and space + REFERENCES="${REFERENCES%, }" + echo $REFERENCES +} + +extractSis(){ + if [[ "$1" == "" ]]; then + printf "invalid use of extractRefs" + exit 1 + fi + SIsPath="" + intents="$(yq e -o=j '.securityIntents' $1 | jq -r '.[]')" + for intent in $intents; do + intentPath=$(echo "[$intent]($INTENTS_DIR/$intent)") + SIsPath="$intentPath, $SIsPath" + done + # Remove trailing comma and space + SIsPath="${SIsPath%, }" + echo $SIsPath +} + +setThreatEntries() { + for file in $(find $1 -name '*.y*ml' -type f | sort); do + TITLE=$(yq '.title' $file) + DESCRIPTION=$(yq '.description' $file) + SEVERITY=$(yq '.severity' $file) + REFERENCES=$(extractRefs $file) + SIS_PATH=$(extractSis $file) + if [[ $SEVERITY == "null" ]]; then + SEVERITY="" + fi + cat >>${MD} <$MD < + +$(cat $HDR_MD) +EOF + writeThreatTemplateFile + cat >> ${MD} <>"$MD" <>$MD <>${MD} <>$MD <>${MD} - cat $THREATS_DIR/threatTemplate.yaml >>${MD} - echo '```' >>${MD} - fi -} - -generateIntentFilesForThreats() { - cat >>$MD <>${MD} <$MD < - -$(cat $HDR_MD) -EOF - echo "" >> $MD - writeIntents - echo "" >> $MD - writeThreatTemplatFile - echo "" >> $MD - generateIntentFilesForThreats - cat >>"$MD" <