Skip to content

Commit 2b048b3

Browse files
meysholdtona-agent
meysholdt
and
ona-agent
committed
Replace README with GitHub Security + Ona automations guide
Co-authored-by: Ona <no-reply@ona.com>
1 parent a775814 commit 2b048b3

1 file changed

Lines changed: 160 additions & 128 deletions

File tree

‎README.md‎

Lines changed: 160 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,173 +1,205 @@
1-
# Spring PetClinic Sample Application [![Build Status](https://github.com/spring-projects/spring-petclinic/actions/workflows/maven-build.yml/badge.svg)](https://github.com/spring-projects/spring-petclinic/actions/workflows/maven-build.yml)[![Build Status](https://github.com/spring-projects/spring-petclinic/actions/workflows/gradle-build.yml/badge.svg)](https://github.com/spring-projects/spring-petclinic/actions/workflows/gradle-build.yml)
1+
# GitHub Security + Ona Automations
22

3-
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/spring-projects/spring-petclinic) [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=7517918)
3+
This repo demonstrates how to set up GitHub's free security features on a public repository and use [Ona](https://ona.com) automations to fix findings automatically.
44

5-
## Understanding the Spring Petclinic application with a few diagrams
5+
The sample application is [Spring PetClinic](https://github.com/spring-projects/spring-petclinic) (Java/Maven).
66

7-
See the presentation here:
8-
[Spring Petclinic Sample Application (legacy slides)](https://speakerdeck.com/michaelisvy/spring-petclinic-sample-application?slide=20)
7+
## Security scanning tools
98

10-
> **Note:** These slides refer to a legacy, pre–Spring Boot version of Petclinic and may not reflect the current Spring Boot–based implementation.
11-
> For up-to-date information, please refer to this repository and its documentation.
9+
All tools below are free for public repos on GitHub's free org plan.
1210

11+
### Dependabot alerts
1312

14-
## Run Petclinic locally
13+
Dependabot monitors your dependency graph for known vulnerabilities and creates alerts under **Security > Dependabot**.
1514

16-
Spring Petclinic is a [Spring Boot](https://spring.io/guides/gs/spring-boot) application built using [Maven](https://spring.io/guides/gs/maven/) or [Gradle](https://spring.io/guides/gs/gradle/).
17-
Java 17 or later is required for the build, and the application can run with Java 17 or newer.
15+
For Maven projects, GitHub's dependency graph often can't resolve versions inherited from a parent BOM. The [`dependency-submission.yml`](.github/workflows/dependency-submission.yml) workflow solves this by running `mvn` to resolve the full dependency tree and submitting it to GitHub's dependency graph API.
1816

19-
You first need to clone the project locally:
17+
### Code scanning (CodeQL)
2018

21-
```bash
22-
git clone https://github.com/spring-projects/spring-petclinic.git
23-
cd spring-petclinic
24-
```
25-
If you are using Maven, you can start the application on the command-line as follows:
26-
27-
```bash
28-
./mvnw spring-boot:run
29-
```
30-
With Gradle, the command is as follows:
31-
32-
```bash
33-
./gradlew bootRun
34-
```
35-
36-
You can then access the Petclinic at <http://localhost:8080/>.
37-
38-
<img width="1042" alt="petclinic-screenshot" src="https://cloud.githubusercontent.com/assets/838318/19727082/2aee6d6c-9b8e-11e6-81fe-e889a5ddfded.png">
39-
40-
You can, of course, run Petclinic in your favorite IDE.
41-
See below for more details.
42-
43-
## Building a Container
44-
45-
There is no `Dockerfile` in this project. You can build a container image (if you have a docker daemon) using the Spring Boot build plugin:
46-
47-
```bash
48-
./mvnw spring-boot:build-image
49-
```
50-
51-
## In case you find a bug/suggested improvement for Spring Petclinic
52-
53-
Our issue tracker is available [here](https://github.com/spring-projects/spring-petclinic/issues).
54-
55-
## Database configuration
56-
57-
In its default configuration, Petclinic uses an in-memory database (H2) which
58-
gets populated at startup with data. The h2 console is exposed at `http://localhost:8080/h2-console`,
59-
and it is possible to inspect the content of the database using the `jdbc:h2:mem:<uuid>` URL. The UUID is printed at startup to the console.
19+
[CodeQL](https://codeql.github.com/) performs static analysis on your source code. GitHub's default setup analyzes Java and Actions code on every push and PR. Results appear under **Security > Code scanning**.
6020

61-
A similar setup is provided for MySQL and PostgreSQL if a persistent database configuration is needed. Note that whenever the database type changes, the app needs to run with a different profile: `spring.profiles.active=mysql` for MySQL or `spring.profiles.active=postgres` for PostgreSQL. See the [Spring Boot documentation](https://docs.spring.io/spring-boot/how-to/properties-and-configuration.html#howto.properties-and-configuration.set-active-spring-profiles) for more detail on how to set the active profile.
21+
### Trivy (filesystem scan)
6222

63-
You can start MySQL or PostgreSQL locally with whatever installer works for your OS or use docker:
23+
[Trivy](https://github.com/aquasecurity/trivy) scans dependency files (pom.xml, lock files, etc.) for known CVEs. The [`trivy.yml`](.github/workflows/trivy.yml) workflow runs a filesystem scan and uploads SARIF results to **Security > Code scanning**.
6424

65-
```bash
66-
docker run -e MYSQL_USER=petclinic -e MYSQL_PASSWORD=petclinic -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=petclinic -p 3306:3306 mysql:9.5
67-
```
68-
69-
or
70-
71-
```bash
72-
docker run -e POSTGRES_USER=petclinic -e POSTGRES_PASSWORD=petclinic -e POSTGRES_DB=petclinic -p 5432:5432 postgres:18.1
73-
```
74-
75-
Further documentation is provided for [MySQL](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/resources/db/mysql/petclinic_db_setup_mysql.txt)
76-
and [PostgreSQL](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/resources/db/postgres/petclinic_db_setup_postgres.txt).
77-
78-
Instead of vanilla `docker` you can also use the provided `docker-compose.yml` file to start the database containers. Each one has a service named after the Spring profile:
79-
80-
```bash
81-
docker compose up mysql
82-
```
25+
### OSV-Scanner
8326

84-
or
27+
[OSV-Scanner](https://github.com/google/osv-scanner) checks dependencies against the [OSV database](https://osv.dev/). The [`osv-scanner.yml`](.github/workflows/osv-scanner.yml) workflow runs on push (scheduled scan) and on PRs (diff scan to catch newly introduced vulnerabilities). Results upload to **Security > Code scanning**.
8528

86-
```bash
87-
docker compose up postgres
88-
```
89-
90-
## Test Applications
29+
## Ona automations
9130

92-
At development time we recommend you use the test applications set up as `main()` methods in `PetClinicIntegrationTests` (using the default H2 database and also adding Spring Boot Devtools), `MySqlTestApplication` and `PostgresIntegrationTests`. These are set up so that you can run the apps in your IDE to get fast feedback and also run the same classes as integration tests against the respective database. The MySql integration tests use Testcontainers to start the database in a Docker container, and the Postgres tests use Docker Compose to do the same thing.
31+
Two Ona automations in [`.ona/`](.ona/) use the GitHub CLI to fetch the highest-severity open alert, apply a fix, run tests, and open a PR.
9332

94-
## Compiling the CSS
33+
### `fix-dependabot-alert`
9534

96-
There is a `petclinic.css` in `src/main/resources/static/resources/css`. It was generated from the `petclinic.scss` source, combined with the [Bootstrap](https://getbootstrap.com/) library. If you make changes to the `scss`, or upgrade Bootstrap, you will need to re-compile the CSS resources using the Maven profile "css", i.e. `./mvnw package -P css`. There is no build profile for Gradle to compile the CSS.
35+
[`.ona/fix-dependabot-alert.yaml`](.ona/fix-dependabot-alert.yaml)
9736

98-
## Working with Petclinic in your IDE
37+
1. **Install gh CLI** if not present
38+
2. **Fetch** the highest-severity open Dependabot alert via `gh api`
39+
3. **Analyze** the alert and read the manifest to understand how the dependency is declared
40+
4. **Upgrade** the dependency to the patched version
41+
5. **Verify** with `./mvnw compile test` and `./mvnw dependency:tree`
42+
6. **Open a PR** with alert details, CVE, CVSS score, and verification checklist
9943

100-
### Prerequisites
44+
### `fix-codescan-alert`
10145

102-
The following items should be installed in your system:
46+
[`.ona/fix-codescan-alert.yaml`](.ona/fix-codescan-alert.yaml)
10347

104-
- Java 17 or newer (full JDK, not a JRE)
105-
- [Git command line tool](https://help.github.com/articles/set-up-git)
106-
- Your preferred IDE
107-
- Eclipse with the m2e plugin. Note: when m2e is available, there is a m2 icon in `Help -> About` dialog. If m2e is
108-
not there, follow the installation process [here](https://www.eclipse.org/m2e/)
109-
- [Spring Tools Suite](https://spring.io/tools) (STS)
110-
- [IntelliJ IDEA](https://www.jetbrains.com/idea/)
111-
- [VS Code](https://code.visualstudio.com)
48+
1. **Install gh CLI** if not present
49+
2. **Fetch** the highest-severity open code scanning alert via `gh api`
50+
3. **Analyze** the alert, read the affected source file and context
51+
4. **Fix** the issue (code change for CodeQL findings, dependency upgrade for Trivy/OSV findings)
52+
5. **Verify** with `./mvnw compile test`
53+
6. **Open a PR** with alert details and verification checklist
11254

113-
### Steps
55+
Both automations authenticate using the token from the git credential helper (`GITHUB_TOKEN` env var), avoiding the need for additional secrets.
11456

115-
1. On the command line run:
57+
## Set up on your own repo
11658

117-
```bash
118-
git clone https://github.com/spring-projects/spring-petclinic.git
119-
```
59+
### 1. Enable Dependabot alerts
12060

121-
1. Inside Eclipse or STS:
61+
Go to **Settings > Code security** and enable:
62+
- **Dependency graph** (on by default for public repos)
63+
- **Dependabot alerts**
12264

123-
Open the project via `File -> Import -> Maven -> Existing Maven project`, then select the root directory of the cloned repo.
65+
### 2. Add the Maven dependency submission workflow
12466

125-
Then either build on the command line `./mvnw generate-resources` or use the Eclipse launcher (right-click on project and `Run As -> Maven install`) to generate the CSS. Run the application's main method by right-clicking on it and choosing `Run As -> Java Application`.
67+
For Maven projects using a parent BOM (e.g., Spring Boot), create `.github/workflows/dependency-submission.yml`:
12668

127-
1. Inside IntelliJ IDEA:
69+
```yaml
70+
name: Maven Dependency Submission
12871

129-
In the main menu, choose `File -> Open` and select the Petclinic [pom.xml](pom.xml). Click on the `Open` button.
72+
on:
73+
push:
74+
branches: [ "main" ]
75+
paths:
76+
- 'pom.xml'
77+
- '.mvn/**'
78+
workflow_dispatch:
13079

131-
- CSS files are generated from the Maven build. You can build them on the command line `./mvnw generate-resources` or right-click on the `spring-petclinic` project then `Maven -> Generates sources and Update Folders`.
80+
permissions:
81+
contents: write
13282

133-
- A run configuration named `PetClinicApplication` should have been created for you if you're using a recent Ultimate version. Otherwise, run the application by right-clicking on the `PetClinicApplication` main class and choosing `Run 'PetClinicApplication'`.
83+
jobs:
84+
submit:
85+
runs-on: ubuntu-latest
86+
steps:
87+
- uses: actions/checkout@v4
13488

135-
1. Navigate to the Petclinic
89+
- name: Set up JDK 17
90+
uses: actions/setup-java@v4
91+
with:
92+
java-version: '17'
93+
distribution: 'adopt'
13694

137-
Visit [http://localhost:8080](http://localhost:8080) in your browser.
138-
139-
## Looking for something in particular?
95+
- name: Submit dependency graph
96+
uses: advanced-security/maven-dependency-submission-action@v4
97+
```
14098
141-
|Spring Boot Configuration | Class or Java property files |
142-
|--------------------------|---|
143-
|The Main Class | [PetClinicApplication](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java) |
144-
|Properties Files | [application.properties](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/resources) |
145-
|Caching | [CacheConfiguration](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java) |
99+
This resolves the full dependency tree with actual versions so Dependabot can match against known CVEs.
100+
101+
### 3. Add Trivy filesystem scanning
102+
103+
Create `.github/workflows/trivy.yml`:
104+
105+
```yaml
106+
name: trivy
107+
108+
on:
109+
push:
110+
branches: [ "main" ]
111+
pull_request:
112+
branches: [ "main" ]
113+
schedule:
114+
- cron: '29 6 * * 2'
115+
116+
permissions:
117+
contents: read
118+
119+
jobs:
120+
fs-scan:
121+
permissions:
122+
contents: read
123+
security-events: write
124+
actions: read
125+
name: Filesystem Scan
126+
runs-on: ubuntu-latest
127+
steps:
128+
- uses: actions/checkout@v4
129+
130+
- name: Run Trivy filesystem scanner
131+
uses: aquasecurity/trivy-action@0.35.0
132+
with:
133+
scan-type: 'fs'
134+
scan-ref: '.'
135+
format: 'sarif'
136+
output: 'trivy-fs-results.sarif'
137+
severity: 'CRITICAL,HIGH'
138+
139+
- name: Upload results to GitHub Security tab
140+
uses: github/codeql-action/upload-sarif@v3
141+
if: always()
142+
with:
143+
sarif_file: 'trivy-fs-results.sarif'
144+
category: 'trivy-fs'
145+
```
146146

147-
## Interesting Spring Petclinic branches and forks
147+
### 4. Add OSV-Scanner
148+
149+
Create `.github/workflows/osv-scanner.yml`:
150+
151+
```yaml
152+
name: OSV-Scanner
153+
154+
on:
155+
pull_request:
156+
branches: [ "main" ]
157+
merge_group:
158+
branches: [ "main" ]
159+
schedule:
160+
- cron: '39 0 * * 4'
161+
push:
162+
branches: [ "main" ]
163+
164+
permissions:
165+
security-events: write
166+
contents: read
167+
actions: read
168+
169+
jobs:
170+
scan-scheduled:
171+
if: ${{ github.event_name == 'push' || github.event_name == 'schedule' }}
172+
uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v2.0.0"
173+
with:
174+
fail-on-vuln: false
175+
scan-args: |-
176+
-r
177+
./
178+
scan-pr:
179+
if: ${{ github.event_name == 'pull_request' || github.event_name == 'merge_group' }}
180+
uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@v2.0.0"
181+
with:
182+
scan-args: |-
183+
-r
184+
./
185+
```
148186

149-
The Spring Petclinic "main" branch in the [spring-projects](https://github.com/spring-projects/spring-petclinic)
150-
GitHub org is the "canonical" implementation based on Spring Boot and Thymeleaf. There are
151-
[quite a few forks](https://spring-petclinic.github.io/docs/forks.html) in the GitHub org
152-
[spring-petclinic](https://github.com/spring-petclinic). If you are interested in using a different technology stack to implement the Pet Clinic, please join the community there.
187+
### 5. Enable CodeQL (optional)
153188

154-
## Interaction with other open-source projects
189+
Go to **Settings > Code security > Code scanning** and click **Set up** for CodeQL. GitHub's default setup works for most repos. See [GitHub's CodeQL docs](https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages) for advanced configuration.
155190

156-
One of the best parts about working on the Spring Petclinic application is that we have the opportunity to work in direct contact with many Open Source projects. We found bugs/suggested improvements on various topics such as Spring, Spring Data, Bean Validation and even Eclipse! In many cases, they've been fixed/implemented in just a few days.
157-
Here is a list of them:
191+
### 6. Add Ona automations
158192

159-
| Name | Issue |
160-
|------|-------|
161-
| Spring JDBC: simplify usage of NamedParameterJdbcTemplate | [SPR-10256](https://github.com/spring-projects/spring-framework/issues/14889) and [SPR-10257](https://github.com/spring-projects/spring-framework/issues/14890) |
162-
| Bean Validation / Hibernate Validator: simplify Maven dependencies and backward compatibility |[HV-790](https://hibernate.atlassian.net/browse/HV-790) and [HV-792](https://hibernate.atlassian.net/browse/HV-792) |
163-
| Spring Data: provide more flexibility when working with JPQL queries | [DATAJPA-292](https://github.com/spring-projects/spring-data-jpa/issues/704) |
193+
Copy the two automation files into your repo:
164194

165-
## Contributing
195+
```
196+
.ona/fix-dependabot-alert.yaml
197+
.ona/fix-codescan-alert.yaml
198+
```
166199

167-
The [issue tracker](https://github.com/spring-projects/spring-petclinic/issues) is the preferred channel for bug reports, feature requests and submitting pull requests.
200+
Adjust the agent prompts if your project uses a different build tool (e.g., replace `./mvnw` with `./gradlew` or `npm`).
168201

169-
For pull requests, editor preferences are available in the [editor config](.editorconfig) for easy use in common text editors. Read more and download plugins at <https://editorconfig.org>. All commits must include a __Signed-off-by__ trailer at the end of each commit message to indicate that the contributor agrees to the Developer Certificate of Origin.
170-
For additional details, please refer to the blog post [Hello DCO, Goodbye CLA: Simplifying Contributions to Spring](https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring).
202+
Trigger them manually from the Ona dashboard. Each run picks the highest-severity open alert, fixes it, and opens a PR.
171203

172204
## License
173205

0 commit comments

Comments
 (0)