MokN
MokN is a deception technology platform that deploys decoy login portals (baits) and agents to detect and analyze credential-based attacks in real time.
MokN is a deception-based security platform that deploys realistic login portals ("baits") and integrates with identity providers to detect and analyze credential theft attempts. This connector enables Swimlane Turbine users to automate the deployment, management, and monitoring of MokN baits and agents, retrieve detailed attack analytics, and orchestrate rapid responses to identity-based threats. By integrating MokN with Swimlane Turbine, security teams can proactively detect credential harvesting, gain deep visibility into attacker behavior, and streamline identity protection workflowsβall without writing code.
Limitations
- Actions that change baits or agents require an API key with write permissions. A key without them returns 403 Forbidden with the message Not enough permission to perform this action.
- Deleting a bait is asynchronous. Use Retrieve Bait Creation Status or Retrieve a Bait to follow its progress.
- Dashboard actions accept months in YYYY/MM format only.
Supported Versions
This MokN connector uses the MokN API version 1 (/api/v1).
Configuration
Prerequisites
To use the MokN connector, ensure you have the following prerequisites:
- API Key Authentication:
- URL: The base endpoint for your MokN instance's API.
- API Key: A valid MokN API key for authenticating requests, sent in the X-MOKN-API-KEY header.
- HTTP Bearer Token Authentication:
- URL: The base endpoint for your MokN instance's API.
- API Token: A valid MokN API token to be used as a bearer token for authentication.
Authentication Methods
API Key Authentication:
- URL: The URL of your MokN tenant.
- API Key: A MokN API key with the permissions needed by the actions you run.
HTTP Bearer Authentication:
- URL: The URL of your MokN tenant.
- API Token: A MokN API token with the permissions needed by the actions you run.
Capabilities
This MokN connector provides the following capabilities:
- Bulk Update Baits
- Create a New Agent
- Delete a Bait
- Delete an Agent
- Export Agent Configuration
- List All Agents
- List All Baits
- List Attacker Aggregates
- List Available Skins
- List Certificate Authorities
- Retrieve a Bait
- Retrieve Agent Details
- Retrieve Agents Queue
- Retrieve Average Time Between Two Attempts
- Retrieve Bait Creation Status ... and so on
Bait Management
Bulk Update Baits
Updates several baits in a single request, for example whether the data collected by each bait is kept. Provide a list of objects, each with the bait id and the fields to change.
Delete a Bait
Deletes a bait by its ID. The deletion is processed asynchronously.
List All Baits
Lists all baits with their hosting, certificate, status and alerting configuration. Set include_deleted to include deleted baits.
List Available Skins
Lists the skins (login portal templates, such as a Fortinet VPN portal) available for creating baits.
List Certificate Authorities
Lists the certificate authorities available to issue TLS certificates for baits.
Retrieve a Bait
Retrieves the details of a bait by its ID.
Retrieve Bait Creation Status
Retrieves the creation status of the baits currently being deployed.
Retrieve Short List of Baits
Retrieves the ID and name of every bait. Set include_deleted to include deleted baits.
Agent Management
Agents connect MokN to your identity provider to check whether captured credentials are valid.
Create a New Agent
Creates an agent connected to an identity provider. name and agent_type are required. The other fields depend on the agent type (see Agent Typesο»Ώ).
Delete an Agent
Deletes an agent by its ID.
Export Agent Configuration
Exports the configuration archive (zip) used to install or update an agent. export must be true. Set new to true to generate a configuration for a new installation instead of an update of the existing one.
List All Agents
Lists all agents with their status and the latest available agent versions.
Retrieve Agent Details
Retrieves the details of an agent by its ID.
Retrieve Agents Queue
Retrieves the login attempts waiting to be checked by agents, being checked, and already checked. Filter by bait_id, and use nb_checked to limit the number of checked attempts returned.
Retrieve Short List of Agents
Retrieves the ID and name of every agent.
Update an Agent
Updates the configuration of an existing agent. Only the fields you provide are changed.
Attack Intelligence and Dashboards
The dashboard actions accept the following optional parameters:
- id: Restrict the results to these bait IDs. When omitted, all baits are returned.
- start_month and end_month: The period to report on, in YYYY/MM format.
- detail: Whether to include detailed results for each bait.
- limit: The maximum number of entries returned for each bait (Top Passwords and Top Usernames only).
List Attacker Aggregates
Lists attacker aggregates computed from the login attempts captured by baits. Supports page, page_size, date_from and date_to.
Retrieve Average Time Between Two Attempts
Retrieves the average time between two login attempts, for all baits and for each bait.
Retrieve Monthly History
Retrieves the monthly history of login attempts, for all baits and for each bait.
Retrieve Monthly History Dates
Retrieves the first and last months for which a monthly history is available.
Retrieve Targeting Countries Data
Retrieves the top countries from which login attempts originate.
Retrieve Threat Level
Retrieves the threat level, for all baits and for each bait.
Retrieve Top Passwords
Retrieves the passwords most used in login attempts.
Retrieve Top Usernames
Retrieves the usernames most targeted in login attempts.
Retrieve Unique Targeted Accounts Data
Retrieves the number of unique accounts targeted in login attempts.
Tasks Setup
Agent Types
The agent_type input of Create a New Agent and Update an Agent accepts the following values:
Value | Identity provider | Type-specific fields |
|---|---|---|
AgentAD | Active Directory | domain, domain_controller, search_base, lockout_threshold (0 to 9999), tls_ssl, tls_ssl_verify, attributes |
AgentEntra | Microsoft Entra ID | tenant_id, client_id, client_secret (the secret value, not the secret ID), domains, is_fast_setup |
AgentOkta | Okta | domain, ssws_token (Okta API token), domains |
AgentGoogle | Google Workspace | domains, attributes, tls_client_certificate, tls_client_private_key (PEM-encoded) |
AgentXSOAR | Cortex XSOAR | None |
AgentCustom | Custom | None |
All agent types accept recipients, the email addresses notified about the agent. To monitor an agent with a known valid account, set valid_username and valid_password together.
Additional Documentation
Configurations
MokN API Key Authentication
Authenticates using a MokN API key sent in the X-MOKN-API-KEY header.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | The URL of your MokN tenant, for example https:// ο»Ώ | string | Required |
X-MOKN-API-KEY | The MokN API key generated in the MokN console. | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
MokN HTTP Bearer Authentication
Authenticates using a MokN API token sent as a bearer token.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | The URL of your MokN tenant, for example https:// ο»Ώ | string | Required |
token | The MokN API token generated in the MokN console. | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Bulk Update Baits
Update multiple MokN baits in a single request, including options such as retaining or modifying bait data.
Endpoint
- URL: /api/v1/baits/baits
- Method: PATCH
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | string | The updated baits. |
Output Example
{"status":"active","message":"string","data":"string"}
Create a New Agent
Create a new MokN agent linked to an identity provider such as Active Directory, Entra ID, Okta, Google, XSOAR, or Custom by specifying the agent name and type.
Endpoint
- URL: /api/v1/baits/agents
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
name | string | Optional | The display name of the agent. |
agent_type | string | Optional | The identity provider type the agent connects to. |
recipients | array | Optional | The email addresses notified about this agent. |
valid_username | string | Optional | A valid account username used to monitor the agent. Must be set together with Valid Password. |
valid_password | string | Optional | The password of the monitoring account. |
domain | string | Optional | The domain of the identity provider (Active Directory and Okta agents). |
domains | array | Optional | The email domains handled by the agent (Entra ID, Okta and Google agents). |
domain_controller | string | Optional | The host of the domain controller (Active Directory agents). |
search_base | string | Optional | The LDAP search scope (Active Directory agents). |
lockout_threshold | integer | Optional | The account lockout threshold, between 0 and 9999 (Active Directory agents). |
tls_ssl | boolean | Optional | Whether LDAP connections use TLS/SSL (Active Directory agents). |
tls_ssl_verify | boolean | Optional | Whether the LDAP TLS certificate is verified (Active Directory agents). |
attributes | array | Optional | The directory attributes used to match usernames (Active Directory and Google agents). |
tenant_id | string | Optional | The Microsoft Entra ID tenant ID (Entra ID agents). |
client_id | string | Optional | The Microsoft Entra ID application client ID (Entra ID agents). |
client_secret | string | Optional | The Microsoft Entra ID application client secret value, not the secret ID (Entra ID agents). |
is_fast_setup | boolean | Optional | Whether the Entra ID fast setup is used (Entra ID agents). |
ssws_token | string | Optional | The Okta API token (Okta agents). |
tls_client_certificate | string | Optional | The PEM-encoded TLS client certificate (Google agents). |
tls_client_private_key | string | Optional | The PEM-encoded TLS client private key (Google agents). |
Input Example
{"json_body":{"name":"Corporate AD agent","agent_type":"AgentAD","recipients":["[email protected]"],"domain":"corp.example.com","domain_controller":"dc01.corp.example.com","search_base":"DC=corp,DC=example,DC=com","lockout_threshold":0,"tls_ssl":true,"tls_ssl_verify":false,"attributes":["mail","samaccountname","userprincipalname"]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The agent details. |
data.id | integer | The unique identifier of the agent. |
data.name | string | The display name of the agent. |
data.agent_type | string | The identity provider type the agent connects to. |
data.is_alive | boolean | Whether the agent is currently alive and reporting to MokN. |
data.is_reachable | boolean | Whether the identity provider is reachable by the agent. |
data.last_seen | string | The date and time the agent last contacted MokN. |
data.date_created | string | The date and time the agent was created. |
data.server | string | The server the agent is installed on. |
data.version | string | The installed agent version. |
data.recipients | array | The email addresses notified about this agent. |
data.last_check_at | string | The date and time of the last credential check performed by the agent. |
data.today_checks | integer | The number of credential checks performed today. |
data.total_checks | integer | The total number of credential checks performed by the agent. |
data.domain | string | The domain the agent is attached to (Active Directory / Okta). |
data.domains | array | The email domains handled by the agent. |
Output Example
{"status":"active","message":"string","data":{"id":123,"name":"Example Name","agent_type":"string","is_alive":true,"is_reachable":true,"last_seen":"string","date_created":"string","server":"string","version":"string","recipients":["string"],"last_check_at":"string","today_checks":123,"total_checks":123,"domain":"string","domains":["string"]}}
Delete a Bait
Remove a MokN bait asynchronously using its unique bait ID.
Endpoint
- URL: /api/v1/baits/baits/{{bait_id}}
- Method: DELETE
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.bait_id | integer | Required | The unique identifier of the bait. |
Input Example
{"path_parameters":{"bait_id":101}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The result of the deletion. |
Output Example
{"status":"active","message":"string","data":{}}
Delete an Agent
Remove a MokN agent from your environment using the specified agent ID.
Endpoint
- URL: /api/v1/baits/agents/{{agent_id}}
- Method: DELETE
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.agent_id | integer | Required | The unique identifier of the agent. |
Input Example
{"path_parameters":{"agent_id":12}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The result of the deletion. |
Output Example
{"status":"active","message":"string","data":{}}
Export Agent Configuration
Export the configuration archive (ZIP) for a MokN agent using the agent ID and export parameters to facilitate installation or updates.
Endpoint
- URL: /api/v1/baits/agents/{{agent_id}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.agent_id | integer | Required | The unique identifier of the agent. |
parameters.export | boolean | Required | Must be true to export the agent configuration archive. |
parameters.new | boolean | Optional | Generate a new configuration (new installation) instead of an update of the existing one. |
Input Example
{"parameters":{"export":true,"new":false},"path_parameters":{"agent_id":12}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
file | object | The exported agent configuration archive. |
file.file | string | Output field: file.file |
file.file_name | string | Name of the resource |
Output Example
{"file":{"file":"string","file_name":"Example Name"}}
List All Agents
Retrieve a list of all MokN agents, including their current status and the latest available agent versions.
Endpoint
- URL: /api/v1/baits/agents
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.can_sync | boolean | Optional | Return only agents that can synchronize users. |
Input Example
{"parameters":{"can_sync":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The agents and the latest available agent versions. |
data.agents | array | The list of agents. |
data.agents.id | integer | The unique identifier of the agent. |
data.agents.name | string | The display name of the agent. |
data.agents.agent_type | string | The identity provider type the agent connects to. |
data.agents.is_alive | boolean | Whether the agent is currently alive and reporting to MokN. |
data.agents.is_reachable | boolean | Whether the identity provider is reachable by the agent. |
data.agents.last_seen | string | The date and time the agent last contacted MokN. |
data.agents.date_created | string | The date and time the agent was created. |
data.agents.server | string | The server the agent is installed on. |
data.agents.version | string | The installed agent version. |
data.agents.recipients | array | The email addresses notified about this agent. |
data.agents.last_check_at | string | The date and time of the last credential check performed by the agent. |
data.agents.today_checks | integer | The number of credential checks performed today. |
data.agents.total_checks | integer | The total number of credential checks performed by the agent. |
data.agents.domain | string | The domain the agent is attached to (Active Directory / Okta). |
data.agents.domains | array | The email domains handled by the agent. |
data.last_version | object | The latest available version for each installable agent type. |
data.last_version.ad | string | The latest Active Directory agent version. |
data.last_version.xsoar | string | The latest XSOAR agent version. |
Output Example
{"status":"active","message":"string","data":{"agents":[{}],"last_version":{"ad":"string","xsoar":"string"}}}
List All Baits
Retrieve all MokN baits along with their hosting details, certificate information, and alerting configuration.
Endpoint
- URL: /api/v1/baits/baits
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.include_deleted | boolean | Optional | Include deleted baits in the results. |
Input Example
{"parameters":{"include_deleted":false}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The list of baits. |
data.id | integer | The unique identifier of the bait. |
data.name | string | The display name of the bait. |
data.profile | string | The skin (login portal template) used by the bait. |
data.profile_short | string | The short label of the bait skin. |
data.category | string | The category of the bait, such as VPN, WEBMAIL or APPLICATION. |
data.domain | string | The domain name the bait is exposed on. |
data.hosting | string | Where the bait is hosted (azure, aws or on-premise). |
data.status | string | The current status of the bait (UP or DOWN). |
data.reason | string | The reason the bait is down, when status is DOWN. |
data.is_running | boolean | Whether the bait is running. |
data.is_deleted | boolean | Whether the bait has been deleted. |
data.is_data_kept | boolean | Whether the data collected by the bait is kept after deletion. |
data.public_ip | string | The public IP address of the bait. |
data.cloud_public_ip | string | The public IP address of the cloud instance hosting the bait. |
data.ip_proxy_in | string | The inbound proxy IP address for on-premise baits. |
data.ip_proxy_out | string | The outbound proxy IP address for on-premise baits. |
data.certificate | string | The state of the TLS certificate of the bait. |
data.expiration_date_cert | string | The expiration date of the TLS certificate. |
data.auto_renew | boolean | Whether the TLS certificate is automatically renewed. |
data.renew_server | string | The server used to renew the TLS certificate. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","profile":"string","profile_short":"string","category":"string","domain":"string","hosting":"string","status":"active","is_running":true,"is_deleted":true,"is_data_kept":true,"public_ip":"string","cloud_public_ip":"string","ip_proxy_in":"string","ip_proxy_out":"string"}]}
List Attacker Aggregates
Retrieve aggregated attacker data based on login attempts captured by MokN baits.
Endpoint
- URL: /api/v1/baits/attacks
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.page | integer | Optional | The page number to return. |
parameters.page_size | integer | Optional | The number of results per page. |
parameters.date_from | string | Optional | The start date for filtering attacker aggregates. |
parameters.date_to | string | Optional | The end date for filtering attacker aggregates. |
Input Example
{"parameters":{"page":1,"page_size":30}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | string | The attacker aggregates. |
Output Example
{"status":"active","message":"string","data":"string"}
List Available Skins
Retrieve a list of available login portal templates (skins) that can be used to create MokN baits.
Endpoint
- URL: /api/v1/baits/skins
- Method: GET
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The available skins. |
data.name | string | The name of the skin. |
Output Example
{"status":"active","message":"string","data":[{"name":"Example Name"}]}
List Certificate Authorities
Retrieve a list of certificate authorities available to issue TLS certificates for MokN baits.
Endpoint
- URL: /api/v1/baits/baits/certificate-authorities
- Method: GET
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The certificate authorities. |
data.name | string | The name of the certificate authority. |
Output Example
{"status":"active","message":"string","data":[{"name":"Example Name"}]}
Retrieve a Bait
Retrieve detailed information for a specific MokN bait using its unique bait ID.
Endpoint
- URL: /api/v1/baits/baits/{{bait_id}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.bait_id | integer | Required | The unique identifier of the bait. |
Input Example
{"path_parameters":{"bait_id":101}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The bait details. |
data.id | integer | The unique identifier of the bait. |
data.name | string | The display name of the bait. |
data.profile | string | The skin (login portal template) used by the bait. |
data.profile_short | string | The short label of the bait skin. |
data.category | string | The category of the bait, such as VPN, WEBMAIL or APPLICATION. |
data.domain | string | The domain name the bait is exposed on. |
data.hosting | string | Where the bait is hosted (azure, aws or on-premise). |
data.status | string | The current status of the bait (UP or DOWN). |
data.reason | string | The reason the bait is down, when status is DOWN. |
data.is_running | boolean | Whether the bait is running. |
data.is_deleted | boolean | Whether the bait has been deleted. |
data.is_data_kept | boolean | Whether the data collected by the bait is kept after deletion. |
data.public_ip | string | The public IP address of the bait. |
data.cloud_public_ip | string | The public IP address of the cloud instance hosting the bait. |
data.ip_proxy_in | string | The inbound proxy IP address for on-premise baits. |
data.ip_proxy_out | string | The outbound proxy IP address for on-premise baits. |
data.certificate | string | The state of the TLS certificate of the bait. |
data.expiration_date_cert | string | The expiration date of the TLS certificate. |
data.auto_renew | boolean | Whether the TLS certificate is automatically renewed. |
data.renew_server | string | The server used to renew the TLS certificate. |
Output Example
{"status":"active","message":"string","data":{"id":123,"name":"Example Name","profile":"string","profile_short":"string","category":"string","domain":"string","hosting":"string","status":"active","is_running":true,"is_deleted":true,"is_data_kept":true,"public_ip":"string","cloud_public_ip":"string","ip_proxy_in":"string","ip_proxy_out":"string"}}
Retrieve Agent Details
Retrieve detailed information for a specific MokN agent using its unique agent ID.
Endpoint
- URL: /api/v1/baits/agents/{{agent_id}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.export | boolean | Optional | Whether to export the agent details. |
parameters.new | boolean | Optional | Whether to retrieve the agent as new. |
path_parameters.agent_id | integer | Required | The unique identifier of the agent. |
Input Example
{"path_parameters":{"agent_id":12}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The agent details. |
data.id | integer | The unique identifier of the agent. |
data.name | string | The display name of the agent. |
data.agent_type | string | The identity provider type the agent connects to. |
data.is_alive | boolean | Whether the agent is currently alive and reporting to MokN. |
data.is_reachable | boolean | Whether the identity provider is reachable by the agent. |
data.last_seen | string | The date and time the agent last contacted MokN. |
data.date_created | string | The date and time the agent was created. |
data.server | string | The server the agent is installed on. |
data.version | string | The installed agent version. |
data.recipients | array | The email addresses notified about this agent. |
data.last_check_at | string | The date and time of the last credential check performed by the agent. |
data.today_checks | integer | The number of credential checks performed today. |
data.total_checks | integer | The total number of credential checks performed by the agent. |
data.domain | string | The domain the agent is attached to (Active Directory / Okta). |
data.domains | array | The email domains handled by the agent. |
Output Example
{"status":"active","message":"string","data":{"id":123,"name":"Example Name","agent_type":"string","is_alive":true,"is_reachable":true,"last_seen":"string","date_created":"string","server":"string","version":"string","recipients":["string"],"last_check_at":"string","today_checks":123,"total_checks":123,"domain":"string","domains":["string"]}}
Retrieve Agents Queue
Retrieve the list of login attempts that are pending, in progress, or completed in the agents' queue.
Endpoint
- URL: /api/v1/baits/agents/queue
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.bait_id | integer | Optional | The unique identifier of the bait. |
parameters.nb_checked | integer | Optional | The maximum number of already checked attempts to return. |
Input Example
{"parameters":{"nb_checked":50}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The agents queue. |
data.in_queue | array | The login attempts waiting in the queue. |
data.waiting_for_check | array | The login attempts waiting to be checked by an agent. |
data.checked | array | The login attempts already checked by an agent. |
Output Example
{"status":"active","message":"string","data":{"in_queue":[],"waiting_for_check":[],"checked":[]}}
Retrieve Average Time Between Two Attempts
Retrieve the average time between two login attempts across all baits and for each individual bait in MokN.
Endpoint
- URL: /api/v1/baits/dashboard/average
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.detail | boolean | Optional | Whether to include detailed results for each bait. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The average time per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.time | number | The average time between two login attempts. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","time":123}]}
Retrieve Bait Creation Status
Retrieve the current creation status of MokN baits being deployed.
Endpoint
- URL: /api/v1/baits/baits/status
- Method: GET
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | string | The bait creation status. |
Output Example
{"status":"active","message":"string","data":"string"}
Retrieve Monthly History
Retrieve the monthly history of login attempts for all baits and each individual bait in MokN.
Endpoint
- URL: /api/v1/baits/dashboard/monthly
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.detail | boolean | Optional | Whether to include detailed monthly history. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The monthly history per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.date | string | The month, in YYYY/MM format. |
data.count_attempts | integer | The number of login attempts. |
data.count_targeted | integer | The number of targeted attempts (existing accounts). |
data.count_leaked | integer | The number of targeted attempts with a password found in public leaks. |
data.count_identical | integer | The number of attempts using the real password. |
data.count_match_policy | integer | The number of attempts with a password matching the password policy. |
data.count_sprayed | integer | The number of password spraying attempts. |
data.count_variations | integer | The number of attempts using a variation of the real password. |
data.count_empty | integer | The number of attempts with an empty password. |
data.count_whitelist | integer | The number of whitelisted attempts. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","date":"2024-01-01T00:00:00Z","count_attempts":123,"count_targeted":123,"count_leaked":123,"count_identical":123,"count_match_policy":123,"count_sprayed":123,"count_variations":123,"count_empty":123,"count_whitelist":123}]}
Retrieve Monthly History Dates
Retrieve the earliest and latest months with available monthly login attempt history from MokN.
Endpoint
- URL: /api/v1/baits/dashboard/monthly/dates
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
Input Example
{"parameters":{"id":[101]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The available monthly history range. |
data.first_month | string | The first month with data, in YYYY/MM format. |
data.last_month | string | The last month with data, in YYYY/MM format. |
Output Example
{"status":"active","message":"string","data":{"first_month":"string","last_month":"string"}}
Retrieve Short List of Agents
Retrieve a concise list of all MokN agents, including their IDs and names.
Endpoint
- URL: /api/v1/baits/agents/short
- Method: GET
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The short list of agents. |
data.id | integer | The unique identifier. |
data.name | string | The display name. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name"}]}
Retrieve Short List of Baits
Retrieve a concise list of all MokN baits, including their IDs and names.
Endpoint
- URL: /api/v1/baits/baits/short
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.include_deleted | boolean | Optional | Include deleted baits in the results. |
Input Example
{"parameters":{"include_deleted":false}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The short list of baits. |
data.id | integer | The unique identifier. |
data.name | string | The display name. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name"}]}
Retrieve Targeting Countries Data
Retrieve the top countries of origin for login attempts across all baits and for each individual bait.
Endpoint
- URL: /api/v1/baits/dashboard/top/countries
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.detail | boolean | Optional | Whether to include country-level details in the results. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The top countries per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.details | array | The countries sorted by number of attempts. |
data.details.country | string | The name of the country. |
data.details.country_code | string | The ISO country code. |
data.details.total_attempts | integer | The number of login attempts from this country. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","details":[]}]}
Retrieve Threat Level
Retrieve the overall threat level for all baits and individual threat levels for each bait in MokN.
Endpoint
- URL: /api/v1/baits/dashboard/threat
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.detail | boolean | Optional | Whether to include detailed threat-level results. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The threat level per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.threat_level | string | The threat level (Low, Medium, High or Critical). |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","threat_level":"string"}]}
Retrieve Top Passwords
Retrieve the most frequently used passwords in login attempts across all baits and for each individual bait.
Endpoint
- URL: /api/v1/baits/dashboard/top/passwords
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.limit | integer | Optional | The maximum number of entries returned for each bait. |
parameters.detail | boolean | Optional | Whether to include detailed password information. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","limit":10,"detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The top passwords per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.passwords | object | The most used passwords, mapped to their number of attempts. |
data.targeted_passwords | object | The most used passwords on existing accounts, mapped to their number of attempts. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","passwords":{},"targeted_passwords":{}}]}
Retrieve Top Usernames
Retrieve the most frequently used usernames in login attempts across all baits and for each individual bait.
Endpoint
- URL: /api/v1/baits/dashboard/top/logins
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.limit | integer | Optional | The maximum number of entries returned for each bait. |
parameters.detail | boolean | Optional | Whether to include detailed results. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","limit":10,"detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The top usernames per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.users | object | The most used usernames, mapped to their number of attempts. |
data.targeted_users | object | The most targeted existing accounts, mapped to their number of attempts. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","users":{},"targeted_users":{}}]}
Retrieve Unique Targeted Accounts Data
Retrieve the count of unique targeted accounts across all baits and for each individual bait in MokN.
Endpoint
- URL: /api/v1/baits/dashboard/unique
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.id | array | Optional | Restrict the results to these bait IDs. When omitted, all baits are returned. |
parameters.start_month | string | Optional | The first month of the period, in YYYY/MM format. |
parameters.end_month | string | Optional | The last month of the period, in YYYY/MM format. |
parameters.detail | boolean | Optional | Whether to include detailed results for each bait. |
Input Example
{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | array | The unique targeted accounts per bait. |
data.id | integer | The bait ID. Null for the aggregate entry covering all baits. |
data.name | string | The bait name, or "All baits" for the aggregate entry. |
data.unique | integer | The number of unique targeted accounts. |
Output Example
{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","unique":123}]}
Update an Agent
Update the configuration of an existing MokN agent using the specified agent ID and new settings.
Endpoint
- URL: /api/v1/baits/agents/{{agent_id}}
- Method: PUT
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.agent_id | integer | Required | The unique identifier of the agent. |
name | string | Optional | The display name of the agent. |
agent_type | string | Optional | The identity provider type the agent connects to. |
recipients | array | Optional | The email addresses notified about this agent. |
valid_username | string | Optional | A valid account username used to monitor the agent. Must be set together with Valid Password. |
valid_password | string | Optional | The password of the monitoring account. |
domain | string | Optional | The domain of the identity provider (Active Directory and Okta agents). |
domains | array | Optional | The email domains handled by the agent (Entra ID, Okta and Google agents). |
domain_controller | string | Optional | The host of the domain controller (Active Directory agents). |
search_base | string | Optional | The LDAP search scope (Active Directory agents). |
lockout_threshold | integer | Optional | The account lockout threshold, between 0 and 9999 (Active Directory agents). |
tls_ssl | boolean | Optional | Whether LDAP connections use TLS/SSL (Active Directory agents). |
tls_ssl_verify | boolean | Optional | Whether the LDAP TLS certificate is verified (Active Directory agents). |
attributes | array | Optional | The directory attributes used to match usernames (Active Directory and Google agents). |
tenant_id | string | Optional | The Microsoft Entra ID tenant ID (Entra ID agents). |
client_id | string | Optional | The Microsoft Entra ID application client ID (Entra ID agents). |
client_secret | string | Optional | The Microsoft Entra ID application client secret value, not the secret ID (Entra ID agents). |
is_fast_setup | boolean | Optional | Whether the Entra ID fast setup is used (Entra ID agents). |
ssws_token | string | Optional | The Okta API token (Okta agents). |
tls_client_certificate | string | Optional | The PEM-encoded TLS client certificate (Google agents). |
tls_client_private_key | string | Optional | The PEM-encoded TLS client private key (Google agents). |
Input Example
{"json_body":{"name":"Corporate AD agent","agent_type":"AgentAD","recipients":["[email protected]"],"domain":"corp.example.com","domain_controller":"dc01.corp.example.com","search_base":"DC=corp,DC=example,DC=com","lockout_threshold":0,"tls_ssl":true,"tls_ssl_verify":false,"attributes":["mail","samaccountname","userprincipalname"]},"path_parameters":{"agent_id":12}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | The HTTP status code of the response. |
reason | string | The HTTP reason phrase of the response. |
status | string | The status of the request (success or error). |
message | string | A message describing the result of the request. |
data | object | The agent details. |
data.id | integer | The unique identifier of the agent. |
data.name | string | The display name of the agent. |
data.agent_type | string | The identity provider type the agent connects to. |
data.is_alive | boolean | Whether the agent is currently alive and reporting to MokN. |
data.is_reachable | boolean | Whether the identity provider is reachable by the agent. |
data.last_seen | string | The date and time the agent last contacted MokN. |
data.date_created | string | The date and time the agent was created. |
data.server | string | The server the agent is installed on. |
data.version | string | The installed agent version. |
data.recipients | array | The email addresses notified about this agent. |
data.last_check_at | string | The date and time of the last credential check performed by the agent. |
data.today_checks | integer | The number of credential checks performed today. |
data.total_checks | integer | The total number of credential checks performed by the agent. |
data.domain | string | The domain the agent is attached to (Active Directory / Okta). |
data.domains | array | The email domains handled by the agent. |
Output Example
{"status":"active","message":"string","data":{"id":123,"name":"Example Name","agent_type":"string","is_alive":true,"is_reachable":true,"last_seen":"string","date_created":"string","server":"string","version":"string","recipients":["string"],"last_check_at":"string","today_checks":123,"total_checks":123,"domain":"string","domains":["string"]}}
Response Headers
Header | Description | Example |
|---|---|---|
Content-Type | The media type of the resource | application/json |
Date | The date and time at which the message was originated | Thu, 01 Jan 2024 00:00:00 GMT |