docs/soc-integration.md · Secure CI/CD Pipeline

44 lines · markdown

# Wiring the pipeline into the SOC lab
 
This pipeline doesn't stop at a green check. The `notify-soc` job posts the run
outcome to the same Shuffle instance that runs the SOC automation lab, so CI
security events land next to endpoint alerts.
 
## Why send CI events to a SOC
 
A failed secret scan or a newly vulnerable dependency is a security event. Treating
it like one - routing it to the same place analysts already watch - means a leaked
credential in a commit gets the same case-and-notify treatment as a Wazuh alert,
instead of sitting in a CI log nobody reads.
 
## What gets sent
 
`scripts/notify_soc.py` posts a small JSON document:
 
```json
{
  "source": "github-actions",
  "pipeline": "security-pipeline",
  "status": "failure",
  "outcome": "failure",
  "repository": "owner/secure-cicd-pipeline",
  "commit": "9f2c...",
  "actor": "username",
  "run_url": "https://github.com/owner/secure-cicd-pipeline/actions/runs/123"
}
```
 
## Shuffle side
 
In Shuffle, point a webhook trigger at a small workflow that branches on `outcome`:
 
1. On `failure`, open a TheHive case tagged `ci`, `pipeline`, severity Medium, with
   the run URL in the description so the analyst can jump straight to the failing job.
2. On `success`, drop a low-priority message in the CI channel and do nothing else.
 
## Setup
 
Add a repository secret named `SHUFFLE_WEBHOOK_URL` with the webhook from the
Shuffle workflow. If the secret is absent the job logs that it's skipping and exits
zero, so forks and clones don't fail the pipeline trying to reach a webhook they
don't have.

1	# Wiring the pipeline into the SOC lab
2
3	This pipeline doesn't stop at a green check. The `notify-soc` job posts the run
4	outcome to the same Shuffle instance that runs the SOC automation lab, so CI
5	security events land next to endpoint alerts.
6
7	## Why send CI events to a SOC
8
9	A failed secret scan or a newly vulnerable dependency is a security event. Treating
10	it like one - routing it to the same place analysts already watch - means a leaked
11	credential in a commit gets the same case-and-notify treatment as a Wazuh alert,
12	instead of sitting in a CI log nobody reads.
13
14	## What gets sent
15
16	`scripts/notify_soc.py` posts a small JSON document:
17
18	```json
19	{
20	"source": "github-actions",
21	"pipeline": "security-pipeline",
22	"status": "failure",
23	"outcome": "failure",
24	"repository": "owner/secure-cicd-pipeline",
25	"commit": "9f2c...",
26	"actor": "username",
27	"run_url": "https://github.com/owner/secure-cicd-pipeline/actions/runs/123"
28	}
29	```
30
31	## Shuffle side
32
33	In Shuffle, point a webhook trigger at a small workflow that branches on `outcome`:
34
35	1. On `failure`, open a TheHive case tagged `ci`, `pipeline`, severity Medium, with
36	the run URL in the description so the analyst can jump straight to the failing job.
37	2. On `success`, drop a low-priority message in the CI channel and do nothing else.
38
39	## Setup
40
41	Add a repository secret named `SHUFFLE_WEBHOOK_URL` with the webhook from the
42	Shuffle workflow. If the secret is absent the job logs that it's skipping and exits
43	zero, so forks and clones don't fail the pipeline trying to reach a webhook they
44	don't have.