Skip to content

Commit 1445955

Browse files
QuantumNeuralCoderQuantumNeuralCoder
authored
chore: refactored security guardian tool and security-guardian action. Enables local run. (#34158)
### Issue # (if applicable) None Closes #<issue number here>. NA ### Reason for this change With this change, developers can locally run security guardian against committed files to detect changed .template.json and run the 2 part scanner 1. cfn-guard to detect inline 2. custom scanner to detect intrinsics Please note that this will detect templates where the developer has explicitly provided broadened scope permissions like new AccountPrincipal(); We will use this as an opportunity to review if that is really needed or can be scoped down. ```bash > cd tools/@aws-cdk/security-guardian >yarn security-guardian ``` ### Description of changes ### Describe any new or updated permissions being added ### Description of how you validated changes ### Checklist - [ x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent e37faed commit 1445955

File tree

10 files changed

+519
-99
lines changed

10 files changed

+519
-99
lines changed

‎.github/workflows/security-guardian.yml

Lines changed: 7 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -9,59 +9,25 @@ jobs:
99
- name: Checkout
1010
uses: actions/checkout@v4
1111
with:
12-
fetch-depth: 0 # Fetches full history
12+
fetch-depth: 0 # Required to enable full git diff
1313

14-
- name: Get list of changed .template.json files
15-
id: filter_files
16-
run: |
17-
echo "Getting changed CloudFormation templates..."
18-
mkdir -p changed_templates
19-
20-
git fetch origin main --depth=1
21-
22-
base_sha="${{ github.event.pull_request.base.sha }}"
23-
head_sha="${{ github.event.pull_request.head.sha }}"
24-
if [[ -z "$base_sha" ]]; then base_sha=$(git merge-base origin/main HEAD); fi
25-
if [[ -z "$head_sha" ]]; then head_sha=HEAD; fi
26-
27-
git diff --name-status "$base_sha" "$head_sha" \
28-
| grep -E '^(A|M)\s+.*\.template\.json$' \
29-
| awk '{print $2}' > changed_files.txt || true
30-
31-
while IFS= read -r file; do
32-
if [ -f "$file" ]; then
33-
safe_name=$(echo "$file" | sed 's|/|_|g')
34-
cp "$file" "changed_templates/$safe_name"
35-
else
36-
echo "::warning::Changed file not found in workspace: $file"
37-
fi
38-
done < changed_files.txt
39-
40-
if [ -s changed_files.txt ]; then
41-
echo "files_changed=true" >> $GITHUB_OUTPUT
42-
else
43-
echo "files_changed=false" >> $GITHUB_OUTPUT
44-
fi
45-
4614
- name: Install cfn-guard
47-
if: steps.filter_files.outputs.files_changed == 'true'
4815
run: |
4916
mkdir -p $HOME/.local/bin
5017
curl -L -o cfn-guard.tar.gz https://github.com/aws-cloudformation/cloudformation-guard/releases/latest/download/cfn-guard-v3-x86_64-ubuntu-latest.tar.gz
5118
tar -xzf cfn-guard.tar.gz
5219
mv cfn-guard-v3-*/cfn-guard $HOME/.local/bin/cfn-guard
5320
chmod +x $HOME/.local/bin/cfn-guard
5421
echo "$HOME/.local/bin" >> $GITHUB_PATH
55-
22+
5623
- name: Install & Build security-guardian
57-
if: steps.filter_files.outputs.files_changed == 'true'
5824
run: yarn install --frozen-lockfile && cd tools/@aws-cdk/security-guardian && yarn build
5925

60-
- name: Run cfn-guard if templates changed
61-
if: steps.filter_files.outputs.files_changed == 'true'
26+
- name: Run Security Guardian
6227
uses: ./tools/@aws-cdk/security-guardian
6328
with:
64-
data_directory: './changed_templates'
65-
rule_set_path: './tools/@aws-cdk/security-guardian/rules/trust_scope_rules.guard'
29+
base_sha: ${{ github.event.pull_request.base.sha }}
30+
head_sha: ${{ github.event.pull_request.head.sha }}
31+
rule_set_path: './tools/@aws-cdk/security-guardian/rules'
6632
show_summary: 'fail'
67-
output_format: 'single-line-summary'
33+
output_format: 'json'

‎tools/@aws-cdk/security-guardian/README.md

Lines changed: 55 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,41 @@
11
# Security Guardian
22

3-
A GitHub Action tool designed to
4-
- detect broadly scoped inline policies in `*.template.json` files in incoming PRs and validate changed AWS CloudFormation templates against custom [cfn-guard](https://github.com/aws-cloudformation/cloudformation-guard) rules. Supports local paths for custom rule sets.
5-
- [in future] detect broadly scoped CFN intrinsic statements
3+
A GitHub Action and CLI tool that helps detect broadly scoped IAM principals in CloudFormation templates by:
4+
5+
- Validating **changed** `*.template.json` files in pull requests using custom [cfn-guard v3](https://github.com/aws-cloudformation/cloudformation-guard) rules.
6+
- Detecting **broadly scoped IAM principals** using CloudFormation **intrinsic functions** (e.g., `Fn::Join` with `:root`).
67

78
---
89

910
## Features
1011

11-
- Validates only changed `*.template.json` files in PRs
12-
- Supports `cfn-guard v3`
13-
- Accepts rules from a local file or remote URL
14-
- Outputs validation results in summary format
12+
Validates **only changed** templates in a PR
13+
Supports **cfn-guard v3** with rule sets
14+
Scans for **broad IAM principals using intrinsics**
15+
Runs locally and in GitHub Actions
16+
Outputs human-readable and machine-parsable summaries
1517

1618
---
1719

18-
## Inputs
19-
20-
| Name | Description | Required | Default |
21-
|------------------|-------------------------------------------------------------------|----------|-----------------------|
22-
| `data_directory` | Directory containing templates to validate | Yes | |
23-
| `rule_file_path` | Local path to the rules file | Yes | |
24-
| `show_summary` | Whether to show summary output (`fail`, `warn`, `none`) | No | `fail` |
25-
| `output_format` | Output format (`single-line-summary`, `json`, etc.) | No | `single-line-summary` |
20+
## Inputs (GitHub Action)
2621

27-
> `data_directory` and `rule_file_path` must be set.
22+
| Name | Description | Required | Default |
23+
|------------------|------------------------------------------------------|----------|-----------------------|
24+
| `rule_set_path` | Local path to the cfn-guard rules file | No | `./rules` |
25+
| `show_summary` | Show summary (`none`, `all`, `pass`, `fail`, `skip`) | No | `fail` |
26+
| `output_format` | Output format (`single-line-summary`, `json`, etc.) | No | `single-line-summary` |
27+
| `base_sha` | Commit SHA to compare against | No | `origin/main` |
28+
| `head_sha` | The commit SHA for the head (current) branch or PR | No | `HEAD` |
2829

2930
---
3031

31-
## Usage
32+
## Usage (GitHub Action)
3233

3334
```yaml
34-
- name: Run CFN Guard
35+
- name: Run Security Guardian
3536
uses: ./tools/@aws-cdk/security-guardian
3637
with:
37-
data_directory: './changed_templates'
38-
rule_set_path: './tools/@aws-cdk/security-guardian/rules/trust_scope_rules.guard'
38+
rule_set_path: './tools/@aws-cdk/security-guardian/rules'
3939
show_summary: 'fail'
4040
output_format: 'single-line-summary'
4141
```
@@ -44,28 +44,52 @@ A GitHub Action tool designed to
4444
4545
## Local Development
4646
47-
### 1. Build
47+
### 1. Install Dependencies
4848
```bash
49-
npm install
50-
npm run build
49+
cd tools/@aws-cdk/security-guardian && yarn install
5150
```
5251

5352
### 2. Run Locally
53+
The tool automatically detects changed templates and validates them.
54+
5455
```bash
55-
node dist/index.js \
56-
--data_directory=./changed_templates \
57-
--rule_file_path=./rules.guard \
58-
--output_format=single-line-summary \
59-
--show_summary=fail
56+
yarn security-guardian
6057
```
6158

59+
> You can override defaults using:
60+
> - `--base_sha=origin/main`
61+
> - `--output_format=json`
62+
> - `--show_summary=warn`
63+
6264
---
6365

64-
## Acknowledgments
66+
## Output
67+
68+
In addition to validation results from `cfn-guard`, the tool logs detailed findings from the intrinsic scan (if applicable), such as:
6569

66-
Built on top of [cfn-guard](https://github.com/aws-cloudformation/cloudformation-guard) and [GitHub Actions Toolkit](https://github.com/actions/toolkit).
70+
```
71+
detailed_output File: changed_templates/example.template.json
72+
{
73+
"Action": "kms:*",
74+
"Effect": "Allow",
75+
"Principal": {
76+
"AWS": {
77+
"Fn::Join": [
78+
"",
79+
["arn:", { "Ref": "AWS::Partition" }, ":iam::", { "Ref": "AWS::AccountId" }, ":root"]
80+
]
81+
}
82+
},
83+
"Resource": "*"
84+
}
85+
```
6786

6887
---
6988

70-
Happy Guarding!
89+
## Acknowledgments
90+
91+
Built with care on top of [cfn-guard](https://github.com/aws-cloudformation/cloudformation-guard) and the [GitHub Actions Toolkit](https://github.com/actions/toolkit).
92+
93+
---
7194

95+
Happy Guarding!

0 commit comments

Comments
 (0)