Skip to content

fix: stop counting Swagger decorators as auth, flag empty and unsupported scans - #31

Merged
danieloceno merged 5 commits into
mainfrom
fix/swagger-auth-and-empty-scan
Nov 16, 2026
Merged

danieloceno merged 5 commits into
mainfrom
fix/swagger-auth-and-empty-scan

Conversation

@danieloceno

@danieloceno danieloceno commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

No open issue covers these. All three came from a demo rehearsal of ApiGate 0.4.0 on public repositories. The empty-scan point is related to #9 (closed), which made the score n/a for a scan with no endpoints; the status still said PASS.

What changed

  • Swagger decorators are not auth (lib/config.mjs).
    • @ApiBearerAuth, @ApiCookieAuth and @ApiSecurity are no longer default auth.nest markers. @ApiOAuth2 and @ApiBasicAuth never were. These @nestjs/swagger decorators only describe the OpenAPI document.
    • Seen on lujakob/nestjs-realworld-example-app at c1c2cc4: 20 of 21 endpoints were GUARDED with matchedAuthMarker: "ApiBearerAuth", while the app's real auth is an AuthMiddleware applied with .forRoutes(...) to a few routes.
    • A config that lists these decorators in auth.nest still counts them, because a list replaces the defaults.
  • An empty scan is not a pass (lib/gate.mjs, apigate.js, lib/report.mjs).
    • With no code endpoints and no OpenAPI spec, the status is NOTHING_ANALYSED in the console, the JSON status and gate.status, and the HTML badge.
    • A NOTICE: line, which is also the HTML hero text, says that ApiGate reads only Express, Fastify and NestJS routes and OpenAPI 2/3 specs.
    • The exit code stays 0, as for every empty scan before. --fail-on empty (no-endpoints) and requireSpec (missing-spec) still make it FAIL.
    • Seen on fastapi/full-stack-fastapi-template at aabb901: 0 endpoints and PASS.
  • Express routes count only in a repository that uses Express (lib/parsers/express.mjs, lib/inventory.mjs).
    • app.get(...) and router.get(...) are also Hono and Koa syntax. The Express parser's endpoints now count only when a scanned file imports or requires express, or the target's package.json declares it.
    • JavaScript files are checked on the parsed syntax tree: import and export declarations, import() and require(), with quotes or a plain template literal. TypeScript files (regex fallback) are checked with comments removed. A commented-out import does not count.
    • A router received as a parameter still counts when Express is imported in another scanned file or declared in package.json.
    • parserCapabilities.express.expressRequired states the rule in the JSON report.
    • Seen on documenso/documenso at 1e2333d: 2 "express" endpoints from apps/remix/server/router.ts, which is a Hono app, and PASS.
    • No Hono, Koa or tRPC parsing was added.
  • README:
    • what is not parsed (FastAPI, Django, Flask, Hono, tRPC, Koa, Next.js and Remix handlers), the Express rule above, and its limit: in a repository that also uses Express, Hono-style calls can still be read as Express;
    • the default auth identifiers per framework, where a helper must appear to count (a route argument, a path-less app.use, a mount's middleware; not a path-only app.use('/api/x', helper)), and that an auth.<framework> list replaces the defaults;
    • NOTHING_ANALYSED in the JSON sample, the exit-code table and --help, and the exit-code wording with requireSpec;
    • the historical ApiBearerAuth scan note now says it used the old defaults.
    • The path rules were checked on a probe app: an inline security.isAuthorized() yields the marker isAuthorized, a path-less app.use(requireAuth) guards later routes, and app.use('/api/scoped', requireAuth) leaves GET /api/scoped OPEN.
  • Release prep 0.4.1: package.json, package-lock.json, CHANGELOG ## [0.4.1] - 2026-11-16, and the README JSON sample "version".

Proof

"On main" means the branch's test files run against 53dfed4.

Test Branch On main
test/auth.mjs: NestJS endpoint whose only auth-looking decorator is from @nestjs/swagger → OPEN pass fails: ApiBearerAuth: expected "OPEN", got "GUARDED"
test/auth.mjs: NestJS endpoint with @UseGuards next to @ApiBearerAuth → GUARDED by UseGuards pass fails: expected "UseGuards", got "ApiBearerAuth"
test/gates.mjs: empty directory: NOTHING_ANALYSED, not PASS, and stdout names the supported frameworks pass fails: expected "NOTHING_ANALYSED", got "PASS"
test/gates.mjs: only an unsupported framework (FastAPI): NOTHING_ANALYSED, not PASS pass fails: expected "NOTHING_ANALYSED", got "PASS"
test/gates.mjs: only an unsupported JS framework (Hono app.get in .ts and .js): NOTHING_ANALYSED, not PASS pass fails: expected "NOTHING_ANALYSED", got "PASS"
test/gates.mjs: an express import inside a comment does not make a Hono app Express pass fails: expected "NOTHING_ANALYSED", got "PASS"
test/gates.mjs: require(express) with a template literal counts as Express pass passes; it guards against dropping real Express routes and failed on this branch at a323af1 (expected "PASS", got "NOTHING_ANALYSED")
test/gates.mjs: express declared only in package.json / imported in another scanned file: a router received as a parameter still counts pass passes (controls)

test/gate.mjs "no-endpoints fires only with failOn.emptyInventory ..." now expects NOTHING_ANALYSED instead of PASS for the empty case without the opt-in. The golden snapshot and the determinism tests are unchanged and pass.

Real repositories

Before: 0.4.0 at 53dfed4. After: this branch at 6f057f6. Same clones, same commits.

Repository Commit Before After
documenso/documenso 1e2333d PASS, 2 endpoints NOTHING_ANALYSED, 0 endpoints
fastapi/full-stack-fastapi-template aabb901 PASS, 0 endpoints NOTHING_ANALYSED, 0 endpoints
juice-shop/juice-shop 266448a FAIL, 256 endpoints, score 40 FAIL, the same 256 endpoints, score 40
lujakob/nestjs-realworld-example-app c1c2cc4 PASS, 21 endpoints (20 GUARDED by ApiBearerAuth), score 100 FAIL, the same 21 endpoints, all OPEN, score 50

The NestJS app's real auth is an AuthMiddleware applied with .forRoutes(...), which ApiGate does not read, so OPEN is what it can prove.

Gate

npm ci && npm run lint && npm test on Node 22.23.4 at 6f057f6, exit 0, 0 failed:

  • parser-express 37, parser-fastify 11, parser-nest 21, parser-openapi 4;
  • auth 14, drift 6, score 19, risk 15, diff 9, filter 16, explain 7, config 6, gate 15, gates 15;
  • capabilities 9, heuristics 10, golden 18, determinism 9, report-theme contract 19, scan safeguards 5.

npm pack --dry-run: 26 files. git diff --check 53dfed4..HEAD: clean.

Not changed

  • The Dogfood scores in the README come from earlier scans, and are not re-run here.
  • The HTML hero still says "inventories every HTTP endpoint" for scans that find endpoints.
  • Only the target's own package.json is read for the Express rule; a package.json inside a workspace folder is not.

@danieloceno danieloceno added the bug Something isn't working label Nov 16, 2026
app.get()/router.get() calls are also Hono and Koa syntax, so a Hono app got "express" endpoints and PASS. They now count only when a scanned file imports or requires express or the target's package.json declares it; otherwise a Hono-only scan is NOTHING_ANALYSED.
require(`express`) with a template literal now counts, and an import inside a comment no longer makes a Hono app Express. The status contract (README JSON schema, --help, exit-code wording with requireSpec) lists NOTHING_ANALYSED, and the historical ApiBearerAuth note matches the 0.4.1 defaults.
@danieloceno danieloceno changed the title fix: stop counting Swagger decorators as auth, flag empty scans fix: stop counting Swagger decorators as auth, flag empty and unsupported scans Nov 16, 2026
@danieloceno

Copy link
Copy Markdown
Contributor Author

Second-model review

Three passes by a different model than the one that wrote the change: a full review at 330c123, then a review of the fixes at a323af1, then a confirmation at 6f057f6.

  1. BLOCKING, fixed in f76919e. lib/parsers/express.mjs (hasExpressSignal) and lib/inventory.mjs (the Express block of buildInventory).
    • Problem: generic app.get(...) / router.get(...) calls were read as Express routes in any file, so a Hono app got "express" endpoints and PASS. That also made the new README sentence "ApiGate does not read ... Hono" untrue.
    • Proof: documenso/documenso at 1e2333d gave 2 endpoints from apps/remix/server/router.ts (a Hono app) and PASS.
    • Fix: the Express parser's endpoints count only when a scanned file imports or requires express, or the target's package.json declares it. Test "only an unsupported JS framework (Hono app.get in .ts and .js)" fails on 53dfed4 and on 330c123. documenso is now NOTHING_ANALYSED with 0 endpoints; juice-shop keeps the same 256 endpoints.
  2. Fixed in 6f057f6. lib/parsers/express.mjs (the Express import check).
    • Problem: the first fix matched the import with a plain text pattern. It missed require(express) written with a template literal, so a real Express app with no package.json lost its routes, and it accepted a commented-out import "express", so a Hono app with that comment still passed.
    • Fix: JavaScript files are checked on the parsed syntax tree (import and export declarations, import(), require()); TypeScript files are checked with comments removed. Tests "an express import inside a comment does not make a Hono app Express" and "require(express) with a template literal counts as Express" fail at a323af1 and pass now.
  3. Fixed in 6f057f6. README.md JSON sample, apigate.js --help, README and CHANGELOG exit-code wording.
    • Problem: the status was still documented as PASS | FAIL, and the docs said the exit code stays 0 unless --fail-on empty, while requireSpec also fails an empty scan (missing-spec).
    • Fix: NOTHING_ANALYSED is listed for status and gate.status and in --help; the wording names both gates.
  4. Fixed in 6f057f6. README.md, historical ApiBearerAuth scan note.
    • Problem: it still told users to remove ApiBearerAuth from auth.nest, as if it were a default.
    • Fix: it now says that scan used the old defaults and that since 0.4.1 only a custom auth.nest list counts Swagger decorators.

Minor, not fixed in this PR: test/capabilities.mjs does not assert the new expressRequired key, and the TypeScript comment check does not recognise regex literals (a quote inside one can hide a later import from the check; stated in the code).

Verdict: approve

In plain English

ApiGate said PASS in cases where it had not really checked anything: a repository with no routes it can read, and a Hono app whose routes it mistook for Express routes. It also treated a documentation-only NestJS decorator as a login check. Now those scans say NOTHING_ANALYSED, other frameworks' routes are ignored unless the project uses Express, and the decorator no longer counts as protection. The remaining risk is a project that mixes Express with another framework: there, the other framework's routes can still be read as Express, and the README says so.

@danieloceno
danieloceno merged commit 4e8e682 into main Nov 16, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant