jramos/cve-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Auto-sync .kiro/ from master (post-checkout hook)

Browse Source
This commit is contained in:
Jordan Ramos
2026-05-19 15:01:25 -06:00
parent ada9df26a8
commit 8ebd7e4d5e
23 changed files with 3485 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
.kiro/steering/firewall-request-template.md Normal file
View File

@@ -0,0 +1,111 @@
---
inclusion: manual
---
# Firewall Exception Request Template
When the user needs to generate a Red/Blue Firewall Exception Request (LNE > Lab Network Request ticket), use this template structure. Adapt the content based on the specific service requiring network access.
## Template Structure
Every firewall request document must include these sections in order:
### 1. Title and Purpose
```
# <Service Name> Firewall Exception Request — <Application Name>
Reference material for the LNE > Lab Network Request ticket required by
<reason for the block / policy reference>. All targets are <source of truth
for the destination list>.
```
### 2. Destinations Table
| Cluster/Service | Destination IP/Host | Port(s) | Protocol | Encryption |
|---|---|---|---|---|
| *Name of the service* | *IP or hostname* | *port(s)* | TCP/UDP | *TLS, PLAINTEXT, etc.* |
Include notes about connection type: stateful TCP, client-initiated outbound, ephemeral source port, etc.
### 3. Source
- Source host: `<hostname>`
- Source IP: `<IP address>`
- Source port: `ephemeral / 1024-65535`
### 4. Requested Firewall Rules
Provide both per-IP rules and summary rules (if LNE accepts them):
```
Rule N
Source: <source IP>/32 ephemeral
Destination: <dest IP>/32 tcp/<port>
Protocol: TCP
Action: allow
```
### 5. Suggested Ticket Text
Follow the LNE template fields exactly:
> **Summary:** Red/Blue FW Request: <Source App> → <Destination Service> (<brief description>)
>
> 1. **Reason:** What the application does and why it needs this access.
> 2. **Drivers:** Operational, compliance, or business justification. State explicitly: no PCI, no CPNI if applicable.
> 3. **Application purpose:** What the app does with the data it gets from the destination. Mention rate limits, compliance with API policies, etc.
> 4. **Source/destination IPs and ports:** Summary of flows (count, protocol, direction).
> 5. **Impact if denied:** What breaks, what the fallback is, and why the fallback is worse.
>
> **Environment Overview**
> 1. Data: What data flows over this connection. Explicitly state no PII/PCI/CPNI if true.
> 2. OS: Operating system on the source host.
> 3. OS compliance / risk acceptance: Fill in if applicable.
> 4. Architecture: Brief description of the application architecture.
>
> **External access:** State whether the source host is internet-exposed or internal-only.
>
> **Mitigation controls:** How access to the source host is controlled, how credentials are stored, what security measures are in place.
### 6. Evidence to Attach
Describe what test script to run and what log files to attach. The log should provide timestamped proof of the connection behavior (success or failure) from the source host.
### 7. Notes
Any additional context: auth methods, TLS settings, environment differences between UAT and production, etc.
---
## Key Principles
- Be specific about IPs, ports, and protocols. Avoid vague descriptions.
- Explicitly state what data does NOT flow (no PII, no PCI, no CPNI) to speed risk assessment.
- Reference test evidence that proves the current behavior without speculation.
- If a test script exists, reference it and describe its output format.
- Use `/32` for single-host rules. Only use CIDR aggregates if you explain what extra IPs are included.
- State whether TLS is used. If PLAINTEXT, explain why (e.g., internal Kafka brokers with no client auth).
- Mention rate limiting and compliance with any API usage policies if applicable.
---
## Existing Firewall Request Documents
Reference these for examples of completed requests:
- `docs/kafka-firewall-request.md` — ZBL Impairment Map → Charter Kafka telemetry feeds (STAMP + DAA RPHY Prod). TCP PLAINTEXT to specific broker IPs on non-standard ports.
- The Jira request (generated in chat) — STEAM Dashboard → jira.charter.com:443. Single HTTPS flow with Basic Auth service account.
---
## Checklist Before Submitting
- [ ] All destination IPs/hostnames and ports are listed
- [ ] Source host IP is filled in (not placeholder)
- [ ] Protocol and encryption are specified for each flow
- [ ] Ticket text follows the LNE template fields
- [ ] Data classification is stated (PII/PCI/CPNI or lack thereof)
- [ ] Test evidence is attached or referenced
- [ ] Impact-if-denied section explains the operational consequence
- [ ] Mitigation controls describe how the source host is secured

40
.kiro/steering/gitlab-workflow.md Normal file
View File

