SW-A2A-003: Agent card at the path used before A2A 0.3

What it detects

The rule looks at the path of the card file. A file whose path ends in .well-known/agent.json, at any depth, is a card when it parses as strict JSON and has the card shape (a string name, and a supportedInterfaces list or a url). The rule then reports the card once, with the reason legacy_path. A file with that name that is not a card only gets a notice, because other software uses the same name.

The same rule covers a remote agent. Under --probe the scanner asks for /.well-known/agent-card.json first, and after a 404 or 410 it asks once for /.well-known/agent.json; a card found only there is reported too. The rule says nothing about what the card contains. It judges only where the card is kept.

Why it matters

Clients that follow the current specification look for the card at /.well-known/agent-card.json. A card kept at the older path is found by older clients and may not be found at all by current ones. If both paths are served and the two files differ, two groups of clients read two different descriptions of the same agent, and nobody has reviewed both. The scanner maps this rule to OWASP ASI07, Insecure Inter-Agent Communication, and to NIST SP 800-53 control SI-10, Information Input Validation.

Example

A complete 1.0 card saved as .well-known/agent.json instead of .well-known/agent-card.json:

.well-known/agent.json

{
  "name": "demo-agent",
  "description": "Drafts release notes from merged pull requests.",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://agent.example.invalid/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {},
  "securitySchemes": {
    "bearer": {
      "httpAuthSecurityScheme": {
        "scheme": "Bearer"
      }
    }
  },
  "securityRequirements": [
    {
      "schemes": {
        "bearer": {
          "list": []
        }
      }
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "skills": [
    {
      "id": "release-notes",
      "name": "Release notes",
      "description": "Drafts release notes for one tag.",
      "tags": [
        "release"
      ]
    }
  ]
}

The finding points at the file and says it is served at the old path. Renaming the file makes it go away.

How to fix

Move the file to .well-known/agent-card.json and serve it from /.well-known/agent-card.json. If older clients still need the old path, serve the same bytes at both for as long as you must, write down the date on which the old copy goes, and keep the two identical until then.

If it is a false positive

A file called agent.json that is not an agent card is never reported, so a finding means the scanner found the card shape. If you keep the old copy on purpose for older clients, accept the finding with a note that names the date the copy is removed.

If the finding is not a problem in your case, accept it with a note: in the dashboard a manager or owner can accept a finding and the note is kept with it; with the scanner on its own, add it to the baseline file with a reason and an expiry date.

Related rules

• SW-A2A-002: Agent card uses a format older than A2A 1.0
• SW-A2A-001: Agent card does not follow A2A 1.0