Skip to content
This repository was archived by the owner on Jan 24, 2025. It is now read-only.

Commit fc28dd3

Browse files
austinsongeraustinsonger
authored
Update README.md
1 parent 103c47a commit fc28dd3

File tree

1 file changed

+226
-1
lines changed

1 file changed

+226
-1
lines changed

‎README.md

+226-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,228 @@
1-
# AWS Inspector Results for EC2 Instances
1+
# Vulnerability Scan GitHub Action for Amazon Inspector
2+
3+
Amazon Inspector is a vulnerability management service that scans AWS workloads for known software vulnerabilities.
4+
5+
This GitHub Action allows you to scan EC2 instances for software vulnerabilities using Amazon Inspector from your GitHub Actions workflows.
6+
7+
An active AWS account is required to use this action.
8+
9+
## Overview
10+
This action works by utilizing Amazon Inspector to scan specified EC2 instances for known vulnerabilities.
11+
12+
## Prerequisites
13+
14+
- Required: You must have an active AWS account to use this action.
15+
- Required: You must have read access to the InspectorScan API.
16+
- Required: You must configure AWS authentication for use in GitHub action workflows.
17+
- Required: Create a GitHub Actions workflow if you do not already have one.
18+
19+
## Usage
20+
21+
### Quick Start
22+
23+
Perform the following steps to quickly add this action to your GitHub Actions pipeline:
24+
25+
```
26+
name: Scan EC2 Instances with Amazon Inspector
27+
on: [push]
28+
jobs:
29+
daily_job:
30+
runs-on: ubuntu-latest
31+
32+
# change this to match your GitHub Secrets environment
33+
environment:
34+
name: your_github_secrets_environment
35+
36+
steps:
37+
38+
# modify this block based on how you authenticate to AWS
39+
# make sure you have permission to access the Inspector ScanEC2 API
40+
# https://docs.aws.amazon.com/inspector/latest/user/configure-cicd-account.html#cicd-iam-role
41+
- name: Configure AWS credentials
42+
uses: aws-actions/configure-aws-credentials@v4
43+
with:
44+
aws-region: "us-east-1"
45+
role-to-assume: "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>"
46+
47+
# Check out your repository if needed
48+
- name: Checkout this repository
49+
uses: actions/checkout@v4
50+
51+
# modify this block to scan your intended EC2 instances
52+
- name: Inspector Scan
53+
id: inspector
54+
uses: aws-actions/[email protected]
55+
with:
56+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
57+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
58+
aws-region: ${{ secrets.AWS_REGION }}
59+
assessment-run-arn: 'arn:aws:inspector:us-west-2:123456789012:assessment-run/assessment-run-id'
60+
61+
# If enabled, this setting will display Inspector's vulnerability scan findings
62+
# as a GitHub actions step summary. See here for an example step summary:
63+
# https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/actions/runs/8800085041
64+
display_vulnerability_findings: "enabled"
65+
66+
# Set vulnerability thresholds; if the number of vulnerabilities is
67+
# equal to or greater than any of the specified thresholds, this
68+
# action will set the 'vulnerability_threshold_exceeded'
69+
# output flag to 1.
70+
critical_threshold: 1
71+
high_threshold: 1
72+
medium_threshold: 1
73+
low_threshold: 1
74+
other_threshold: 1
75+
76+
# Additional input arguments are available to control scan behavior.
77+
# See 'action.yml' for additional input/output options.
78+
79+
80+
# The following steps illustrate how to
81+
# display scan results in the GitHub Actions job terminal.
82+
- name: Display Inspector vulnerability scan results (JSON)
83+
run: cat ${{ steps.inspector.outputs.inspector_scan_results }}
84+
85+
- name: Display Inspector vulnerability scan results (CSV)
86+
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
87+
88+
- name: Display Inspector vulnerability scan results (Markdown)
89+
run: cat ${{ steps.inspector.outputs.inspector_scan_results_markdown }}
90+
91+
92+
# The following steps illustrate how to
93+
# upload scan results as a GitHub actions job artifact
94+
- name: Upload Scan Results
95+
uses: actions/upload-artifact@v4
96+
with:
97+
name: Inspector Vulnerability Scan Artifacts
98+
path: |
99+
${{ steps.inspector.outputs.inspector_scan_results }}
100+
${{ steps.inspector.outputs.inspector_scan_results_csv }}
101+
${{ steps.inspector.outputs.inspector_scan_results_markdown }}
102+
103+
# This step illustrates how to add custom logic if
104+
# the vulnerability threshold is exceeded. This example
105+
# simply prints the 'vulnerability_threshold_exceeded' value
106+
# to the GitHub actions job terminal.
107+
# Replace 'echo' with 'exit' if you want to fail the job.
108+
- name: On vulnerability threshold exceeded
109+
run: echo ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
110+
```
111+
112+
113+
114+
### Configuring Vulnerability Scan Outputs
115+
116+
By default, this action only displays the number of vulnerabilities detected in the GitHub Actions job terminal. Detailed findings are optional and configurable as JSON, CSV, or Markdown.
117+
118+
The below example shows how to enable action outputs in various locations and formats.
119+
120+
```
121+
- name: Scan EC2 instances
122+
id: inspector
123+
uses: aws/[email protected]
124+
with:
125+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
126+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
127+
aws-region: ${{ secrets.AWS_REGION }}
128+
assessment-run-arn: 'arn:aws:inspector:us-west-2:123456789012:assessment-run/assessment-run-id'
129+
display_vulnerability_findings: "enabled"
130+
131+
# Display Inspector results in the GitHub Actions terminal
132+
- name: Display Inspector vulnerability scan results (JSON)
133+
run: cat ${{ steps.inspector.outputs.inspector_scan_results }}
134+
135+
- name: Display Inspector vulnerability scan results (CSV)
136+
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
137+
138+
- name: Display Inspector vulnerability scan results (markdown)
139+
run: cat ${{ steps.inspector.outputs.inspector_scan_results_markdown }}
140+
141+
142+
# Upload Inspector outputs as a .zip that can be downloaded
143+
# from the GitHub actions job summary page.
144+
- name: Upload Scan Results
145+
id: inspector
146+
uses: actions/upload-artifact@v4
147+
with:
148+
name: Inspector Vulnerability Scan Artifacts
149+
path: |
150+
${{ steps.inspector.outputs.inspector_scan_results }}
151+
${{ steps.inspector.outputs.inspector_scan_results_csv }}
152+
153+
```
154+
155+
### Configuring Vulnerability Thresholds
156+
157+
This action allows the user to set vulnerability thresholds.
158+
159+
Vulnerability thresholds can be used to support custom logic, such as failing the workflow if any vulnerabilities are found.
160+
161+
```
162+
- name: Invoke Amazon Inspector Scan
163+
id: inspector
164+
uses: aws/[email protected]
165+
with:
166+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
167+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
168+
aws-region: ${{ secrets.AWS_REGION }}
169+
assessment-run-arn: 'arn:aws:inspector:us-west-2:123456789012:assessment-run/assessment-run-id'
170+
display_vulnerability_findings: "enabled"
171+
172+
# If the number of vulnerabilities equals or exceeds
173+
# any of the specified vulnerability thresholds, this action
174+
# sets a flag, 'vulnerability_threshold_exceeded' to 1, else 0.
175+
# To ignore thresholds for a given severity, set its value to 0.
176+
# This example sets 'vulnerability_threshold_exceeded' flag if
177+
# one or more criticals, highs, or medium severity vulnerabilities
178+
# are found; lows and other type vulnerabilities will not set
179+
# the 'vulnerability_threshold_exceeded' flag.
180+
critical_threshold: 1
181+
high_threshold: 1
182+
medium_threshold: 1
183+
low_threshold: 0
184+
other_threshold: 0
185+
186+
# Fail the job with 'exit 1' if vuln threshold flag is set
187+
- name: On vulnerability threshold exceeded
188+
run: exit ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
189+
190+
```
191+
192+
193+
## Action Inputs and Outputs
194+
195+
196+
### Input Options
197+
198+
| **Name** | **Description** | **Required** | **Default** |
199+
| ------------------------------ | ------------------------------------------------------------ | ------------ | ----------- |
200+
| aws-access-key-id | AWS Access Key ID for accessing Amazon Inspector | True | - |
201+
| aws-secret-access-key | AWS Secret Access Key for accessing Amazon Inspector | True | - |
202+
| aws-region | AWS Region where your EC2 instances are located | True | - |
203+
| assessment-run-arn | Amazon Inspector Assessment Run ARN | True | - |
204+
| display_vulnerability_findings | If set to "enabled", the action will display detailed vulnerability findings in the action summary page | True | disabled |
205+
| critical_threshold | Specifies the number of critical vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag | False | 0 |
206+
| high_threshold | Specifies the number of high vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag | False | 0 |
207+
| medium_threshold | Specifies the number of medium vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag | False | 0 |
208+
| low_threshold | Specifies the number of low vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag | False | 0 |
209+
| other_threshold | Specifies the number of other vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag | False | 0 |
210+
211+
### Output Options
212+
213+
| **Name** | **Description** |
214+
| -------------------------------- | ------------------------------------------------------------ |
215+
| inspector_scan_results | The file path to the Inspector vulnerability scan findings in JSON format |
216+
| inspector_scan_results_csv | The file path to the Inspector vulnerability scan findings in CSV format |
217+
| inspector_scan_results_markdown | The file path to the Inspector vulnerability scan findings in markdown format |
218+
| vulnerability_threshold_exceeded | This variable is set to 1 if any vulnerability threshold was exceeded, otherwise it is 0. This variable can be used to trigger custom logic, such as failing the job if vulnerabilities were detected |
219+
220+
221+
222+
223+
224+
225+
226+
2227

3228

0 commit comments

Comments
 (0)