Skip to content

Commit 8d98c7c

Browse files
Zimbo88Zimbo88
Zimbo88
authored and
Zimbo88
committed
Initial public release v1.0.0
1 parent 2730b02 commit 8d98c7c

133 files changed

Lines changed: 9863 additions & 580 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Bug report
2+
description: Report a reproducible defect
3+
title: "[Bug] "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Remove private paths, credentials, signing material, and device identifiers.
10+
- type: input
11+
id: component
12+
attributes:
13+
label: Component
14+
placeholder: Bootloader, HIL runner, image tooling, documentation
15+
validations:
16+
required: true
17+
- type: textarea
18+
id: description
19+
attributes:
20+
label: Description
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: reproduce
25+
attributes:
26+
label: Reproduction steps
27+
validations:
28+
required: true
29+
- type: textarea
30+
id: expected
31+
attributes:
32+
label: Expected behavior
33+
validations:
34+
required: true
35+
- type: textarea
36+
id: observed
37+
attributes:
38+
label: Observed behavior
39+
validations:
40+
required: true
41+
- type: textarea
42+
id: environment
43+
attributes:
44+
label: Hardware and toolchain
45+
description: MCU, board revision, probe, compiler, OpenOCD or stlink version

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security report
4+
url: ../../security/policy
5+
about: Follow the repository security policy before publishing details.

‎.github/ISSUE_TEMPLATE/research_observation.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Research observation
2+
description: Document a reproducible hardware or security observation
3+
title: "[Observation] "
4+
labels: ["research"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Use only owned or explicitly authorized hardware. Do not publish secrets,
10+
private device data, or uncoordinated vulnerability details.
11+
- type: textarea
12+
id: hypothesis
13+
attributes:
14+
label: Hypothesis or question
15+
validations:
16+
required: true
17+
- type: textarea
18+
id: setup
19+
attributes:
20+
label: Experimental setup
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: procedure
25+
attributes:
26+
label: Procedure
27+
validations:
28+
required: true
29+
- type: textarea
30+
id: evidence
31+
attributes:
32+
label: Evidence
33+
validations:
34+
required: true
35+
- type: textarea
36+
id: interpretation
37+
attributes:
38+
label: Interpretation and uncertainty
39+
validations:
40+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
## Summary
2+
3+
Describe the technical purpose of this change.
4+
5+
## Security impact
6+
7+
- [ ] No security-relevant behavior changes
8+
- [ ] Image verification
9+
- [ ] Key handling
10+
- [ ] Metadata or slot selection
11+
- [ ] Rollback policy
12+
- [ ] Update or recovery
13+
- [ ] Flash protection or option bytes
14+
- [ ] HIL or flashing behavior
15+
16+
Explain the impact and residual risk:
17+
18+
## Validation
19+
20+
- [ ] Host tests passed
21+
- [ ] Static checks passed
22+
- [ ] Firmware builds passed
23+
- [ ] HIL tests passed or are not required
24+
- [ ] Documentation updated
25+
- [ ] Diff reviewed for private information
26+
- [ ] Generated artifacts excluded
27+
28+
Commands and results:
29+
30+
## Hardware
31+
32+
Target board, MCU revision, probe, and serial setup used for validation:
33+
34+
## Checklist
35+
36+
- [ ] The change fails safely
37+
- [ ] Negative tests are included where relevant
38+
- [ ] No private signing material is included
39+
- [ ] Public text is written in English

‎.github/dependabot.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "pip"
4+
directory: "/tools/secure_boot_hil"
5+
schedule:
6+
interval: "monthly"
7+
open-pull-requests-limit: 5
8+
- package-ecosystem: "github-actions"
9+
directory: "/"
10+
schedule:
11+
interval: "monthly"
12+
open-pull-requests-limit: 5

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,30 +34,25 @@ jobs:
3434
run: |
3535
python -m pip install --upgrade pip
3636
python -m pip install -r requirements.txt
37+
python -m pip install -e tools/secure_boot_hil[dev]
38+
39+
- name: Run Ruff
40+
run: ruff check .
3741

3842
- name: Check generated memory layout
3943
run: python tools/emit_memory_layout.py --check
4044

4145
- name: Run Python and host tests
42-
run: PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider tests
43-
44-
- name: Run memory-integrity tooling tests
45-
run: PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider tests/test_memory_integrity_tool.py
46+
run: PYTHONDONTWRITEBYTECODE=1 python -m pytest -q -p no:cacheprovider tests
4647

47-
- name: Run pre-hardware EXP066 tests
48-
run: PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider tests/test_exp066_prehardware.py
49-
50-
- name: Run authenticated update package tool tests
51-
run: PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider tests/test_update_package_tool.py
48+
- name: Run secure-boot HIL host checks
49+
run: tools/secure_boot_hil/scripts/run_host_checks.sh
5250

5351
- name: Build factory metadata provisioning tool
5452
run: |
5553
make -C tools clean test
5654
make -C tools clean test SANITIZE=1
5755
58-
- name: Run Stage-0 slot-selection simulation tests
59-
run: PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider tests/test_update_storage.py
60-
6156
- name: Build firmware projects
6257
run: |
6358
make -C firmware/exp045_bootloader_v2 clean all report LAYOUT_PROFILE=stm32f429_1m

‎.gitignore‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,57 @@ __pycache__/
1919

2020
# Local reference material
2121
archive/
22+
23+
# Hardware-in-the-loop run outputs
24+
hil-results/
25+
tools/secure_boot_hil/.mypy_cache/
26+
tools/secure_boot_hil/.pytest_cache/
27+
tools/secure_boot_hil/.ruff_cache/
28+
tools/secure_boot_hil/*.egg-info/
29+
30+
# BEGIN publication-readiness local artifacts
31+
32+
# Local Python environments
33+
.venv/
34+
.venv-*/
35+
venv/
36+
37+
# Python and analysis caches
38+
.pytest_cache/
39+
.ruff_cache/
40+
.mypy_cache/
41+
.coverage
42+
coverage.xml
43+
htmlcov/
44+
45+
# Python packaging output
46+
*.egg-info/
47+
build/
48+
dist/
49+
50+
# Local hardware-test output
51+
hil-results/
52+
test-results/
53+
secure_boot_flash_tests.log
54+
55+
# Repository audit output containing local environment details
56+
audit/repository-audit.txt
57+
58+
# Editor and temporary files
59+
*.bak
60+
*.tmp
61+
*.swp
62+
*.swo
63+
*~
64+
.DS_Store
65+
66+
# Local environment configuration
67+
.env
68+
.env.*
69+
!.env.example
70+
71+
# END publication-readiness local artifacts
72+
73+
# Local publication installer backups
74+
.publication-backup-*/
75+
.publication-suite-backup-*/

‎CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Changelog
2+
3+
All notable project changes are documented in this file.
4+
5+
The format follows Keep a Changelog, and public releases use semantic
6+
versioning.
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Automated hardware-in-the-loop validation for the secure-boot chain.
13+
- Positive and negative manifest, hash, signature, and authentication tests.
14+
- Flash backup and post-test restoration verification.
15+
- Publication-readiness documentation and repository policy files.
16+
- BSD 3-Clause License.
17+
18+
### Changed
19+
20+
- Payload mutation tests preserve the application vector-table prefix.
21+
- ST-Link failures include command output, return codes, and retry diagnostics.
22+
- Public documentation is being consolidated into consistent technical English.
23+
24+
### Fixed
25+
26+
- Modified-payload HIL images no longer corrupt the initial stack pointer.
27+
- Hardware restoration failures expose the underlying `st-flash` diagnostics.
28+
29+
## [1.0.0] - Unreleased
30+
31+
Initial public research release.

‎CITATION.cff‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
cff-version: 1.2.0
2+
message: "If you use this project in research, please cite the repository release."
3+
title: "STM32 Security Lab"
4+
type: software
5+
authors:
6+
- name: "STM32 Security Lab contributors"
7+
license: "BSD-3-Clause"
8+
version: "1.0.0"
9+
abstract: >-
10+
A reproducible STM32F429 secure-boot and embedded-security research platform
11+
with authenticated firmware, rollback-aware slot selection, controlled
12+
recovery, and automated hardware-in-the-loop validation.
13+
keywords:
14+
- STM32
15+
- STM32F429
16+
- secure boot
17+
- embedded security
18+
- hardware-in-the-loop
19+
- Ed25519
20+
- SHA-512

‎CONTRIBUTING.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Contributing
2+
3+
Contributions that improve reproducibility, documentation, test coverage,
4+
hardware support, or defensive security analysis are welcome.
5+
6+
## Principles
7+
8+
Changes should:
9+
10+
- preserve safe-failure behavior;
11+
- avoid weakening verification, recovery, or rollback checks;
12+
- remain reproducible on documented hardware;
13+
- include tests for security-relevant behavior;
14+
- use English for source comments, documentation, reports, and user-facing output;
15+
- avoid personal paths, hostnames, credentials, and private device data;
16+
- explain the technical reason for the change.
17+
18+
## Development workflow
19+
20+
1. Create a focused branch.
21+
2. Keep each change limited to one technical purpose.
22+
3. Run the relevant host tests and static checks.
23+
4. Run hardware-in-the-loop tests when firmware or flashing behavior changes.
24+
5. Update documentation when observable behavior changes.
25+
6. Review the diff for private information and generated artifacts.
26+
27+
## Commit messages
28+
29+
Use concise imperative commit subjects, for example:
30+
31+
- `Add manifest boundary validation`
32+
- `Document HIL restore guarantees`
33+
- `Reject invalid application vector tables`
34+
35+
Avoid vague subjects such as `fix`, `update`, or `changes`.
36+
37+
## Security-sensitive changes
38+
39+
Changes to image verification, key handling, metadata selection, rollback
40+
policy, flash protection, recovery, or update installation require:
41+
42+
- a description of the threat being addressed;
43+
- negative tests;
44+
- safe-failure verification;
45+
- documentation of residual risk.
46+
47+
## Generated files
48+
49+
Do not commit compiler output, virtual environments, caches, temporary logs,
50+
private signing material, or complete local HIL run directories.
51+
52+
Curated validation evidence may be added under a dedicated report directory
53+
when it is anonymized, reproducible, and required to support a documented
54+
result.
55+
56+
## Licensing
57+
58+
By submitting a contribution, you agree that it may be distributed under the
59+
BSD 3-Clause License used by this repository.

0 commit comments

Comments
 (0)