Skip to content

Commit a4e8367

Browse files
jfrogdixitjfrogdixit
committed
Integration with OWASP dependencycheck
1 parent f7e9683 commit a4e8367

File tree

8 files changed

+838
-0
lines changed

8 files changed

+838
-0
lines changed

‎.github/workflows/owasp-depcheck-evidence-example.yml‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
name: "Dependency Check with Evidence Integration"
2+
on:
3+
workflow_dispatch:
4+
5+
permissions:
6+
id-token: write
7+
contents: read
8+
9+
env:
10+
REGISTRY_DOMAIN: ${{ vars.JF_URL }}
11+
REPO_NAME: 'maven-depcheck-local'
12+
PACKAGE_NAME: 'simple-java-depcheck'
13+
VERSION: ${{ github.run_number }}
14+
BUILD_NAME: 'depcheck-maven-build'
15+
ATTACH_OPTIONAL_CUSTOM_MARKDOWN_TO_EVIDENCE: true
16+
17+
jobs:
18+
package-java-project-with-depcheck-evidence:
19+
runs-on: ubuntu-latest
20+
steps:
21+
# Setup JFrog CLI
22+
- name: Setup jfrog cli
23+
uses: jfrog/setup-jfrog-cli@v4
24+
env:
25+
JF_URL: ${{ vars.ARTIFACTORY_URL }}
26+
JF_ACCESS_TOKEN: ${{ secrets.ARTIFACTORY_ACCESS_TOKEN }}
27+
- name: Checkout repository
28+
uses: actions/checkout@v4
29+
30+
- name: Set up JDK 21
31+
uses: actions/setup-java@v4
32+
with:
33+
java-version: '21'
34+
distribution: 'temurin'
35+
36+
- name: Cache Maven dependencies
37+
uses: actions/cache@v4
38+
with:
39+
path: ~/.m2
40+
key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
41+
restore-keys: ${{ runner.os }}-m2
42+
43+
# Build and publish the Java package to JFrog Artifactory
44+
- name: Build and publish Java package to Artifactory
45+
run: |
46+
cd examples/depcheck/src
47+
mvn clean compile
48+
mvn package
49+
echo "Deploying package to Artifactory"
50+
jf rt upload target/*.jar $REPO_NAME/$PACKAGE_NAME/$VERSION/ --build-name=$BUILD_NAME --build-number=${{ github.run_number }}
51+
echo "Publishing build info"
52+
jf rt build-publish $BUILD_NAME ${{ github.run_number }}
53+
54+
- name: Dependency Check Scan
55+
uses: dependency-check/[email protected]
56+
env:
57+
# actions/setup-java@v1 changes JAVA_HOME so it needs to be reset to match the depcheck image
58+
JAVA_HOME: /opt/jdk
59+
with:
60+
project: '${{ env.PACKAGE_NAME }}'
61+
format: 'JSON'
62+
path: examples/depcheck/src/target
63+
out: ${{ github.workspace }}/reports
64+
args: >
65+
--noupdate
66+
67+
# This is an optional step to generate a custom markdown report
68+
- name: Generate optional custom markdown report
69+
if: env.ATTACH_OPTIONAL_CUSTOM_MARKDOWN_TO_EVIDENCE == 'true'
70+
run: |
71+
cd ${{ github.workspace }}
72+
if [ -f "reports/dependency-check-report.json" ]; then
73+
python examples/depcheck/scripts/markdown-converter.py reports/dependency-check-report.json
74+
echo "Custom markdown report generated"
75+
else
76+
echo "Warning: dependency-check-report.json not found"
77+
exit 1
78+
fi
79+
80+
# Attaching the evidence to associated build
81+
- name: Attach evidence to associated build
82+
run: |
83+
jf evd create \
84+
--build-name $BUILD_NAME \
85+
--build-number ${{ github.run_number }} \
86+
--key "${{ secrets.PRIVATE_KEY }}" \
87+
--key-alias "${{ vars.EVIDENCE_KEY_ALIAS }}" \
88+
--predicate ./reports/dependency-check-report.json \
89+
--predicate-type https://owasp.org/dependency-check \
90+
${{ env.ATTACH_OPTIONAL_CUSTOM_MARKDOWN_TO_EVIDENCE == 'true' && '--markdown "dependency-check-report.md"' || '' }}

‎examples/depcheck/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Compiled class file
2+
*.class
3+
4+
# Log file
5+
*.log
6+
7+
# BlueJ files
8+
*.ctxt
9+
10+
# Mobile Tools for Java (J2ME)
11+
.mtj.tmp/
12+
13+
# Package Files #
14+
*.jar
15+
*.war
16+
*.nar
17+
*.ear
18+
*.zip
19+
*.tar.gz
20+
*.rar
21+
22+
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
23+
hs_err_pid*
24+
replay_pid*

‎examples/depcheck/README.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# **OWASP Dependency Check Evidence Example**
2+
3+
This repository provides a working example of a GitHub Actions workflow that automates Java Maven project security scanning using **OWASP Dependency Check**. It then attaches the resulting vulnerability report as signed, verifiable evidence to the package in **JFrog Artifactory**.
4+
5+
This workflow is an essential pattern for DevSecOps, creating a traceable, compliant, and secure software supply chain with comprehensive security vulnerability assessment.
6+
7+
### **Key Features**
8+
9+
* **Automated Build & Deploy**: Builds a Java Maven project and deploys it to Artifactory.
10+
* **OWASP Dependency Check**: Runs comprehensive security vulnerability scanning using OWASP Dependency Check.
11+
* **Vulnerability Report Generation**: Generates detailed JSON vulnerability reports with CVSS scoring.
12+
* **Optional Markdown Report**: Includes a helper script to generate a human-readable Markdown summary from the Dependency Check JSON results.
13+
* **Signed Evidence Attachment**: Attaches the vulnerability scan results to the corresponding package version in Artifactory using jf evd create, cryptographically signing it for integrity.
14+
* **OWASP Dependency Check**: [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) security vulnerability scanner
15+
16+
### **Workflow**
17+
18+
The following diagram illustrates the sequence of operations performed by the GitHub Actions workflow.
19+
20+
```mermaid
21+
graph TD
22+
A[Workflow Dispatch Trigger] --> B[Setup JFrog CLI]
23+
B --> C[Checkout Repository]
24+
C --> D[Setup JDK 21]
25+
D --> E[Build and Publish Java Package to Artifactory]
26+
E --> F[Run OWASP Dependency Check Scan]
27+
F --> G[Generate Vulnerability Report]
28+
G --> H{Attach Optional Custom Markdown Report?}
29+
H -->|Yes| I[Generate Custom Markdown Report]
30+
H -->|No| J[Skip Markdown Report]
31+
I --> K[Attach Evidence to Package]
32+
J --> K[Attach Evidence to Package]
33+
```
34+
35+
---
36+
37+
### **1. Prerequisites**
38+
39+
Before running this workflow, you must have:
40+
41+
* JFrog CLI 2.65.0 or above (installed automatically in the workflow)
42+
* An Artifactory repository of type maven (e.g., maven-depcheck-local).
43+
* A private key and a corresponding key alias configured in your JFrog Platform for signing evidence.
44+
* The following GitHub repository variables:
45+
* `JF_URL` (Artifactory base URL, e.g. `https://mycompany.jfrog.io`)
46+
* `EVIDENCE_KEY_ALIAS` (Key alias for signing evidence)
47+
* The following GitHub repository secrets:
48+
* `ARTIFACTORY_ACCESS_TOKEN` (Artifactory access token)
49+
* `PRIVATE_KEY` (Private key for signing evidence)
50+
51+
### Environment Variables Used
52+
53+
* `REGISTRY_DOMAIN` - Maven registry domain
54+
* `REPO_NAME` - Maven repository name
55+
* `PACKAGE_NAME` - Maven artifact name
56+
* `VERSION` - Build version (uses GitHub run number)
57+
* `BUILD_NAME` - Build information name in Artifactory
58+
* `ATTACH_OPTIONAL_CUSTOM_MARKDOWN_TO_EVIDENCE` - Controls markdown report generation
59+
60+
### **2. Configuration**
61+
62+
To use this workflow, you must configure the following GitHub Repository Secrets and Variables.
63+
64+
#### **GitHub Secrets**
65+
66+
Navigate to Settings > Secrets and variables > Actions and create the following secrets:
67+
68+
| Secret Name | Description |
69+
| :---- | :---- |
70+
| ARTIFACTORY_ACCESS_TOKEN | A valid JFrog Access Token with permissions to read, write, and annotate in your target repository. |
71+
| PRIVATE_KEY | The private key used to sign the evidence. This key corresponds to the alias configured in JFrog Platform. |
72+
73+
#### **GitHub Variables**
74+
75+
Navigate to Settings > Secrets and variables > Actions and create the following variables:
76+
77+
| Variable Name | Description | Example Value |
78+
| :---- | :---- | :---- |
79+
| JF_URL | The base URL of your JFrog Platform instance. | https://mycompany.jfrog.io |
80+
| EVIDENCE_KEY_ALIAS | The alias for the public key in JFrog Platform used to verify the evidence signature. | my-signing-key-alias |
81+
82+
#### **Workflow Environment Variables**
83+
84+
You can also customize the workflow's behavior by modifying the env block in the .github/workflows/owasp-depcheck-evidence-example.yml file:
85+
86+
| Variable Name | Description | Default Value |
87+
| :---- | :---- | :---- |
88+
| REPO_NAME | The name of the target Maven repository in Artifactory. | maven-depcheck-local |
89+
| PACKAGE_NAME | The name of the Maven artifact to be built and deployed. | simple-java-depcheck |
90+
| BUILD_NAME | The name assigned to the build information in Artifactory. | depcheck-maven-build |
91+
| ATTACH_OPTIONAL_CUSTOM_MARKDOWN_TO_EVIDENCE | Set to true to generate and attach a Markdown report alongside the JSON evidence. Set to false to skip this step. | true |
92+
93+
---
94+
95+
### **3. Usage**
96+
97+
This workflow is triggered manually.
98+
99+
1. Navigate to the **Actions** tab of your forked repository.
100+
2. In the left sidebar, click on the **Dependency Check with Evidence Integration** workflow.
101+
3. Click the **Run workflow** dropdown button. You can leave the default branch selected.
102+
4. Click the green **Run workflow** button.
103+
104+
## Repository Structure
105+
106+
```
107+
examples/depcheck/
108+
├── .github/workflows/
109+
│ └── owasp-depcheck-evidence-example.yml # Main workflow with evidence integration
110+
├── examples/depcheck/
111+
│ ├── src/ # Java Maven project
112+
│ │ ├── main/java/com/example/ # Source code
113+
│ │ └── pom.xml # Maven configuration
114+
│ └── scripts/
115+
│ └── markdown-converter.py # Evidence report converter
116+
└── README.md # This file
117+
```
118+
119+
## Workflow Overview
120+
121+
The GitHub Actions workflow (`owasp-depcheck-evidence-example.yml`) performs the following steps:
122+
123+
### 1. **Build and Package**
124+
- Sets up Java 21 environment
125+
- Builds the Maven project
126+
- Deploys artifacts to JFrog Artifactory
127+
128+
### 2. **Security Scanning**
129+
- Runs OWASP Dependency Check on built artifacts
130+
- Scans for known vulnerabilities in dependencies
131+
- Generates JSON vulnerability reports
132+
133+
### 3. **Evidence Generation**
134+
- Converts JSON reports to readable markdown format (optional)
135+
- Creates evidence reports suitable for attachment to packages
136+
- Provides comprehensive vulnerability analysis
137+
138+
### 4. **Evidence Attachment**
139+
- Publishes build information to JFrog Artifactory
140+
- Attaches signed evidence to builds in JFrog Artifactory
141+
- Uses cryptographic signing for evidence integrity
142+
- Creates verifiable security attestation
143+
144+
## Evidence Integration
145+
146+
This project follows the evidence management pattern from [JFrog Evidence Examples](https://github.com/jfrog/Evidence-Examples), where:
147+
148+
- **Security scan results** become verifiable evidence
149+
- **Markdown reports** provide human-readable evidence
150+
- **Evidence is attached** to packages for security attestation
151+
- **Signed evidence** ensures integrity and authenticity
152+
153+
## Local Development
154+
155+
For local development and testing:
156+
157+
```bash
158+
# Build the project locally
159+
cd examples/depcheck/src
160+
mvn clean compile package
161+
162+
# Run dependency check (requires OWASP Dependency Check CLI)
163+
dependency-check --scan target/ --format JSON --out reports/
164+
165+
# Convert to markdown evidence
166+
python ../scripts/markdown-converter.py reports/dependency-check-report.json
167+
```
168+
169+
## Dependency Check Configuration
170+
171+
The workflow configures OWASP Dependency Check with:
172+
173+
- **Project Name**: Uses the package name for consistency
174+
- **Output Format**: JSON for processing, optional Markdown for evidence
175+
- **Scan Path**: Maven target directory (`examples/depcheck/src/target`)
176+
- **No Updates**: Uses cached vulnerability database (`--noupdate`)
177+
- **Evidence Type**: `https://owasp.org/dependency-check` predicate type
178+
- **Evidence Attachment**: Attaches evidence to build information in Artifactory
179+
180+
## Evidence Management
181+
182+
### Attaching Evidence to Builds
183+
184+
This workflow follows the JFrog Evidence Examples pattern by attaching evidence to builds:
185+
186+
1. **Build Evidence** - Security scan results attached to build information in Artifactory
187+
2. **Build Publishing** - Build information is published to Artifactory for evidence attachment
188+
3. **Signed Evidence** - Cryptographically signed vulnerability reports
189+
4. **Verifiable Evidence** - Evidence that can be verified using the configured key alias
190+
191+
### Evidence Types Generated
192+
193+
- **Dependency Check JSON Report** - Raw vulnerability data in JSON format
194+
- **Markdown Evidence Report** - Human-readable security summary (optional)
195+
- **Build Evidence** - Evidence attached to build information in Artifactory
196+
- **Signed Evidence** - Cryptographically signed evidence for integrity verification
197+
198+
## Security Considerations
199+
200+
- **CVSS Scoring**: Uses industry-standard Common Vulnerability Scoring System
201+
- **Vulnerability Assessment**: Comprehensive scanning of dependencies for known vulnerabilities
202+
- **Evidence Integrity**: Generated evidence is cryptographically signed for authenticity
203+
- **Audit Trail**: Complete record of security assessments with verifiable evidence
204+
- **CVE References**: Direct links to vulnerability databases for detailed information
205+
206+
## Contributing
207+
208+
This project follows the evidence management patterns established by JFrog Evidence Examples. Contributions should:
209+
210+
1. Maintain evidence integrity and verifiability
211+
2. Follow the established workflow patterns for security scanning
212+
3. Ensure vulnerability scan results are properly formatted
213+
4. Include appropriate documentation for evidence types
214+
5. Maintain consistency with the OWASP Dependency Check integration
215+
216+
## References
217+
218+
- [JFrog Evidence Examples](https://github.com/jfrog/Evidence-Examples) - Original inspiration and patterns
219+
- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) - Vulnerability scanning tool
220+
- [JFrog Evidence Management](https://jfrog.com/help/r/jfrog-artifactory-documentation/evidence-management-overview) - Evidence management documentation
221+
- [CVSS Scoring System](https://www.first.org/cvss/) - Vulnerability severity scoring

0 commit comments

Comments
 (0)