# Security gates and remediation evidence for a local application

> Project scaffold: replace TODO fields with your implementation and measured results before publishing. This template does not contain a completed application.

## Objective
Build a pipeline that identifies a reproducible security finding, blocks release according to a written policy and proves a remediation with a regression test. Work only on your own isolated NodeGoat lab.

## Architecture
```mermaid
flowchart TD
  N0["Local application fork"]
  N1["Unit and security regression tests"]
  N2["Filesystem and image scans"]
  N3["Finding triage and policy gate"]
  N4["Remediation branch"]
  N5["Rescan and evidence artifacts"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5
```

Application tests and scanners provide different evidence. The release gate consumes scan results and explicit exception records; it must fail when scanning fails instead of interpreting missing results as a clean scan.

## Tools and prerequisites
Node.js basics, containers, CI pipelines and common application security risks.
- OWASP NodeGoat as an intentionally vulnerable training target
- Docker Compose for an isolated local application and database
- Trivy for supported dependency, image, secret and configuration scans
- GitHub Actions for a repeatable pipeline
- Node.js tests and JSON reports for regression evidence

## Repository structure (proposed)
```text
README.md
src/                 # Your implementation
tests/               # Unit, integration and failure-case tests
fixtures/            # Small synthetic or permitted inputs
config/              # Non-secret configuration examples
docs/architecture.md # Decisions and tradeoffs
docs/runbook.md      # Recovery, rerun and cleanup procedures
reports/             # Sanitized evidence and measured results
.env.example         # Variable names and safe placeholders only
```

## Setup and execution
- TODO: Record supported OS, runtime versions, pinned dependencies and hardware requirements.
- TODO: Add exact commands to install, configure, start and run a sample input after implementing them.
- TODO: Document environment variables in .env.example; keep secrets and local .env files out of Git.
- TODO: Include expected sample output and any optional hosted-service costs.

## Implementation checklist
- [ ] Create a lab fork and record the upstream commit and license notices. Bind the vulnerable application to localhost, use synthetic data and avoid public deployment or real credentials.
- [ ] Read the application's security tutorial and draw trust boundaries between browser, application and database. Choose one finding you can reproduce and remediate within this lab.
- [ ] Run the application tests and baseline filesystem and container scans. Save scanner version, vulnerability database timestamp and the scanned commit or image digest with the results.
- [ ] Define a release policy for new actionable high/critical findings and scan failures. Give every accepted exception a reason, owner and expiry; do not hide the baseline with a blanket ignore.
- [ ] Add CI jobs that produce reports even when the gate fails. Use minimal job permissions and keep lab execution isolated from production credentials and networks.
- [ ] Fix the selected issue and write a regression test that fails on the baseline and passes after the change. Use the scanner for issues it supports; an application logic flaw may require a dedicated test.
- [ ] Rebuild and rescan the exact candidate image. Compare findings by identity, not just total count, and show whether other vulnerabilities remain.
- [ ] Publish sanitized before/after evidence, a concise threat model and the exception process. Clearly state the scan coverage and avoid claiming the application is completely secure.

## Tests and acceptance evidence
- [ ] A threat model with a scoped lab finding
- [ ] A policy gate failing on a baseline or controlled test fixture
- [ ] A regression test failing before and passing after remediation
- [ ] Versioned scan reports and a documented exception example
- TODO: Add the exact test command and a link to a passing run.
- TODO: Explain at least one failure case and how it is detected or recovered.

## Results
Do not replace missing measurements with estimates presented as observations.

| Metric | Baseline | Result | Dataset / hardware / run link |
| --- | --- | --- | --- |
| TODO: choose a project metric | Not measured | Not measured | TODO |

## Limitations and next steps
- TODO: State what this lab does not establish about production reliability, security or model quality.
- TODO: Document cleanup, retained data and optional infrastructure charges.
- TODO: Link an issue for the next improvement and explain its priority.

## Interview preparation
- How do you distinguish scanner severity from exploitability in your application?
- What should the pipeline do if a scanner cannot download its database?
- Why does a clean dependency scan not prove authorization logic is correct?
- How do you prevent temporary security exceptions from becoming permanent?

## Resume draft (use only after completing the work)
Replace bracketed values with real evidence and remove claims you did not implement.
- Implemented a security-gated CI lab for an intentionally vulnerable application, combining dependency/image scans, explicit exception expiry and fail-closed scan handling.
- Remediated [specific lab finding] and added a regression test, publishing versioned before/after evidence and documenting remaining coverage gaps.

## References, attribution and your contribution
- [OWASP NodeGoat](https://github.com/OWASP/NodeGoat): A deliberately vulnerable Node.js learning application with security tutorials and local/container setup guidance.
- [Trivy](https://github.com/aquasecurity/trivy): Scanner reference covering supported vulnerability, secret and misconfiguration detection and SBOM generation. Consult its documentation for target-specific coverage.

The application and scanner belong to their maintainers. Your portfolio contribution is the threat model, policy implementation, selected fix and reproducible before/after evidence.

- TODO: Record the exact upstream commit/tag you consulted and any files reused or modified.
- TODO: Preserve required copyright/license notices and check each repository's reuse terms before copying code. Choose a license only for work you have rights to license.
- TODO: Explain your own implementation and link its commits; do not claim authorship of upstream code.

Project brief: [BonusMantra](https://bonusmantra.com/career-roadmaps/devsecops-engineer/projects/); reference pages checked 2026-09-06.