Skip to main content
Glama
Industrial-AIops Energy

Industrial-AIops Energy

device_advisory_check

Read-only

Checks scanned OT devices against a mounted advisory library and reports which fall inside an affected range, flagging unknown or unparsed firmware rather than declaring them safe.

Instructions

[READ][risk=low] Which scanned devices fall inside a mounted advisory's stated range.

`iaiops scan` already reads vendor / model / firmware / serial and then does
nothing with them. This closes that loop — and deliberately stops short of
where a vulnerability scanner would go.

**It reports that a device falls inside an advisory's stated range. Nothing
more.** Not "vulnerable", not "exploitable", no severity score. Whether a
published issue is reachable on a particular machine depends on
configuration, network position and compensating controls that a read-only
scan cannot see — and in OT most advisories against a protocol stack are not
findings at all, because the stack is not reachable from anywhere that
matters. A report full of red text that ignores that gets switched off by the
site, and then the real one is missed too.

**No database ships with this.** A bundled CVE feed is a maintenance
commitment this repo has not made, and a stale one that looks current is
worse than none — so the library is a file the site controls, which also
makes it work air-gapped. Every entry must carry a source, and one bad entry
refuses the whole file rather than half-mounting it.

Four verdicts, and the middle two are the point: `in_affected_range`,
`version_unknown` (model matches, no firmware read — neither a hit nor a
pass), `version_unparsed` (a firmware string it will not invent an ordering
for), `not_affected`. A device no advisory mentions is **absent** from the
findings, not reported clean: "nothing known" is not "nothing there".

Args:
    devices: [{ip?, vendor, model, firmware?}] — e.g. the `hosts` of a scan.
    library_path: Path to the advisory file (.yaml/.yml/.json) this site
        mounted, under $IAIOPS_HOME, the config directory or a directory
        the operator lists in IAIOPS_AGENT_READ_DIRS (other paths are refused unread);
        entries are {id, vendor, model, source, affected_below|affected_from|
        affected_versions, title?}.

Returns dict: {devices_checked, advisories_mounted, devices_with_findings,
    summary:{in_affected_range, version_unparsed, version_unknown,
    not_affected}, findings:[{ip, vendor, model, firmware, advisory_id, title,
    source, status, detail}], truncated, advisory_note, note}.

Example: device_advisory_check(devices=[{"ip":"10.0.0.5","vendor":"Siemens",
    "model":"S7-1500","firmware":"2.8.1"}], library_path="~/advisories.yaml").

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "devices": "<devices>",
      "library_path": "<library_path>"
    },
    "name": "device_advisory_check"
  }
}

Input Schema

NameRequiredDescriptionDefault
devicesYes
library_pathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.13

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, open-world, non-destructive behavior, but the description adds substantial context: file validation that refuses the whole library on one bad entry, air-gapped operation, the four verdict semantics, and the distinction between absent devices and devices reported clean. It also explains what the tool deliberately does not claim (vulnerable/exploitable/severity).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the Args/Returns/Example structure is clear, but the middle paragraphs include rhetorical rationale and repeated scope caveats that could be tightened. The definition is informative but noticeably verbose for a tool description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there is no output schema, the description documents the return dictionary and its key fields. Given the annotations cover the safety profile and the description covers both parameters and return semantics, an agent has enough to call and interpret the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the `devices` items have no declared fields, but the description supplies the item shape (`ip?`, `vendor`, `model`, `firmware?`) and explains `library_path` restrictions plus advisory entry structure. This fully compensates for the sparse schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific operation and scope: which scanned devices fall inside a mounted advisory's stated range. It clearly distinguishes this from a vulnerability scanner, but it does not name or differentiate against sibling tools such as mechanism_library_check or compliance_mapping, so it falls short of a full 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context that this closes the loop after `iaiops scan` and requires a site-mounted advisory library. However, it does not explicitly state 'use when' conditions versus alternatives, nor when not to use it; usage is implied rather than routed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools