KosmoKrator

data

OSV Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the OSV KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.osv.*. Use lua_read_doc("integrations.osv") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic OSV workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.osv.query({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("osv"))' --json
kosmo integrations:lua --eval 'print(docs.read("osv.query"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local osv = app.integrations.osv
local result = osv.query({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.osv, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.osv.default.* or app.integrations.osv.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need OSV, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

OSV

Namespace: osv

Use this integration to query OSV.dev open source vulnerability records by package version, package URL, git commit, batch query, or vulnerability ID. It also exposes OSV’s experimental import-findings and C/C++ version-determination endpoints.

Authentication

OSV.dev is public and does not require credentials.

Tools

  • osv_query: query one package version, package URL, or git commit. Use either commit, or a package query. For package queries, pass either package_name plus ecosystem, or purl. Add version unless the purl is already versioned.
  • osv_query_batch: query multiple package versions or commits. The response order matches the input queries order. OSV currently allows up to 1000 query items in one batch.
  • osv_get_vulnerability: retrieve one full OSV vulnerability record by ID.
  • osv_import_findings: experimental endpoint for records from a source that fail import-time quality checks.
  • osv_determine_version: experimental endpoint for identifying probable C/C++ library versions from relative file paths and base64-encoded MD5 hash bytes.

Return Notes

This package keeps OSV response field names intact. osv_query returns vulns and may include next_page_token. osv_query_batch returns results, where each result corresponds to the input query at the same index and may have its own next_page_token.

Case matters for ecosystems and vulnerability IDs. Use PyPI, not pypi; use the exact GHSA-*, CVE-*, or OSV-* identifier when fetching by ID.

Examples

local vulns = tools.osv_query({
  package_name = "jinja2",
  ecosystem = "PyPI",
  version = "3.1.4"
})

local batch = tools.osv_query_batch({
  queries = {
    {purl = "pkg:pypi/[email protected]"},
    {commit = "6879efc2c1596d11a6a6ad296f80063b558d5e0f"},
    {package_name = "jinja2", ecosystem = "PyPI", version = "2.4.1"}
  }
})

local record = tools.osv_get_vulnerability({
  id = "GHSA-vp9c-fpxx-744v"
})

For pagination, repeat the same query with page_token set to the returned next_page_token until no token remains.

Raw agent markdown 
# OSV

Namespace: `osv`

Use this integration to query OSV.dev open source vulnerability records by
package version, package URL, git commit, batch query, or vulnerability ID. It
also exposes OSV's experimental import-findings and C/C++ version-determination
endpoints.

## Authentication

OSV.dev is public and does not require credentials.

## Tools

- `osv_query`: query one package version, package URL, or git commit. Use
  either `commit`, or a package query. For package queries, pass either
  `package_name` plus `ecosystem`, or `purl`. Add `version` unless the purl is
  already versioned.
- `osv_query_batch`: query multiple package versions or commits. The response
  order matches the input `queries` order. OSV currently allows up to 1000 query
  items in one batch.
- `osv_get_vulnerability`: retrieve one full OSV vulnerability record by ID.
- `osv_import_findings`: experimental endpoint for records from a source that
  fail import-time quality checks.
- `osv_determine_version`: experimental endpoint for identifying probable C/C++
  library versions from relative file paths and base64-encoded MD5 hash bytes.

## Return Notes

This package keeps OSV response field names intact. `osv_query` returns
`vulns` and may include `next_page_token`. `osv_query_batch` returns `results`,
where each result corresponds to the input query at the same index and may have
its own `next_page_token`.

Case matters for ecosystems and vulnerability IDs. Use `PyPI`, not `pypi`; use
the exact `GHSA-*`, `CVE-*`, or `OSV-*` identifier when fetching by ID.

## Examples

```lua
local vulns = tools.osv_query({
  package_name = "jinja2",
  ecosystem = "PyPI",
  version = "3.1.4"
})

local batch = tools.osv_query_batch({
  queries = {
    {purl = "pkg:pypi/[email protected]"},
    {commit = "6879efc2c1596d11a6a6ad296f80063b558d5e0f"},
    {package_name = "jinja2", ecosystem = "PyPI", version = "2.4.1"}
  }
})

local record = tools.osv_get_vulnerability({
  id = "GHSA-vp9c-fpxx-744v"
})
```

For pagination, repeat the same query with `page_token` set to the returned
`next_page_token` until no token remains.
Metadata-derived Lua example 
local result = app.integrations.osv.query({})
print(result)

Functions

query Read

Query vulnerabilities for one package version, purl, or commit.

Lua path
app.integrations.osv.query
Full name
osv.osv_query
ParameterTypeRequiredDescription
No parameters.
query_batch Read

Query vulnerabilities for multiple package versions or commits.

Lua path
app.integrations.osv.query_batch
Full name
osv.osv_query_batch
ParameterTypeRequiredDescription
No parameters.
get_vulnerability Read

Retrieve one OSV vulnerability record by ID.

Lua path
app.integrations.osv.get_vulnerability
Full name
osv.osv_get_vulnerability
ParameterTypeRequiredDescription
No parameters.
import_findings Read

Retrieve experimental import-quality findings for a source.

Lua path
app.integrations.osv.import_findings
Full name
osv.osv_import_findings
ParameterTypeRequiredDescription
No parameters.
determine_version Read

Experimentally identify likely C/C++ library versions from file hashes.

Lua path
app.integrations.osv.determine_version
Full name
osv.osv_determine_version
ParameterTypeRequiredDescription
No parameters.