KosmoKrator

data

Have I Been Pwned Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Have I Been Pwned KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.have_i_been_pwned.*. Use lua_read_doc("integrations.have-i-been-pwned") 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 Have I Been Pwned workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.have_i_been_pwned.breached_account({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("have-i-been-pwned"))' --json
kosmo integrations:lua --eval 'print(docs.read("have-i-been-pwned.breached_account"))' --json

Workflow file

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

workflow.lua 
local have_i_been_pwned = app.integrations.have_i_been_pwned
local result = have_i_been_pwned.breached_account({})

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.have_i_been_pwned, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.have_i_been_pwned.default.* or app.integrations.have_i_been_pwned.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Have I Been Pwned, 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.

Have I Been Pwned

Namespace: have-i-been-pwned

Use this integration to inspect public breach metadata, check account exposure, query verified-domain breach data, inspect paste exposure, retrieve stealer-log summaries, check subscription status, and query the Pwned Passwords range API.

Authentication

The breach catalogue tools and hibp_pwned_password_range work without an API key. Account, paste, domain, stealer-log, domain-verification, subscribed-domain, and subscription tools require an HIBP API key. When a protected tool is called without credentials, it returns a clear configuration error instead of making an unauthenticated request.

Tools

  • hibp_breached_account: returns breaches for an email address. Pass truncate_response=false when you need complete breach objects instead of only names. A not-found result is normalized to an empty array.
  • hibp_breached_account_range: queries the six-character SHA-1 account hash prefix endpoint and returns HIBP’s hash suffix response.
  • hibp_breaches: lists public breach catalogue entries. Optional filters are domain and is_spam_list.
  • hibp_breach_by_name: retrieves one breach by stable HIBP Name.
  • hibp_latest_breach: retrieves the most recently added breach.
  • hibp_data_classes: lists all breach data classes.
  • hibp_paste_account: lists paste records for an email address. A not-found result is normalized to an empty array.
  • hibp_breached_domain: lists breached aliases and breach names for a verified domain. A not-found result is normalized to an empty array.
  • hibp_subscribed_domains: lists domains attached to the API-key subscription.
  • hibp_generate_dns_token: generates a DNS TXT token for domain verification.
  • hibp_verify_dns_token: asks HIBP to verify the DNS TXT token.
  • hibp_send_domain_verification_email: sends a verification email to one of admin, hostmaster, info, security, or webmaster.
  • hibp_stealer_logs_by_email: lists website domains found in stealer logs for an email address.
  • hibp_stealer_logs_by_website_domain: lists email addresses found in stealer logs for a website domain.
  • hibp_stealer_logs_by_email_domain: lists stealer-log records for addresses under an email domain.
  • hibp_subscription_status: retrieves status for the configured API key.
  • hibp_pwned_password_range: queries Pwned Passwords by the first five hexadecimal characters of a SHA-1 or NTLM hash.

Return Notes

This package keeps HIBP’s response field names intact. Breach objects include fields such as Name, Title, Domain, BreachDate, AddedDate, ModifiedDate, PwnCount, DataClasses, and status flags. Pwned Passwords range responses are normalized to:

{
  "prefix": "21BD1",
  "mode": "sha1",
  "padded": true,
  "matches": [
    {"hash_suffix": "DA6EE5E6BAE3D2F8C4BDB1A70E3E7F4E4B7F8A", "count": 42}
  ]
}

When padding=true, HIBP may include zero-count padding rows. Treat only positive count matches as breached passwords.

Examples

local recent = tools.hibp_latest_breach({})

local breaches = tools.hibp_breached_account({
  account = "[email protected]",
  truncate_response = false
})

local range = tools.hibp_pwned_password_range({
  prefix = "21BD1",
  mode = "sha1"
})

Do not send plaintext passwords to this integration. Hash the password outside the tool and pass only the first five hexadecimal hash characters to hibp_pwned_password_range.

Raw agent markdown 
# Have I Been Pwned

Namespace: `have-i-been-pwned`

Use this integration to inspect public breach metadata, check account exposure,
query verified-domain breach data, inspect paste exposure, retrieve stealer-log
summaries, check subscription status, and query the Pwned Passwords range API.

## Authentication

The breach catalogue tools and `hibp_pwned_password_range` work without an API
key. Account, paste, domain, stealer-log, domain-verification, subscribed-domain,
and subscription tools require an HIBP API key. When a protected tool is called
without credentials, it returns a clear configuration error instead of making an
unauthenticated request.

## Tools

- `hibp_breached_account`: returns breaches for an email address. Pass
  `truncate_response=false` when you need complete breach objects instead of
  only names. A not-found result is normalized to an empty array.
- `hibp_breached_account_range`: queries the six-character SHA-1 account hash
  prefix endpoint and returns HIBP's hash suffix response.
- `hibp_breaches`: lists public breach catalogue entries. Optional filters are
  `domain` and `is_spam_list`.
- `hibp_breach_by_name`: retrieves one breach by stable HIBP `Name`.
- `hibp_latest_breach`: retrieves the most recently added breach.
- `hibp_data_classes`: lists all breach data classes.
- `hibp_paste_account`: lists paste records for an email address. A not-found
  result is normalized to an empty array.
- `hibp_breached_domain`: lists breached aliases and breach names for a verified
  domain. A not-found result is normalized to an empty array.
- `hibp_subscribed_domains`: lists domains attached to the API-key subscription.
- `hibp_generate_dns_token`: generates a DNS TXT token for domain verification.
- `hibp_verify_dns_token`: asks HIBP to verify the DNS TXT token.
- `hibp_send_domain_verification_email`: sends a verification email to one of
  `admin`, `hostmaster`, `info`, `security`, or `webmaster`.
- `hibp_stealer_logs_by_email`: lists website domains found in stealer logs for
  an email address.
- `hibp_stealer_logs_by_website_domain`: lists email addresses found in stealer
  logs for a website domain.
- `hibp_stealer_logs_by_email_domain`: lists stealer-log records for addresses
  under an email domain.
- `hibp_subscription_status`: retrieves status for the configured API key.
- `hibp_pwned_password_range`: queries Pwned Passwords by the first five
  hexadecimal characters of a SHA-1 or NTLM hash.

## Return Notes

This package keeps HIBP's response field names intact. Breach objects include
fields such as `Name`, `Title`, `Domain`, `BreachDate`, `AddedDate`,
`ModifiedDate`, `PwnCount`, `DataClasses`, and status flags. Pwned Passwords
range responses are normalized to:

```json
{
  "prefix": "21BD1",
  "mode": "sha1",
  "padded": true,
  "matches": [
    {"hash_suffix": "DA6EE5E6BAE3D2F8C4BDB1A70E3E7F4E4B7F8A", "count": 42}
  ]
}
```

When `padding=true`, HIBP may include zero-count padding rows. Treat only
positive `count` matches as breached passwords.

## Examples

```lua
local recent = tools.hibp_latest_breach({})

local breaches = tools.hibp_breached_account({
  account = "[email protected]",
  truncate_response = false
})

local range = tools.hibp_pwned_password_range({
  prefix = "21BD1",
  mode = "sha1"
})
```

Do not send plaintext passwords to this integration. Hash the password outside
the tool and pass only the first five hexadecimal hash characters to
`hibp_pwned_password_range`.
Metadata-derived Lua example 
local result = app.integrations.have_i_been_pwned.breached_account({})
print(result)

Functions

breached_account Read

List breaches for an email address.

Lua path
app.integrations.have_i_been_pwned.breached_account
Full name
have-i-been-pwned.hibp_breached_account
ParameterTypeRequiredDescription
No parameters.
breached_account_range Read

List email hash suffixes and affected sites for an account hash prefix.

Lua path
app.integrations.have_i_been_pwned.breached_account_range
Full name
have-i-been-pwned.hibp_breached_account_range
ParameterTypeRequiredDescription
No parameters.
breaches Read

List breach catalogue entries.

Lua path
app.integrations.have_i_been_pwned.breaches
Full name
have-i-been-pwned.hibp_breaches
ParameterTypeRequiredDescription
No parameters.
breach_by_name Read

Retrieve one breach by system name.

Lua path
app.integrations.have_i_been_pwned.breach_by_name
Full name
have-i-been-pwned.hibp_breach_by_name
ParameterTypeRequiredDescription
No parameters.
latest_breach Read

Retrieve the most recently added breach.

Lua path
app.integrations.have_i_been_pwned.latest_breach
Full name
have-i-been-pwned.hibp_latest_breach
ParameterTypeRequiredDescription
No parameters.
data_classes Read

List all breach data classes.

Lua path
app.integrations.have_i_been_pwned.data_classes
Full name
have-i-been-pwned.hibp_data_classes
ParameterTypeRequiredDescription
No parameters.
paste_account Read

List pastes for an email address.

Lua path
app.integrations.have_i_been_pwned.paste_account
Full name
have-i-been-pwned.hibp_paste_account
ParameterTypeRequiredDescription
No parameters.
breached_domain Read

List breached accounts for a verified domain.

Lua path
app.integrations.have_i_been_pwned.breached_domain
Full name
have-i-been-pwned.hibp_breached_domain
ParameterTypeRequiredDescription
No parameters.
subscribed_domains Read

List domains tied to the API-key subscription.

Lua path
app.integrations.have_i_been_pwned.subscribed_domains
Full name
have-i-been-pwned.hibp_subscribed_domains
ParameterTypeRequiredDescription
No parameters.
generate_dns_token Read

Generate a DNS ownership-verification token.

Lua path
app.integrations.have_i_been_pwned.generate_dns_token
Full name
have-i-been-pwned.hibp_generate_dns_token
ParameterTypeRequiredDescription
No parameters.
verify_dns_token Write

Verify a domain DNS token with HIBP.

Lua path
app.integrations.have_i_been_pwned.verify_dns_token
Full name
have-i-been-pwned.hibp_verify_dns_token
ParameterTypeRequiredDescription
No parameters.
send_domain_verification_email Write

Send an HIBP domain verification email.

Lua path
app.integrations.have_i_been_pwned.send_domain_verification_email
Full name
have-i-been-pwned.hibp_send_domain_verification_email
ParameterTypeRequiredDescription
No parameters.
stealer_logs_by_email Read

Check stealer logs by email address.

Lua path
app.integrations.have_i_been_pwned.stealer_logs_by_email
Full name
have-i-been-pwned.hibp_stealer_logs_by_email
ParameterTypeRequiredDescription
No parameters.
stealer_logs_by_website_domain Read

Check stealer logs by compromised website domain.

Lua path
app.integrations.have_i_been_pwned.stealer_logs_by_website_domain
Full name
have-i-been-pwned.hibp_stealer_logs_by_website_domain
ParameterTypeRequiredDescription
No parameters.
stealer_logs_by_email_domain Read

Check stealer logs by email address domain.

Lua path
app.integrations.have_i_been_pwned.stealer_logs_by_email_domain
Full name
have-i-been-pwned.hibp_stealer_logs_by_email_domain
ParameterTypeRequiredDescription
No parameters.
subscription_status Read

Retrieve subscription status for the API key.

Lua path
app.integrations.have_i_been_pwned.subscription_status
Full name
have-i-been-pwned.hibp_subscription_status
ParameterTypeRequiredDescription
No parameters.
password_range Read

Query Pwned Passwords by hash prefix.

Lua path
app.integrations.have_i_been_pwned.password_range
Full name
have-i-been-pwned.hibp_pwned_password_range
ParameterTypeRequiredDescription
No parameters.