Skip to content

Commit 6236ed3

Browse files
Arpan0995Arpan0995
committed
Add CI workflow, issue templates and a report example to the README
1 parent b3685bb commit 6236ed3

10 files changed

Lines changed: 232 additions & 5 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Bug report
2+
description: A crash, wrong output or build problem in the auditor, the Maven plugin, the GitHub Action or the agility provider
3+
title: "[bug] "
4+
labels: [bug]
5+
body:
6+
- type: dropdown
7+
id: component
8+
attributes:
9+
label: Component
10+
options:
11+
- Auditor CLI
12+
- Maven plugin
13+
- GitHub Action
14+
- Agility provider
15+
- Benchmarks
16+
- Documentation
17+
- Other
18+
validations:
19+
required: true
20+
- type: input
21+
id: version
22+
attributes:
23+
label: Version
24+
description: Release version or commit hash.
25+
placeholder: "1.4.0"
26+
validations:
27+
required: true
28+
- type: input
29+
id: environment
30+
attributes:
31+
label: JDK and OS
32+
placeholder: "Temurin 21.0.9, Ubuntu 24.04"
33+
- type: textarea
34+
id: command
35+
attributes:
36+
label: Command you ran
37+
render: shell
38+
- type: textarea
39+
id: what-happened
40+
attributes:
41+
label: What happened
42+
description: Paste the full error output if there was one.
43+
validations:
44+
required: true
45+
- type: textarea
46+
id: expected
47+
attributes:
48+
label: What you expected instead
49+
- type: textarea
50+
id: snippet
51+
attributes:
52+
label: Minimal Java snippet
53+
description: The smallest source file that reproduces the problem, if the bug is in detection or reporting.
54+
render: java

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Share scan results
4+
url: https://github.com/Arpan0995/pqc-migration-readiness/discussions/categories/show-and-tell
5+
about: Ran the auditor on a codebase? Post the report and say whether the ranking matches what you know about the code.
6+
- name: Ask a question
7+
url: https://github.com/Arpan0995/pqc-migration-readiness/discussions/categories/q-a
8+
about: Questions about the approach, the scoring model or how to read a report.
9+
- name: Report a security problem
10+
url: https://github.com/Arpan0995/pqc-migration-readiness/blob/main/CONTRIBUTING.md#ground-rules
11+
about: Security-sensitive findings go by email to the address in CITATION.cff, not into a public issue.

‎.github/ISSUE_TEMPLATE/detection_gap.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Detection gap
2+
description: A false positive or a false negative in what the auditor flags
3+
title: "[detection] "
4+
labels: [detection]
5+
body:
6+
- type: dropdown
7+
id: kind
8+
attributes:
9+
label: Kind of gap
10+
options:
11+
- "False negative: a quantum-vulnerable call or a fragility pattern was missed"
12+
- "False positive: a flagged site is not quantum-vulnerable or not fragile"
13+
- "Wrong rule, category or confidence on an otherwise correct finding"
14+
validations:
15+
required: true
16+
- type: input
17+
id: version
18+
attributes:
19+
label: Auditor version
20+
placeholder: "1.4.0"
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: snippet
25+
attributes:
26+
label: Java snippet
27+
description: The smallest source file that shows the gap. This is the most useful part of the report.
28+
render: java
29+
validations:
30+
required: true
31+
- type: textarea
32+
id: actual
33+
attributes:
34+
label: What the report shows
35+
description: The finding rows from readiness-report.md for this snippet, or "nothing" for a miss.
36+
- type: textarea
37+
id: expected
38+
attributes:
39+
label: What it should show, and why
40+
description: Name the rule from docs/research/02-detection-rule-catalog.md if you know it.
41+
validations:
42+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Feature request
2+
description: A new detection rule, report format, option or agility-layer capability
3+
title: "[feature] "
4+
labels: [enhancement]
5+
body:
6+
- type: dropdown
7+
id: area
8+
attributes:
9+
label: Area
10+
options:
11+
- Detection rules
12+
- Scoring or effort model
13+
- Reports and output formats
14+
- CLI, Maven plugin or GitHub Action
15+
- Agility provider
16+
- Documentation
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: problem
21+
attributes:
22+
label: What are you trying to do?
23+
description: The situation the feature would help with, ideally with an example codebase or snippet.
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: proposal
28+
attributes:
29+
label: Proposed change
30+
- type: checkboxes
31+
id: checks
32+
attributes:
33+
label: Before filing
34+
options:
35+
- label: I looked through the open issues and the "Where help is most useful" list in CONTRIBUTING.md.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## What this changes
2+
3+
## Why
4+
5+
## Checklist
6+
7+
- [ ] `mvn verify -Dgpg.skip=true` passes on JDK 21
8+
- [ ] Tests added or updated. A new detection rule needs one fixture where it fires and one where it stays quiet.
9+
- [ ] `docs/research/02-detection-rule-catalog.md` or `03-difficulty-scoring-model.md` updated if a rule or a weight changed

‎.github/workflows/ci.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
13+
concurrency:
14+
group: ci-${{ github.ref }}
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
name: Build and test (JDK 21)
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Check out
23+
uses: actions/checkout@v7
24+
25+
- name: Set up JDK 21
26+
uses: actions/setup-java@v6
27+
with:
28+
distribution: temurin
29+
java-version: '21'
30+
cache: maven
31+
32+
- name: Build and test
33+
run: mvn -B -ntp verify -Dgpg.skip=true
34+
35+
- name: Upload test reports
36+
if: failure()
37+
uses: actions/upload-artifact@v7
38+
with:
39+
name: surefire-reports
40+
path: '**/target/surefire-reports/*.xml'
41+
if-no-files-found: ignore

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,12 @@ The usual flow:
5050
2. Build and run the tests with JDK 21 and Maven 3.9+:
5151

5252
```
53-
mvn clean install
53+
mvn clean install -Dgpg.skip=true
5454
```
5555

56+
The flag skips the GPG signing step that release builds run in `verify`;
57+
without it the build fails unless you have a signing key configured.
58+
5659
To build the CLI jar on its own:
5760

5861
```

‎README.md‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,32 @@
11
# PQC Migration Readiness Framework
22

3+
[![CI](https://github.com/Arpan0995/pqc-migration-readiness/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Arpan0995/pqc-migration-readiness/actions/workflows/ci.yml)
34
[![auditor on Maven Central](https://img.shields.io/maven-central/v/io.github.arpan0995/pqc-readiness-auditor.svg?label=auditor%20on%20Maven%20Central)](https://central.sonatype.com/artifact/io.github.arpan0995/pqc-readiness-auditor)
45
[![agility-provider on Maven Central](https://img.shields.io/maven-central/v/io.github.arpan0995/pqc-readiness-agility.svg?label=agility-provider%20on%20Maven%20Central)](https://central.sonatype.com/artifact/io.github.arpan0995/pqc-readiness-agility)
56
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
67
[![JDK 21](https://img.shields.io/badge/JDK-21-orange.svg)](https://openjdk.org/projects/jdk/21/)
78
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21638938.svg)](https://doi.org/10.5281/zenodo.21638938)
89

9-
A research framework for answering a question current post-quantum-cryptography
10-
guidance leaves open: **not *what* to migrate to, but *how much* a migration
11-
will cost for a specific Java codebase, and where the expensive parts hide.**
10+
Point the auditor at a Java source tree and it returns the code that has to
11+
change when RSA, ECDSA and (EC)DH are retired, ranked by how expensive each site
12+
is to migrate, together with an ordered migration plan and an engineer-time
13+
estimate for the work. It needs no build and no classpath: the scan is
14+
syntactic, runs on the source alone, and takes a few seconds for a mid-sized
15+
project.
16+
17+
![First screen of the Markdown readiness report for Eclipse Californium 3.14.0: the migration plan with six ordered steps, sites per step, modules touched and an effort range per step](docs/assets/readiness-report-example.png)
18+
19+
*The first screen of `readiness-report.md` for Eclipse Californium 3.14.0, one of
20+
the four [case studies](case-studies/). The full report continues with the
21+
module ranking and the ranked hotspots, each with a file:line and the reason it
22+
is expensive.*
23+
24+
The tool is the instrument of a research project on a question current
25+
post-quantum-cryptography guidance leaves open: how much a migration will cost
26+
for a specific Java codebase, and where the expensive parts hide. Every score
27+
and time figure it produces today is a Phase 1 estimate from a pre-registered
28+
model, not a validated prediction; [Research question](#research-question) and
29+
[Status](#status) below say what has and has not been validated.
1230

1331
## Install / Run
1432

@@ -61,6 +79,15 @@ alerts. Scan the repository root so alert paths resolve:
6179
sarif_file: audit-out/readiness-report.sarif
6280
```
6381
82+
The same steps are packaged as a GitHub Action,
83+
[`Arpan0995/pqc-readiness-action`](https://github.com/Arpan0995/pqc-readiness-action),
84+
which downloads the auditor, scans the checkout, writes a summary to the job page
85+
and uploads the SARIF report:
86+
87+
```yaml
88+
- uses: Arpan0995/pqc-readiness-action@v1
89+
```
90+
6491
**Use the libraries in a Maven build:**
6592

6693
```xml
@@ -164,6 +191,7 @@ output.
164191
| `auditor` | Scanner + difficulty scoring |
165192
| `agility-provider` | Runtime crypto-agility layer (BC-backed, JDK 21) |
166193
| `benchmarks` | JMH harness for agility-layer overhead |
194+
| `maven-plugin` | `pqc-readiness-maven-plugin`: runs the auditor from a Maven build |
167195
| `case-studies` | Pinned target codebases + migration effort logs |
168196

169197
## Research documentation
@@ -189,9 +217,13 @@ Design decisions and methodology live in [`docs/research/`](docs/research/):
189217
## Build
190218

191219
```
192-
mvn clean install
220+
mvn clean install -Dgpg.skip=true
193221
```
194222
223+
Release builds sign every artifact with GPG during the `verify` phase, so a
224+
local build fails at that step unless a signing key is configured. The flag
225+
skips signing; nothing else changes.
226+
195227
## Run the auditor (from source)
196228
197229
The published `-all` jar (see [Install / Run](#install--run)) is the easiest way

‎docs/assets/readiness-report-example.png‎

140 KB
Loading

‎docs/assets/social-preview.png‎

293 KB
Loading

0 commit comments

Comments
 (0)