feat(core): add asyncapi security-defined lint rule by harshit078 · Pull Request #2759 · Redocly/redocly-cli

harshit078 · 2026-04-21T09:52:21Z

What/Why/How?

Added asyncapi-operation-security-defined rule for AsyncAPI 2.x and 3.x. both which reports when a security scheme referenced from an operation or server security array is not defined in ``components.securitySchemes.

Reference

#2667

Testing

Screenshots (optional)

Check yourself

This PR follows the contributing guide
All new/updated code is covered by tests
Core code changed? - Tested with other Redocly products (internal contributions only)
New package installed? - Tested in different environments (browser/node)
Documentation update has been considered

Security

The security impact of the change has been considered
Code follows company security practices and guidelines

Note

Medium Risk
New default error in recommended rulesets can break previously clean AsyncAPI lint runs; security and server-binding logic is nuanced and could produce false positives or misses on edge cases.

Overview
Adds the security-defined built-in rule for AsyncAPI 2.x and 3.x, aligned with the existing OpenAPI rule name and behavior.

For 2.x, the rule validates scheme names on operation/server security against components.securitySchemes, and flags operations with no own security when applicable servers (including channel bindings and traits) do not fully cover them. For 3.x, it validates $ref targets under components.securitySchemes and applies similar operation/server coverage checks on root operations.

The rule is wired into async2/async3 rule registries, built-in rule IDs, and preset configs (recommended at error, minimal at warn). Docs, sidebar, changeset, and broad unit tests are included.

Supporting changes add isAsyncOperationSecured, richer AsyncAPI typings/visitors for security-related nodes, and minor AsyncAPI split typing refactors (AnyAsyncApiComponents).

^{Reviewed by Cursor Bugbot for commit ffc7ef8. Bugbot is set up for automated code reviews on this repo. Configure here.}

changeset-bot · 2026-04-21T09:52:26Z

🦋 Changeset detected

Latest commit: ffc7ef8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	Minor
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vadyvas

I would suggest a slightly different approach:

keep the AsyncAPI logic separate and do not reuse shared logic from the OAS rule
use the same rule name, security-defined, for AsyncAPI as well, and register the AsyncAPI implementation in the AsyncAPI ruleset
do not update the v1 docs in this PR

I think this would make the change smaller, clearer, and safer.

Thank you for the contribution, overall the PR looks good

vadyvas

left a few comments, could you take a look?

vadyvas · 2026-05-04T16:37:22Z

  'info-contact': InfoContact as Async2Rule,
  'info-license-strict': InfoLicenseStrict as Async2Rule,
  'operation-operationId': OperationOperationId as Async2Rule,
+  'security-defined': SecurityDefined,


Please add support for AsyncAPI 3 as well. Right now the rule only applies to AsyncAPI2

okay sure !

vadyvas · 2026-05-04T16:39:19Z

The code uses the rule name security-defined, but the docs still say asyncapi-operation-security-defined
Can you update related changes?

vadyvas · 2026-05-04T16:40:22Z

@@ -0,0 +1,83 @@
+# asyncapi-operation-security-defined


Please don’t add this rule to the v1 docs

github-actions · 2026-06-22T12:12:22Z

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x ± 0.01	▓ 1.00x ± 0.01	▓ 1.00x ± 0.01
cli-next	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)

harshit078 · 2026-06-24T20:15:33Z

Hey @DmitryAnansky , I have fixed all comments and failing e2e tests and PR is good to review again. Thanks !

Daryna-del · 2026-07-01T06:25:07Z

    );
  });

+  it('should call createTestContext for arazzo type using the spec form without `workflows` segment', async () => {


Why do we need those changes?

I missed the existing check which was already present hence I agree with you and I should remove this.

harshit078 · 2026-07-03T12:30:25Z

Hey @Daryna-del , I have addressed all the comments left by you and cursor and also resolved the failing e2e tests. Can you review the recent changes again ? Thanks !

DmitryAnansky · 2026-07-08T15:39:37Z

+            location: itemLocation,
+            name,
+            refPointer,
+            resolved: resolved.node !== undefined,


This check treats a null-valued scheme entry as defined, am I right?
Seems that a scheme key with no value (half-finished YAML) silently passes.

I guess you are correct and I didnt catch it. $ref to a key with a null value resolves to node === null and since null !== undefined was marked as defined and silently passed.

DmitryAnansky · 2026-07-08T15:47:12Z

+  operation: SecuredOperation | undefined,
+  resolve: UserContext['resolve']
+): boolean {
+  if (operation?.security) return true;


This condition might be confusing.
Seems the function consider empty security (e.g. security: []) as Secured operation.
But it is actually public.

And have similar check that will result in opposite verdict:

serverHasSecurity.set( key.toString(), Array.isArray(server?.security) && server.security.length > 0 );

DmitryAnansky · 2026-07-08T15:59:08Z

+        if (rootOperations && rootLocation) {
+          const operationsLocation = rootLocation.child(['operations']);
+          for (const [opName, opRef] of Object.entries(rootOperations)) {
+            const operation = isRef(opRef) ? resolve<Async3Operation>(opRef).node : opRef;


Looks like only refs against the root document will be resolved here.
Please double check, but it seems that refs recorded relative to another file never resolve, producing false 'Every operation should have security defined' errors on multi-file docs.
Please check context.resolve functionality, maybe you need to handle this case as well.

DmitryAnansky · 2026-07-08T16:08:33Z

+  return {
+    Root: {
+      enter(root, { location }: UserContext) {
+        rootServers = root?.servers;


Could you please check if you handle the scenario with two files correctly:

# main.yaml asyncapi: 3.0.0 info: title: Test version: 1.0.0 servers: $ref: './servers.yaml' # ← map-level ref channels: myChannel: address: user/signedup operations: sendUserSignedUp: action: send channel: $ref: '#/channels/myChannel' # servers.yaml — the server IS secured prod: host: example.com protocol: kafka security: - type: apiKey in: user

DmitryAnansky · 2026-07-09T07:58:45Z

+
+function pointsToSecurityScheme(pointer: string): boolean {
+  return (
+    pointer.startsWith(SECURITY_SCHEMES_POINTER) &&


Seems external file references are not handled here.

The AsyncAPI 3.0 specification defines security requirements as an array of Security Scheme Objects, and states the general rule: any time a Schema Object can be used, a Reference Object can be used in its place, allowing referencing definitions instead of defining them inline. The Reference Object itself uses JSON Reference resolution — "For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification." JSON Reference allows the $ref value to be any URI, which includes relative file paths and remote URLs.

Please check the example. We able to bundle it with ref resolution but this new rule will produce false failure during file lint.

asyncapi: 3.0.0 info: title: Async3 External Security Ref version: 1.0.0 servers: production: host: broker.example.com protocol: mqtt security: - $ref: './apiKey.yaml' channels: userSignups: address: user/signedup messages: userSignedUp: payload: type: object properties: name: type: string operations: sendUserSignups: action: send channel: $ref: '#/channels/userSignups' security: - $ref: './apiKey.yaml'

apiKey.yaml =>

type: httpApiKey name: api_key in: header description: API key security scheme defined in an external file

cursor

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit ffc7ef8. Configure here.}

cursor · 2026-07-10T10:31:41Z

+            location: itemLocation,
+            name,
+            refPointer,
+            resolved: resolved.node !== undefined,


Null scheme counts as defined

Medium Severity

AsyncAPI 3 $ref resolution treats a target node of null as defined because resolved uses resolved.node !== undefined. AsyncAPI 2 marks any visited SecurityScheme key as defined without checking the scheme body, so a null entry under components.securitySchemes also passes.

Additional Locations (1)

packages/core/src/rules/async2/security-defined.ts#L53-L55

^{Reviewed by Cursor Bugbot for commit ffc7ef8. Configure here.}

cursor · 2026-07-10T10:31:41Z

+      enter(root, { location }: UserContext) {
+        rootServers = root?.servers;
+        rootOperations = root?.operations;
+        rootLocation = location;


Map-level servers ref ignored

High Severity

When top-level servers is a single $ref to another file (instead of a named map), AsyncAPI 3 keeps the raw ref in rootServers and later treats the resolved value as one server object. AsyncAPI 2 never records those servers in serverHasSecurity, so applicability checks see no secured servers.

Additional Locations (1)

packages/core/src/rules/async2/security-defined.ts#L75-L81

^{Reviewed by Cursor Bugbot for commit ffc7ef8. Configure here.}

feat: add 'asyncapi-operation-security-defined' rule

7acc84a

harshit078 and others added 6 commits April 21, 2026 15:22

Merge branch 'main' into add-asyncapi-rule

ddcf5e1

feat: added asyncapi-operation-security-define rule in tests

e1a30b6

feat: added async operation function and updated rules

1fa95ec

Merge branch 'main' into add-asyncapi-rule

14e7719

feat: updated lint md docs and added tests

d6df2bf

feat: added changset

d31dfbc

harshit078 changed the title ~~feat: Add asyncapi-operation-security-defined lint rule~~ feat(core): Add asyncapi-operation-security-defined lint rule Apr 24, 2026

Merge branch 'main' into add-asyncapi-rule

ce2789b

harshit078 marked this pull request as ready for review April 24, 2026 07:51

harshit078 requested review from a team as code owners April 24, 2026 07:51

harshit078 changed the title ~~feat(core): Add asyncapi-operation-security-defined lint rule~~ feat(core): add asyncapi-operation-security-defined lint rule Apr 24, 2026

cursor Bot reviewed Apr 24, 2026

View reviewed changes

Comment thread packages/core/src/rules/async2/asyncapi-operation-security-defined.ts

harshit078 and others added 2 commits April 24, 2026 15:36

fix: address comments by cursor

726a43e

Merge branch 'main' into add-asyncapi-rule

bb01316

vadyvas requested changes Apr 28, 2026

View reviewed changes

harshit078 and others added 5 commits April 30, 2026 13:18

Merge branch 'main' into add-asyncapi-rule

f671deb

fix: removed v1 doc update for async api

573cbef

fix: adress comments and remove shared helper

e0229df

fix: security defined package

27f2667

Merge branch 'main' into add-asyncapi-rule

0663a44

cursor Bot reviewed Apr 30, 2026

View reviewed changes

Comment thread packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap Outdated

fix: address cursor comment

dd80e01

harshit078 requested a review from vadyvas April 30, 2026 12:45

vadyvas requested changes May 4, 2026

View reviewed changes

harshit078 and others added 2 commits May 5, 2026 20:01

Merge branch 'main' into add-asyncapi-rule

cc6133e

removed: asyncapi from v1 docs

4bd8b15

cursor Bot reviewed May 6, 2026

View reviewed changes

Comment thread docs/@v1/v1.sidebars.yaml Outdated

Comment thread packages/core/src/rules/async2/index.ts

harshit078 requested a review from DmitryAnansky June 15, 2026 08:49

harshit078 and others added 3 commits June 19, 2026 16:27

Merge branch 'main' into add-asyncapi-rule

959b639

fix: failing tests

5679041

fix: duplicate async3 tests

39f8cc0

harshit078 and others added 3 commits June 24, 2026 18:06

Merge branch 'main' into add-asyncapi-rule

21d5d1d

fix: failing e2e tests

f6630ab

fix: address failing e2e tests

9b5b00e

cursor Bot reviewed Jun 24, 2026

View reviewed changes

Comment thread packages/core/src/rules/async2/security-defined.ts Outdated

harshit078 and others added 2 commits June 24, 2026 23:07

Merge branch 'main' into add-asyncapi-rule

0665edc

fix: address cursor comment

b8c7026

Daryna-del reviewed Jul 1, 2026

View reviewed changes

harshit078 and others added 3 commits July 1, 2026 22:54

Merge branch 'main' into add-asyncapi-rule

6954037

fix: address comments

4326620

Merge branch 'main' into add-asyncapi-rule

99f2ba7

cursor Bot reviewed Jul 3, 2026

View reviewed changes

Comment thread packages/core/src/rules/async3/security-defined.ts

harshit078 and others added 4 commits July 3, 2026 16:50

fix: address cursor comments and failing e2e tests

ed08156

Merge branch 'main' into add-asyncapi-rule

8e982e1

fix: failing e2e test

18d76ef

fix: failing e2e test

fb2fcb2

harshit078 requested a review from Daryna-del July 3, 2026 12:30

DmitryAnansky reviewed Jul 8, 2026

View reviewed changes

DmitryAnansky reviewed Jul 9, 2026

View reviewed changes

Merge branch 'main' into add-asyncapi-rule

ffc7ef8

cursor Bot reviewed Jul 10, 2026

View reviewed changes

Uh oh!

Conversation

harshit078 commented Apr 21, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

vadyvas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vadyvas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

Uh oh!

Uh oh!

harshit078 commented Jun 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

harshit078 commented Jul 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 10, 2026

Choose a reason for hiding this comment

Null scheme counts as defined

Uh oh!

cursor Bot Jul 10, 2026

Choose a reason for hiding this comment

Map-level servers ref ignored

Uh oh!

Reviewers

Assignees

Labels

harshit078 commented Apr 21, 2026 •

edited by cursor Bot

Loading

changeset-bot Bot commented Apr 21, 2026 •

edited

Loading

github-actions Bot commented Jun 22, 2026 •

edited

Loading