graphql: Improve GraphQL fingerprinting with specificity scoring

[kingthorin]

Overview

Implements specificity-based ordering for GraphQL framework fingerprinting to increase efficiency and potentially reduce false positives by checking specific patterns before generic ones.

This is one of a set of PRs that I'm working on for GraphQL Fingerprinting.

---

This also fixes a bug whereby the handlers were always reset on instantiation when they should have only been reset if null. So the Tech Detection support had been broken. (I can move that fix to a separate PR if necessary.)

Changes

• FingerprintCheck record: Encapsulates each check with a specificity score (0-100), validated at construction
• Descending order iteration: Checks run in order of decreasing specificity; first match wins
• Refactored structure: Extracted performPatternBasedDetection() and raiseAlertForFramework() for clarity
• Minor fix: Added null/JSON check in checkStrawberryEngine()

Specificity Tiers

Tier	Score	Description	Examples
A	90-95	Unique error patterns	tartiflette, hasura, dgraph
B	80-89	Distinctive patterns	wpgraphql, absinthe, sangria
C	70-79	Language/framework hints	graphql-java, gqlgen, juniper
D	60-69	Common GraphQL errors	apollo, graphene, mercurius
E	50-59	Very generic	lighthouse

Scoring Guidelines for Future Contributors

When adding a new fingerprint check, assign a specificity score based on how unique the matched pattern is to that specific framework:

• 90+: Pattern includes framework name, unique identifiers, or error text that only that framework produces
• 70-89: Pattern is distinctive (e.g., language-specific error format, unusual field names) but could theoretically appear elsewhere
• 60-69: Pattern uses common GraphQL error structures that multiple frameworks might produce
• 50-59: Pattern matches very generic errors; high false-positive risk

When in doubt, start lower—a false negative (missed detection) is less harmful than a false positive (wrong framework reported).

AI Disclosure

Portions of this contribution were prepared by copilot or augment code.

[psiinon]

Checkmarx One – Scan Summary & Details – dcbdf96f-e3de-463d-969d-96e964446403

New Issues (3)

Checkmarx found the following issues in this Pull Request

#	Severity	Issue	Source File / Package	Checkmarx Insight
1		Unpinned Actions Full Length Commit SHA	/codeql.yml: 31	details Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA help...
2		Unpinned Actions Full Length Commit SHA	/codeql.yml: 35	details Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA help...
3		Unpinned Actions Full Length Commit SHA	/codeql.yml: 50	details Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA help...

---

Use @Checkmarx to interact with Checkmarx PR Assistant.
Examples:
@Checkmarx how are you able to help me?
@Checkmarx rescan this PR

[Copilot]

Pull request overview

Updates the GraphQL add-on’s framework fingerprinter to evaluate fingerprint checks in descending “specificity” order (most unique patterns first), aiming to reduce false positives and improve detection efficiency.

Changes:

• Introduces a FingerprintCheck record with a validated specificity score and uses it to order fingerprint checks.
• Refactors fingerprinting flow into performPatternBasedDetection() + raiseAlertForFramework() with first-match-wins behavior.
• Extends unit tests with stricter “no logged WARN/ERROR” assertions and adds a Juniper detection/evidence test.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
addOns/graphql/src/main/java/org/zaproxy/addon/graphql/GraphQlFingerprinter.java	Adds specificity-scored checks, sorts checks by score, refactors detection/alerting, and hardens Strawberry detection against non-JSON/null responses.
addOns/graphql/src/test/java/org/zaproxy/addon/graphql/GraphQlFingerprinterUnitTest.java	Updates invalid-data expectations, introduces helper for asserting no logged errors, and adds a Juniper pattern/evidence test.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thc202]

Where's the data/evidence for the claims?

[kingthorin]

First is the removed comment:
// TODO: Check whether the order of the fingerprint checks matters.

Logically if the checks can be classified as a range of specific to generic then the order does matter.

Further summary/sources: https://gist.github.com/kingthorin/53859ce98cbe73559898dfee355dd6df

Let me know if you'd like the gist content added here somewhere/somehow.

[thc202]

It's not a logical conclusion since an error is only generic if there are more than one/many GraphQL engines producing those errors, neither your comment nor the gist provide data/evidence for that (where's the sample of errors from all/some of the engines being checked to claim that they are generic). If you read the quote in the gist it says respond uniquely which implies there's no overlap between the errors being triggered, if they are unique the order does not matter (I recall that we added more checks, not sure if all from the same source, but same requirement applies, to know if something is generic you need concrete data showing so). There's also the claims of efficiency and FPs (though the latter is covered by the error uniqueness or not).

[kingthorin]

Point taken. I'll look at another way to tackle this that's more evidence based.

I'll move the small bug fix into another PR, convert this one to draft for now.

[kingthorin]

To your other point the additional checks were from the same source as the originals.