Nightfall AI

​

Pre-requisites

An active Nightfall tenant at app.nightfall.ai and System Administrator role permission to create API keys.

Relevant Nightfall apps and policies configured if you expect DLP violations from those apps.

Access to the AirMDR organization where you will create the connection and Network access from AirMDR, or its selected Remote Agent, to the Nightfall API over HTTPS.

​

Setup Steps

read -rsp "Nightfall API key: " NIGHTFALL_API_KEY
printf '\n'

curl --silent --show-error --get \
  'https://api.nightfall.ai/dlp/v1/violations' \
  --data-urlencode 'limit=1' \
  --header "Authorization: Bearer ${NIGHTFALL_API_KEY}" \
  --header 'Accept: application/json' \
  --output /dev/null \
  --write-out 'HTTP %{http_code}\n'

unset NIGHTFALL_API_KEY

​

Configure Nightfall AI in AirMDR Integrations Dashboard

1. Navigate to AirMDR, provide the credentials and click Login
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
3. Use the search option, enter the keyword “Nightfall AI”, select the Connections tab, and click + New Connection button.
4. Use the following values in the AirMDR integration configuration screen:

   Field	What to enter
   Instance *	A recognizable name for this connection, such as Nightfall-Production. This is an AirMDR label, not the Nightfall API URL.
   Organization	Select the AirMDR organization that should own the connection.
   Description *	Briefly identify the Nightfall tenant and purpose, such as Production Nightfall security events.
   Api_key *	Paste the complete Nightfall key copied in step 4.1. Enter the key value only; do not prefix it with Bearer .

   Expand Advanced Configuration if required. (Optional)

   Field	Guidance
   Remote Agent	For a publicly reachable Nightfall cloud API, leave this unselected unless your AirMDR deployment requires traffic through a particular AirMDR Remote Agent. If required, select an agent that can reach api.nightfall.ai over HTTPS and is supported for this integration in your AirMDR environment. This field does not refer to the Nightfall endpoint agent.
   Expiry	If the Nightfall key has an actual expiration date in your tenant, enter that date. Otherwise, leave the field unset unless your team uses it to track a planned rotation date. A date entered in AirMDR does not set or renew the Nightfall key’s lifetime. Check your AirMDR environment’s behavior before relying on this field for alerts or automatic disabling.

5. Click Save.

​

Skills provided by this Integration

GET https://api.nightfall.ai/apps/v1/endpoint/devices

POST https://api.nightfall.ai/mcp

​

Additional Information

🛑 Security & Access Best Practices

✅ Do

• Create a dedicated Nightfall API key for the AirMDR integration.
• Use a descriptive key name, such as AirMDR-Nightfall-Production.
• Store the API key only in the AirMDR credential field or an approved secrets manager.
• Restrict access to the AirMDR connection to authorized administrators and security personnel.
• Review the selected Nightfall MCP tool before running the Nightfall MCP server skill.
• Require confirmation before executing remediation or policy-changing actions.
• Check a violation’s possibleActions value before applying a remediation action.
• Use read-only skills for investigation before executing a state-changing skill.
• Rotate the API key according to your organization’s credential-rotation policy.
• Update the Expiry field in AirMDR when the key has an expiration or planned rotation date.
• Test a replacement key in AirMDR before deleting the existing key.
• Delete and replace the key immediately if it is exposed or suspected to be compromised.
• Allow outbound HTTPS access to api.nightfall.ai only from the approved AirMDR execution environment or Remote Agent.
• Review Nightfall and AirMDR activity records regularly for unexpected integration actions.

❌ Don’t