@@ -0,0 +1,40 @@
# GitLab Issue Traceability
## Commit Messages
When a commit fixes or resolves a GitLab issue:
- Include `Closes #N` (or `Fixes #N`) on its own line at the end of the commit message body, where N is the GitLab issue number.
- If the fix addresses multiple issues, include one `Closes #N` per issue, each on its own line.
- The CI pipeline's `after_script` will auto-comment on the referenced issues with a link to the deploy pipeline.
Example:
```
Fix duplicate chart entries on compliance page
Aggregate /trends and /category-trend by report_date instead of per-upload row.
Closes #12
```
## Issue References in Code
When working from a GitLab issue, reference the issue number in:
- The commit message (required — `Closes #N`)
- The spec's `bugfix.md` introduction (for traceability from spec to issue)
- Test file header comments (optional — helps future developers find context)
## Closing Issues
- Prefer closing issues via commit message keywords (`Closes`, `Fixes`, `Resolves`) so GitLab auto-closes them when the pipeline succeeds on the default branch.
- If a commit was pushed without the keyword, close the issue via the API after confirming the deploy succeeded.
## Pipeline Notifications
The `deploy-staging` and `deploy-production` jobs in `.gitlab-ci.yml` have `after_script` blocks that parse `#N` references from the commit message and post a comment on each referenced issue with a link to the pipeline. This requires `GITLAB_PAT` to be set as a CI/CD variable in the project settings.
### Setup Required
1. Go to **Settings → CI/CD → Variables** in the GitLab project
2. Add variable: `GITLAB_PAT` = the project access token (already exists as `glpat-...` in `backend/.env`)
3. Mark it as **Protected** and **Masked**

48
.kiro/steering/tech.md
View File

