> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recorded Future

> Connect Serval to Recorded Future so workflows can enrich indicators, triage alerts, manage watchlists, and check identity exposures with a single API token.

## About Recorded Future

Recorded Future is a threat-intelligence platform that scores and contextualizes indicators of compromise, publishes alerts and analyst research, and tracks exposed credentials. Serval connects to the Recorded Future API at api.recordedfuture.com with a single API token, and that one connection covers the enrichment, alerting, list, analyst-note, identity, and SOAR APIs. Everything happens on demand from workflows - there is nothing to install on the Recorded Future side.

**Authentication:** API token - you provide a Recorded Future API token, and Serval sends it in the X-RFToken header on every request it makes on your behalf. Serval only ever sends the token to api.recordedfuture.com. Adjacent Recorded Future products with separate tokens, such as the Sandbox and Attack Surface Intelligence, aren't part of this integration.

**Data sync:** On-demand only. There is no background sync and no entity ingestion - Serval reads and writes Recorded Future data only when a workflow runs.

## What the Recorded Future integration enables

| Capability                 | Description                                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Indicator enrichment       | Look up risk scores, triggered risk rules, and evidence for IPs, domains, URLs, file hashes, and CVEs.                                                        |
| Bulk enrichment and triage | Enrich up to 1,000 indicators in one SOAR API call, or get a one-call risky-or-not verdict against a triage context such as phishing or C2.                   |
| Alert triage               | Search classic alerts, fetch the hits that triggered them, and update status, assignee, and notes.                                                            |
| Playbook alerts            | Search playbook alerts across categories such as domain abuse and novel identity exposures, read category details, and update status, priority, and assignee. |
| Watchlist management       | Create custom lists and add or remove the entities Recorded Future should monitor.                                                                            |
| Identity exposure checks   | Search leaked credentials for your watched domains, look up specific users, and check whether passwords appear in breach data.                                |
| Analyst notes              | Search and read Insikt Group and enterprise analyst notes, or publish your own.                                                                               |
| Detection rules            | Search Sigma, YARA, Snort, Nuclei, and Suricata rules linked to threats you care about.                                                                       |
| Entity resolution          | Resolve free-text names such as a malware family or vendor to Recorded Future entity IDs.                                                                     |
| AI endpoint discovery      | When authoring workflows, Serval AI can discover the curated Recorded Future endpoints and their parameters.                                                  |