• Do not share the API key through email, chat, support tickets, or documentation.
• Do not include the API key in screenshots, application logs, source code, scripts, or Git repositories.
• Do not reuse the AirMDR integration key for unrelated applications or automation.
• Do not add the Bearer prefix when entering the key in AirMDR’s Api_key field.
• Do not assume that a Nightfall API key is limited to read-only operations.
• Do not run the Nightfall MCP server skill without checking whether the selected tool changes data.
• Do not perform delete, quarantine, redact, restrict-access, or policy-scope actions without reviewing their impact.
• Do not repeat a notification or ticket-creation action automatically; repeated calls can send another notification or create another ticket.
• Do not assume that AirMDR’s Expiry field changes or renews the Nightfall key.
• Do not delete the old Nightfall key until the replacement connection has been tested successfully.
• Do not select an AirMDR Remote Agent unless it is approved, active, and able to reach the Nightfall API.
• Do not confuse the AirMDR Remote Agent with the Nightfall endpoint agent.
• Do not expose sensitive violation findings in unrestricted logs or troubleshooting records.
• Do not treat an empty API result as an authentication failure without checking the policy scope, time range, and available Nightfall events.

👉 Support & Maintenance

• 📧 Contact AirMDR Support through your designated support channel.
• 🔁 Rotate credentials regularly. Recommended cadence: As per internal security policy
• 🔄 Reconnect in AirMDR immediately when API Keys are changed.
  Revoke the previous credential after confirming all consumers have migrated.

🛑 Data Flow & Security

The diagram describes the expected integration flow; the records and actions AirMDR uses depend on its Nightfall skills. Nightfall’s DLP API can provide violation records, including related metadata and findings through documented endpoints. Findings may contain sensitive information, so restrict access to both systems accordingly. 

Security item	Guidance
Data in transit	Nightfall requires HTTPS for API requests. Permit outbound TCP 443 to api.nightfall.ai from the AirMDR execution environment or selected Remote Agent.
Nightfall data at rest	Nightfall states that its databases are encrypted at rest. Consult AirMDR’s security documentation for the storage controls applicable to the AirMDR credential and any data AirMDR retains.
API endpoint	The read-only validation example uses https://api.nightfall.ai/dlp/v1/violations. Other supported Nightfall product areas use their own documented API paths; do not use the validation URL as a substitute for AirMDR’s integration configuration.
Credentials	Provide the API key through the AirMDR secret field. Never place it in screenshots, tickets, logs, or a shared code repository.

🔄 Monitoring & Logs

• In AirMDR: Review the connection status and the execution results for Nightfall skills in your AirMDR environment. Record the instance name, operation, time, and HTTP status when investigating a failure. The exact log location and field names depend on your AirMDR deployment.
• In Nightfall: Review the dashboard for the expected events and open an event’s Event logs to see its activity history. The API also documents an activity feed for an individual violation. Event activity is useful for checking whether data exists; it is not a replacement for AirMDR connection logs. 
• Recommended application log levels: Use INFO for successful connection or skill execution, WARN for recoverable authentication or rate-limit problems, and ERROR for failed executions requiring investigation. Omit API keys and sensitive findings from logs.

Illustrative AirMDR log messages — examples of useful information to record, not a claim about AirMDR’s actual log format:

INFO  integration=nightfall instance=Nightfall-Production operation=list_violations http_status=200
WARN  integration=nightfall instance=Nightfall-Production operation=list_violations http_status=429
ERROR integration=nightfall instance=Nightfall-Production operation=list_violations http_status

🧰 Error Handling

Symptom	Likely cause	Recovery
401 Unauthorized	Missing, incorrectly pasted, expired, or revoked key.	Check for spaces or a truncated value. Confirm the key’s status in Nightfall. Replace it in AirMDR if needed; do not type Bearer into the Api_key field.
Connection or TLS failure	The AirMDR execution environment or selected Remote Agent cannot reach the Nightfall API over HTTPS.	Check outbound access to api.nightfall.ai on TCP 443, DNS resolution, and any applicable proxy or certificate configuration.
200 response, but no expected violations	No matching event, app connection, policy scope, or time range; or the queried API does not cover the expected data source.	Verify the event in the Nightfall dashboard, check app and policy scope, widen the time range, and confirm that the relevant AirMDR skill supports that data source.
429 Too Many Requests	API rate limit or quota exceeded.	Reduce request frequency and retry after the interval in the Retry-After response header.
One product area works, another fails	Different Nightfall feature availability or access requirements.	Confirm the subscription and API access for the affected product area, then check which AirMDR skill made the request. Do not interpret this as proof that the entire connection has failed.