@@ -5,31 +5,48 @@
| Layer | Technology |
|-------|-----------|
| Backend | Node.js 18+, Express 5 |
| Database | SQLite3 (file: `backend/cve_database.db`) |
| Database | PostgreSQL (via `pg` pool in `backend/db.js`) |
| Auth | bcryptjs, cookie-based sessions (httpOnly, 24h expiry) |
| File uploads | Multer 2 (10MB limit) |
| Frontend | React 19 (Create React App / react-scripts 5) |
| Frontend serving | Express serves `frontend/build/` as static files on port 3001 |
| UI Icons | lucide-react |
| Charts | recharts |
| Spreadsheet parsing | xlsx (frontend), pandas + openpyxl (backend Python scripts) |
| Markdown rendering | react-markdown |
| Diagrams | mermaid |
## Architecture: Single-Port Serving
Express on port 3001 serves **both** the API and the production frontend build:
- API routes: `/api/*` — handled by Express route handlers
- Frontend: everything else — served as static files from `frontend/build/`
There is no separate frontend server in production. The React dev server (`npm start` on port 3000) is only for local development with hot-reload. In production and on the dev server, you must run `npm run build` in `frontend/` after any frontend code change, then restart the backend.
**After editing frontend source files:**
```bash
cd frontend && npm run build # Compile new bundle into frontend/build/
# Then restart backend (or it will serve the new static files on next request)
```
The CI/CD pipeline handles this automatically — `build-frontend` stage runs before deploy.
## Common Commands
### Backend
```bash
cd backend
node setup.js # Initialize DB, tables, indexes, default admin user
node server.js # Start backend on port 3001
node server.js # Start backend on port 3001 (serves API + frontend build)
```
### Frontend
```bash
cd frontend
npm install # Install dependencies
npm start # Dev server on port 3000
npm run build # Production build
npm run build # Production build → frontend/build/ (REQUIRED after code changes)
npm start # Dev server on port 3000 (local dev only, NOT used in production)
npm test # Run tests (react-scripts test)
```
@@ -39,16 +56,9 @@ npm test # Run tests (react-scripts test)
./stop-servers.sh # Stop all servers
```
### Database Migrations (run from `backend/` in order)
### Database Migrations (run from `backend/`)
```bash
node migrations/add_knowledge_base_table.js
node migrations/add_archer_tickets_table.js
node migrations/add_ivanti_sync_table.js
node migrations/add_ivanti_findings_tables.js
node migrations/add_ivanti_todo_queue_table.js
node migrations/add_card_workflow_type.js
node migrations/add_todo_queue_ip_address.js
node migrations/add_compliance_tables.js
node migrations/run-all.js # Runs all migrations in order (idempotent)
```
### Python Scripts (from `backend/scripts/`)
@@ -68,11 +78,11 @@ Python dependencies: `pandas>=2.0.0`, `openpyxl>=3.0.0` (install via apt or venv
- `backend/.env` — PORT, CORS_ORIGINS, SESSION_SECRET, NVD_API_KEY, Ivanti API credentials
- `frontend/.env` — REACT_APP_API_BASE, REACT_APP_API_HOST
- Both `.env` files are gitignored; see `.env.example` files for templates.
- React caches env vars at build/start time — restart the frontend process after changes.
- React env vars are baked in at **build time** — you must rebuild (`npm run build`) after changing them.
## Default Ports
## Ports
| Service | URL |
|---------|-----|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:3001 |
| Environment | URL | Notes |
|---|---|---|
| Production / Dev server | http://IP:3001 | Express serves API + static frontend build |
| Local dev (frontend only) | http://localhost:3000 | React dev server with hot-reload, proxies API to :3001 |

83
.kiro/steering/versioning.md Normal file
View File

@@ -0,0 +1,83 @@
# Versioning & Release Management
## Version Numbering
This project uses **Semantic Versioning** (MAJOR.MINOR.PATCH) but with a practical cadence-based approach to avoid runaway patch numbers.
### When to bump what
| Change type | Bump | Example |
|---|---|---|
| Breaking change (new DB engine, incompatible API/config, data migration required) | MAJOR | 2.0.0 → 3.0.0 |
| New feature, new page, new integration, significant enhancement | MINOR | 2.1.0 → 2.2.0 |
| Bug fix, UI tweak, docs update, refactor with no user-visible change | PATCH | 2.1.0 → 2.1.1 |
### Cadence rules to keep numbers sane
- **Bundle bug fixes into the next minor release** rather than tagging a patch for every individual fix. Only cut a standalone patch release (x.y.Z) if a fix is urgent and needs to ship before the next feature is ready.
- **One minor bump per feature batch** — if a work session produces 2–3 features and 5 bug fixes, that's one minor release, not five patches and two minors.
- **Tag releases at logical milestones**, not per-commit. A good release boundary is: "a user would notice something new or different."
- **Never exceed x.y.5 in patches** before rolling into the next minor. If you're at x.y.5 and still shipping fixes, just bump to x.(y+1).0 and include the fixes there.
### Practical workflow
1. Work on features and fixes on `master` as normal — no version bump per commit.
2. When a logical batch is complete (end of a sprint, feature area done, before a deploy you want to mark), decide the version:
- Any breaking change since last tag? → MAJOR
- Any new features? → MINOR
- Only fixes? → PATCH (but prefer bundling into next MINOR)
3. Update `CHANGELOG.md` with the new version section.
4. Commit the changelog update.
5. Tag and push:
```bash
git tag -a vX.Y.Z -m "vX.Y.Z — short summary"
git push origin vX.Y.Z
git push backup vX.Y.Z
```
6. Create a GitLab Release from the tag (renders changelog on the Releases page):
```bash
# Extract the changelog section for this version from CHANGELOG.md
# Then create the release via GitLab API:
curl --silent --request POST \
--header "PRIVATE-TOKEN: $GITLAB_PAT" \
--header "Content-Type: application/json" \
--data "{
\"tag_name\": \"vX.Y.Z\",
\"name\": \"vX.Y.Z\",
\"description\": \"<changelog section in markdown>\"
}" \
"https://vulcan.apophisnetworking.net/api/v4/projects/jramos%2Fcve-dashboard/releases"
```
### GitLab Release creation details
- The GitLab instance is `https://vulcan.apophisnetworking.net`
- Project path: `jramos/cve-dashboard` (URL-encoded: `jramos%2Fcve-dashboard`)
- Auth: `GITLAB_PAT` from `backend/.env`
- The `description` field accepts full markdown — paste the relevant `## [vX.Y.Z]` section from `CHANGELOG.md`
- The release appears under **Deployments → Releases** in the GitLab sidebar with rendered markdown, download archives, and a badge showing the latest version
### What counts as a "breaking change"
- Database engine or schema change that requires migration with data transformation
- Removal or rename of API endpoints that external consumers depend on
- Environment variable changes that would break an existing deployment on pull
- Dropping support for a previously supported platform or runtime version
Adding new required env vars for *new* features is NOT breaking — existing features still work without them.
## Release Suggestion Prompt
After completing work (features, fixes, or both), suggest the next version number based on:
1. What the last tagged version is (`git tag -l --sort=-v:refname | head -1`)
2. What changed since that tag (`git log <last_tag>..HEAD --oneline`)
3. The cadence rules above
Format the suggestion as:
> **Suggested release:** vX.Y.Z
> **Reason:** [brief justification based on change types]
> **Changelog entries to add:** [bullet list of items to add]
Only suggest a release if there are meaningful user-visible changes. Internal refactors, test additions, and CI tweaks alone do not warrant a release.