The integration covers a curated subset of the [Recorded Future APIs](https://api.recordedfuture.com/index.html) - Connect enrichment and search, Alert, Playbook Alert, List, Analyst Note, Entity Match, Detection Rule, Identity, and SOAR.

## Get your credentials

You need a Recorded Future API token. Tokens are generated in the Recorded Future portal by an Enterprise Administrator, and each token carries the API entitlements of your licensed modules - the same token works across all the APIs your subscription covers. Recorded Future's guide is [Requesting API Tokens](https://support.recordedfuture.com/hc/en-us/articles/4411077373587-Requesting-API-Tokens) (customer login required).

<Steps>
  <Step title="Log in to the Recorded Future portal">
    Sign in at [app.recordedfuture.com](https://app.recordedfuture.com/) with an Enterprise Administrator account.
  </Step>

  <Step title="Open API access">
    Open the menu in the upper right corner, select **User Settings**, then select **API Access**.
  </Step>

  <Step title="Generate the token">
    Select **Generate New API Token**, give it a descriptive name such as Serval, and choose the API services it should cover.
  </Step>

  <Step title="Copy the token">
    Copy and save the token right away.
  </Step>
</Steps>

<Warning>
  Only Enterprise Administrators can generate API tokens. If you aren't an administrator, ask one to generate the token for you, or submit an integration support ticket to Recorded Future specifying which API offering you need.
</Warning>

<Tip>
  Endpoint access is baked into the token from your licensed modules - for example, vulnerability enrichment needs the Vulnerability Intelligence module and identity lookups need Identity Intelligence. If your organization adds a module later, regenerate the token to pick up the new entitlements.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the Recorded Future connection form">
    In Serval, add a new Recorded Future connection.
  </Step>

  <Step title="Enter the API Token (required)">
    Paste the token into the **API Token** password field ("Recorded Future API token, generated by an Enterprise Administrator in the Recorded Future portal under User Settings -> API Access."). Leaving it empty shows "This field is required".
  </Step>

  <Step title="Submit the form">
    Click **Submit**. If installation fails, the form shows "Failed to install integration" with details appended when available. Serval stores the token securely and attaches it to every Recorded Future request your workflows make.
  </Step>
</Steps>

<Note>
  When you open the connection's settings later, the token appears masked - bullet characters plus its last 4 characters. To rotate it, replace the masked value with the complete new token and save.
</Note>

## Verifying the connection

The integration ships five built-in health checks:

1. **Test Recorded Future Connection** - searches your custom lists, which every module is entitled to. Success reports "Successfully connected to the Recorded Future API". Failure reports "Unable to connect to Recorded Future. Verify the API token is valid and hasn't expired or been revoked."
2. **Check Enrichment API Access** - lists IP risk rules, a static metadata call with no enrichment-quota cost. Failure normally means the token's modules don't include SecOps, Threat, or Brand Intelligence.
3. **Check Alert API Access** - fetches a single alert rule. Alerts are available on every module except SecOps Intelligence.
4. **Check Playbook Alert API Access** - fetches the playbook alert category and status enumerations.
5. **Check SOAR Bulk-Enrichment Access** - lists the static triage contexts. Failure normally means the token's modules don't include SecOps or Threat Intelligence.

Only the first check indicates a broken connection outright. If it passes while a later check fails, the token is valid but its modules don't cover that API - the failure message names the modules that unlock it.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="A health check fails even though the token is valid">
    Every Recorded Future API is gated by module entitlements that are baked into the token at generation time. A 403 with "Missing API privileges" means the token's modules don't cover that endpoint - it isn't an authentication failure. If your organization licensed a new module after the token was created, regenerate the token in the Recorded Future portal.
  </Accordion>

  <Accordion title="Requests suddenly return 401">
    A 401 means the token itself is invalid - expired, revoked, or mistyped. Generate a fresh token in the Recorded Future portal and update the connection.
  </Accordion>

  <Accordion title="Daily API quota and rate limiting">
    Standard Recorded Future API subscriptions include 5,000 API calls per day across all the APIs, and bursts of traffic can return HTTP 429. For enriching many indicators, prefer one SOAR bulk-enrichment call (up to 1,000 indicators) over a loop of per-indicator lookups - it's one call toward the quota and returns risk scores for the whole batch.
  </Accordion>

  <Accordion title="URL enrichment needs no manual encoding">
    The URL enrichment endpoint takes the full URL as a path parameter. Serval URL-encodes path parameters automatically, so pass the raw URL as the id - encoding it yourself produces a double-encoded lookup that misses.
  </Accordion>

  <Accordion title="Search results stop at 1,000">
    The enrichment search endpoints and classic alert search cap limit plus from at 1,000 - deeper pages aren't reachable. Playbook alert, analyst note, and identity searches use cursor offsets instead and aren't capped this way.
  </Accordion>

  <Accordion title="Sandbox and Attack Surface Intelligence are separate products">
    Recorded Future Sandbox (sandbox.recordedfuture.com) and Attack Surface Intelligence (served from api.securitytrails.com) use different hosts and different tokens. This integration only calls api.recordedfuture.com, so those products are out of scope.
  </Accordion>

  <Accordion title="Binary downloads are not included">
    Endpoints that return raw files - alert screenshot images, analyst-note attachments, and bulk risk-list downloads - are excluded from the endpoint catalog because Serval's request pipeline is JSON-based. Risk data is available through the enrichment and SOAR endpoints instead.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Recorded Future integration.