From 83e7e4fe901b864bd7aecddb4ec4640a4cba026f Mon Sep 17 00:00:00 2001 From: Luan Trindade Date: Sun, 20 Sep 2026 00:13:11 -0300 Subject: [PATCH] docs: close C1 dependency advisory remediation in the brain Record ADR-26 for the pacote/tar overrides, reflect the audit-gate policy as BRAIN-006, update the canonical state with the green CI on main, add the dependency advisory follow-up as Priority 12, and leave the handoff. Co-Authored-By: Claude Opus 5 --- brain/canonico/CURRENT_STATE.md | 15 +++++++-- brain/canonico/DECISIONS.md | 10 ++++++ brain/canonico/NEXT_ACTIONS.md | 27 ++++++++++++++-- .../2026-09-20-ci-dependency-advisories.md | 32 +++++++++++++++++++ docs/DECISIONS.md | 11 +++++++ 5 files changed, 90 insertions(+), 5 deletions(-) create mode 100644 brain/handoffs/2026-09-20-ci-dependency-advisories.md diff --git a/brain/canonico/CURRENT_STATE.md b/brain/canonico/CURRENT_STATE.md index 107cc5a..2999dd8 100644 --- a/brain/canonico/CURRENT_STATE.md +++ b/brain/canonico/CURRENT_STATE.md @@ -1,6 +1,6 @@ # Current State -Updated: 2026-06-13 +Updated: 2026-09-20 ## Product Status @@ -110,9 +110,20 @@ Current Brain bootstrap did not rerun the full product gate set because this cha ## Current Branch Context +`main` is the current integration point and its CI is green: run `35485832903` on commit `8623fea` finished with `success` in both jobs, Backend and Frontend. Before that, `main` had been red since the merge of PR #1, failing only on dependency audit steps. + This Brain was bootstrapped on branch `docs/commandsphere-brain-documentation`, created from `feature/commandsphere-portfolio-v1-polish`. -Active remediation branch: `fix/runtime-production-config`. +Remediation branch merged into `main` through PR #5: `fix/ci-dependency-advisories`. + +Dependency advisory phase: + +- Backend locks updated inside the current majors: guzzle `7.11.0 -> 7.15.5`, psr7 `2.11.0 -> 2.13.1`, commonmark `2.8.2 -> 2.10.1`, phpseclib `3.0.52 -> 3.0.57`. `composer audit` reports no advisories; `backend/composer.json` was not touched. +- The frontend `critical` (`tar`, path traversal) is closed through the `pacote` and `tar` overrides recorded in ADR-26. `npm audit --audit-level=critical` exits 0. +- Remaining `high` and `moderate` advisories belong to the Angular runtime and toolchain and have no non-major fix; `19.2.25` is the last published release of the Angular 19 runtime line. They are recorded as risk under ADR-24, not as corrected. +- Backend Pest on the GitHub runner reports `32 warnings, 1 passed` while the same suite in the dev container reports `33 passed (191 assertions)`. The warnings come from `file_get_contents` on runner paths. The suite is byte-identical to the previous `main`, so this is a runner environment condition, not a skipped test — but it makes the Backend green on CI weaker than the local green. + +Earlier remediation branch: `fix/runtime-production-config`. Latest build-loop phase completed in this branch: diff --git a/brain/canonico/DECISIONS.md b/brain/canonico/DECISIONS.md index 9d490d8..e3a36ee 100644 --- a/brain/canonico/DECISIONS.md +++ b/brain/canonico/DECISIONS.md @@ -51,3 +51,13 @@ Consequences: - Public SSR pages may read catalog/search/plugin/command data. - Mutations, favorites, analytics actions, ingestion controls, and operational data require authenticated permission checks. - Invalid authenticated-looking requests must not silently fall back to anonymous scope. + +## BRAIN-006 - Dependency Advisories Are Closed Within The Current Major + +Decision: Security advisories are closed by updating locks inside the current majors, and by npm `overrides` when a transitive dependency is the only blocker. Audit gates are never weakened to make CI pass: no `--audit-level` downgrade, no `continue-on-error`, no `audit.ignore`, no `npm audit fix --force`. + +Consequences: + +- `critical` blocks the pipeline; `high` and `moderate` without a non-major fix are recorded as risk under ADR-24 and never reported as corrected. +- An override that leaves the range declared by its dependent needs a recorded ADR stating the verified facts that justify it, as in ADR-26. +- Toolchain major upgrades stay a deliberate, separately planned task. diff --git a/brain/canonico/NEXT_ACTIONS.md b/brain/canonico/NEXT_ACTIONS.md index 0b873a4..7e5ce4f 100644 --- a/brain/canonico/NEXT_ACTIONS.md +++ b/brain/canonico/NEXT_ACTIONS.md @@ -1,6 +1,6 @@ # Next Actions -Updated: 2026-06-13 +Updated: 2026-09-20 This roadmap is intentionally product-oriented. New work should strengthen portfolio signal, production realism, and architecture maturity rather than adding generic CRUD. @@ -86,7 +86,7 @@ Recommended direction: Acceptance criteria: -- CI proves backend tests, frontend tests, SSR build, dependency audits, and service-backed search behavior. `CONFIGURED`; pending remote Actions execution. +- CI proves backend tests, frontend tests, SSR build, dependency audits, and service-backed search behavior. `VALIDATED` by run `35485832903` on `main` (`8623fea`), both jobs `success`. - CI logs clearly distinguish skipped, pending, and executed integration checks. Risks: @@ -246,13 +246,34 @@ Risks: - Avoid pretending a provider-specific deployment exists unless it has been validated. +## Priority 12 - Dependency Advisory Follow-Up + +Problem: CI is green, but part of the dependency risk is deliberately carried instead of fixed. Two overrides exist as a maintenance point, and the Backend green on CI is weaker than the local green. + +Recommended direction: + +- Re-evaluate the `pacote` and `tar` overrides in `frontend/package.json` at every Angular toolchain upgrade and drop them once the official chain resolves `tar` 7.x (ADR-26). +- Close `@sigstore/sign` and `@sigstore/verify`, the only remaining advisories reporting `fixAvailable: true`. +- Plan the Angular major upgrade that closes the remaining runtime/toolchain advisories (`@angular/*@22.x`, `@angular-devkit/build-angular@21.2.24`+), as a task of its own. +- Investigate the Pest warnings on the GitHub runner: `32 warnings, 1 passed` there versus `33 passed (191 assertions)` in the dev container, caused by `file_get_contents` on runner paths. +- Update the deprecated `actions/checkout@v4` and `actions/setup-node@v4`, and plan the `ubuntu-latest` migration to Ubuntu 26 starting October 19, 2026. + +Acceptance criteria: + +- Overrides are either still justified by recorded facts or removed. +- Backend Pest reports the same passing count on CI and locally, with no warnings masking the result. +- Audit gates stay at `--audit-level=critical` with no weakening. + +Risks: + +- An Angular major upgrade touches SSR, build and tests at once; it needs its own branch, gates and audit. + ## Backlog - Add Content Security Policy on Laravel and SSR Node responses. - Sanitize Markdown HTML server-side before storage or response. - Harden GitHub client HTTP error taxonomy beyond 403/404. - Extract optional bearer-token user resolution shared by public discovery controllers. -- Track Angular toolchain advisories from `npm audit`. - Keyboard-first power-user UX for command palette actions. - Saved searches and team-level curated collections. - Export command/document references. diff --git a/brain/handoffs/2026-09-20-ci-dependency-advisories.md b/brain/handoffs/2026-09-20-ci-dependency-advisories.md new file mode 100644 index 0000000..00d8e12 --- /dev/null +++ b/brain/handoffs/2026-09-20-ci-dependency-advisories.md @@ -0,0 +1,32 @@ +# Handoff - CI Dependency Advisories + +Date: 2026-09-20 +Branch: `fix/ci-dependency-advisories`, merged into `main` through PR #5 (merge commit `8623fea`) + +## Scope + +Audited remediation item C1: bring the `main` CI back to green. Both jobs had been failing on dependency audit steps since the merge of PR #1, with no failing test. + +## Implemented + +- `backend/composer.lock` updated inside the current majors: `guzzlehttp/guzzle 7.11.0 -> 7.15.5`, `guzzlehttp/psr7 2.11.0 -> 2.13.1`, `league/commonmark 2.8.2 -> 2.10.1`, `phpseclib/phpseclib 3.0.52 -> 3.0.57`. `backend/composer.json` untouched, 22 advisories closed. +- `frontend/package.json` gained the overrides `"pacote": "20.0.1"` and `"tar": "^7.5.21"`, closing the only `critical` (`tar`, path traversal). Rationale and verified facts are recorded in ADR-26. +- No CI gate was weakened: `.github/workflows/` has no diff, `--audit-level` stays `critical`, no `continue-on-error`, no `audit.ignore`, no test skipped. + +## Validation + +- Clean install in a CI-parity container (PHP 8.3, Node 22): `composer install` + `composer audit` exit 0, "No security vulnerability advisories found."; `npm ci` + `npm audit --audit-level=critical` exit 0. +- Pint `115 files`, Pest `33 passed (191 assertions)`, `tsc --noEmit`, lint, Jest `15/15`, SSR build with `server/` and `prerendered-routes.json`. +- `IngestionPipelineTest` passes in all 5 cases, confirming the CommonMark bump does not change `App\Services\Markdown\MarkdownParser` or ingestion behaviour. +- CI on the branch: run `35474423377`, both jobs `success` on `3c1095b`. CI on `main` after the merge: run `35485832903`, both jobs `success` on `8623fea`. +- Independent adversarial audit: APPROVED on all 9 checklist items, including an own-hands clean install, the override facts through `npm ls`, and the run SHA against the remote HEAD. + +## Remaining Work + +Tracked as Priority 12 in `brain/canonico/NEXT_ACTIONS.md`: + +- Re-evaluate and eventually drop the `pacote` and `tar` overrides at the next Angular toolchain upgrade. +- Close `@sigstore/sign` and `@sigstore/verify`, the only remaining advisories with `fixAvailable: true`. +- Plan the Angular major upgrade that closes the remaining runtime and toolchain advisories. +- Investigate the Pest warnings on the GitHub runner (`32 warnings, 1 passed` there versus `33 passed` in the dev container). +- Update `actions/checkout@v4` and `actions/setup-node@v4`, and plan the `ubuntu-latest` migration to Ubuntu 26. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 0ff2a4f..ca36056 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -290,3 +290,14 @@ Adicionar Dockerfiles multi-stage para backend PHP-FPM e frontend Node SSR, alé ### Consequências A stack pode ser validada localmente com `docker compose -f docker-compose.prod.yml up -d --build`, preservando separação entre runtime PHP-FPM, SSR Node e serviços de dados. O trade-off é manter dois caminhos Docker: dev com DX/testes e prod com empacotamento mais fiel ao deploy. + +## ADR-26 — Override de `pacote` para fechar vulnerabilidade crítica sem upgrade de major + +### Contexto +O CI da `main` ficou vermelho desde o merge do PR #1 por auditoria de dependências. No frontend, a única vulnerabilidade `critical` era `tar <=7.5.20` (path traversal por hardlink/symlink), alcançada de forma transitiva. `@angular/cli@19.2.27` fixa `pacote` em `20.0.0` exato, e `pacote@20.0.0` depende de `tar ^6.1.11` — uma linha que nunca recebeu patch de segurança. Sem tocar nessa cadeia, a critical só fecharia com upgrade de major da toolchain Angular, fora do escopo da correção. + +### Decisão +Declarar em `frontend/package.json` os overrides `"pacote": "20.0.1"` e `"tar": "^7.5.21"`. A versão forçada de `pacote` está fora do pin exato declarado pelo `@angular/cli`, e isso é aceito conscientemente como exceção, com base nestes fatos verificados: a única diferença de dependências entre `pacote@20.0.0` e `20.0.1` é `tar: ^6.1.11 -> ^7.5.10`, com `engines` e `bin` idênticos; `pacote` é usado apenas por `ng update` e `ng add`, nunca em build, teste, SSR ou runtime; com `tar ^7.5.21`, os requisitos de `cacache` (`^7.4.3`), `node-gyp` (`^7.4.3`) e `pacote@20.0.1` (`^7.5.10`) são satisfeitos pela mesma versão resolvida, e `npm ls` não reporta `invalid`. + +### Consequências +`npm audit --audit-level=critical` volta a sair com código 0 sem afrouxar o gate, sem `npm audit fix --force` e sem upgrade de major. O custo é um ponto de manutenção: no upgrade da toolchain Angular os dois overrides devem ser reavaliados e removidos assim que a cadeia oficial trouxer `tar` 7.x. Vulnerabilidades `high` e `moderate` remanescentes seguem a política do ADR-24: registradas como risco, nunca declaradas corrigidas.