bug(query): some openapi queries cannot be excluded from the report

[kisaiev]

When running KICS for the swagger.json it produces report with OpenAPI queries which cannot be excluded.

After a closer look it seems that some of the OpenAPI queries are not accessible:

• 6e96ed39-bf45-4089-99ba-f1fe7cf6966f - 404 ❌
• e3f026e8-fdb4-4d5a-bcfd-bd94452073fe - 200 ✅
• 586abcee-9653-462d-ad7b-2638a32bd6e6 - 404 ❌
• 74703c89-0ea2-49ab-a7db-bf04f19f5a57 - 404 ❌

All of them can still be reported, but not excluded. When the listed queries are passed to the KICS CLI via --exclude-queries, only e3f026e8-fdb4-4d5a-bcfd-bd94452073fe is removed.

Expected Behavior

All queries passed to the CLI via --exclude-queries option must be excluded.

Actual Behavior

Some of the queries are not excluded.

Steps to Reproduce the Problem

Please refer to the kics-openapi-exclude-bug repository for the demo.

Specifications

• Version: latest Docker image
• Platform: OpenAPI
• Subsystem: N/A

[cx-artur-ribeiro]

Hi @kisaiev, thank you so much for raising this issue! Special thanks for putting together the demo repository to demonstrate the problem. That was incredibly helpful and made it much easier to pinpoint the root cause.

You're absolutely right: some OpenAPI query results (particularly for OpenAPI Shared V2 cannot be excluded using the --exclude-queries flag and trying to access their documentation returns 404 errors.

As you've observed, only the query with a valid documentation page (e3f026e8...) could be excluded; the rest were still reported even when passed using the --exclude-queries flag. These were two separate problems: missing documentation pages for these queries and the incorrect exclusion from results.

The problem is that KICS uses a single physical query file to handle both OpenAPI V2 and V3:

• The query determines the OpenAPI version dynamically at runtime;
• Based on that version, it applies the appropriate override metadata, including a new ID, name, and description;
• The final query result includes an override key (e.g., "2.0", "3.0") and gets logically transformed into a version-specific result.

This design caused two main issues:

• OpenAPI General queries had documentation problems, which prevented separate docs for V2 from being generated;
• The main docs page grouped them under “Shared (V2/V3)” but didn’t generate the V2-specific queryDetails pages due to how the metadata varied from other queries.

The --exclude-queries flag only excluded physical queries (before override), and logical override IDs (like the V2-specific ones) weren’t recognized at that stage. As a result, those query results were still reported because they were excluded too late in the process.

We will address both issues by improving the documentation generation, processing all override variants individually, creating separate pages for each logical query (e.g., V2 and V3), and ensuring the correct metadata (ID, title, description, URL) is generated per variant. This will fix broken links to V2 query detail pages and add them to the main OpenAPI Queries Documentation page.

We will also add result-level filtering: results will now be filtered by their final resolved override ID (after override processing). This means the --exclude-queries flag will work for both the main physical query IDs and logical override IDs (such as the V2 query UUIDs), ensuring that both loading and reporting stages respect exclusions.

I hope this new approach bridges the gap properly. I will also link this issue to the PR fixing this problem so you’ll be notified once the fix is done.

Thank you again for the detailed report. I hope this explanation helps clarify the issues.