fix: Fix Auto generation of Readme

Signed-off-by: Anurag Rajawat <[email protected]>

Makefile

@@ -1,2 +1,2 @@
 all:
-	@./tools/gendoc.sh
+	@./scripts/gendoc.sh

README.md

@@ -1,67 +1,80 @@
-<!-- THIS IS AN AUTO-GENERATED FILE by ./tools/gendoc.sh. DO NOT EDIT MANUALLY -->
+<!-- THIS IS AN AUTO-GENERATED FILE by ./scripts/gendoc.sh. DO NOT EDIT MANUALLY -->
 
 # 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

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

tools/header.md → 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)
-

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://...

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 <<EOF
+
+## Security Threat Template
+EOF
+  echo '```yaml' >>${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} <<EOF
+   | [$TITLE]($file) | $DESCRIPTION | $SEVERITY | $SIS_PATH |$REFERENCES |
+EOF
+  done;
+}
+
+forEveryThreat() {
+   if [[ "$1" == "" ]]; then
+     printf "invalid use of forEveryThreat"
+     exit 1
+   fi
+   if [[ -d $THREATS_DIR ]]; then
+     while read dir; do
+       $1 $dir
+     done < <(find $THREATS_DIR -mindepth 1 -maxdepth 1 -type d | sort)
+   fi
+}
+
+main() {
+  cat >$MD <<EOF
+<!-- THIS IS AN AUTO-GENERATED FILE by $0. DO NOT EDIT MANUALLY -->
+
+$(cat $HDR_MD)
+EOF
+  writeThreatTemplateFile
+  cat >> ${MD} <<EOF
+
+## Security Threats
+
+| Title | Description | Severity | Security Intents | References |
+|:-----:|-------------|----------|------------|------------|
+EOF
+  forEveryThreat setThreatEntries
+  cat >>"$MD" <<EOF
+
+$(cat $FTR_MD)
+EOF
+}
+
+prerequisites
+main