.png)
BitSight Integration Guide
Integrate BitSight security ratings, risk vectors, companies, portfolios, and findings with enterprise systems through REST API workflows and scheduled synchronization.
BitSight integration options at a glance
BitSight’s primary programmatic integration mechanism is its REST API, which provides access to companies, ratings, rating history where available, risk vectors, findings, portfolios, and related security-risk data. API-key authentication commonly uses the X-Api-Key request header. BitSight collection endpoints support retrieval of multiple resources, but a separate bulk or asynchronous export API was not confirmed. General-purpose webhooks, outbound callbacks, GraphQL, SOAP, file APIs, and direct database access were also not confirmed. Martini can schedule incremental polling, paginate responses, map BitSight objects into canonical models, persist checkpoints, apply business rules, and expose a controlled internal REST API.
| Integration point | Supported by BitSight? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | BitSight’s primary API surface retrieves Companies, Ratings, Risk Vectors, Findings, Portfolios, and related security-rating data through the BitSight API service. | Martini can consume the BitSight REST API from workflows, paginate collections, apply filters, transform responses, and expose normalized results through a Martini API. |
| Authentication | Yes | The BitSight API uses API-key authentication, commonly supplied in the X-Api-Key request header over HTTPS. | Martini can store the API key in Secrets Management and inject it into outbound requests without embedding it in workflow logic or logs. |
| Bulk / async / batch APIs | Limited | Collection endpoints can return multiple Companies, Ratings, Findings, or related resources, but a separate bulk or asynchronous export API was not confirmed. | Martini can process paginated collections, use bounded concurrency, checkpoint progress, and separate high-volume synchronization workflows. |
| Scheduled synchronization | Yes | Scheduled polling is the recommended approach when a general BitSight webhook or callback mechanism is unavailable or not confirmed. | Martini Scheduler Triggers can start incremental workflows that retrieve updated data, compare state, and emit internal downstream actions. |
| Webhooks / outbound callbacks | Not confirmed | A general-purpose BitSight webhook or outbound callback API was not confirmed. Product-specific notifications should be verified separately. | Martini can receive webhooks when a customer has a confirmed BitSight callback mechanism, but polling should be the default design. |
| GraphQL APIs | Not confirmed | No official BitSight GraphQL API was confirmed in the reviewed material. | Martini can consume GraphQL APIs generally, but a BitSight GraphQL integration should not be assumed. |
| SOAP APIs | Not confirmed | No official BitSight SOAP API was confirmed. | Martini supports SOAP integrations generally, but BitSight-specific SOAP access was not established. |
| File / attachment APIs | Not confirmed | No general BitSight file-import, file-export, report-download, or attachment API was confirmed. | Martini can process files from supported endpoints when an officially documented BitSight export is available, but the REST API is the supported default. |
| Database / analytics access | No | Direct customer database, JDBC, and general-purpose analytics database access were not confirmed for BitSight. | Martini should use the BitSight API or an officially documented export rather than attempting direct database access. |
How BitSight exposes data and business events
BitSight REST APIs
BitSight’s REST API is the principal documented integration surface for retrieving Companies, Ratings, Risk Vectors, Findings, Portfolios, and related security-rating data. Endpoint availability and fields depend on account entitlement and enabled products.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates with the BitSight API key, calls the relevant REST endpoint, follows pagination and supported filters, validates the response, maps it to a canonical model, and writes or serves the result to downstream systems.
Implementation sequence
Scheduled BitSight synchronization
Because a general BitSight webhook or outbound callback mechanism was not confirmed, scheduled polling is the safer general-purpose change-detection pattern. Date, update-time, status, or other endpoint filters should be used where available.
Martini implementation pattern
Martini implementation pattern: a Scheduler Trigger starts an incremental workflow, retrieves current BitSight data, compares it with durable local state, and creates internal downstream actions only for new or materially changed objects.
Implementation sequence
BitSight collection processing
BitSight collection endpoints support retrieval of multiple resources, but a separate bulk or asynchronous export API was not confirmed. Large portfolios and finding sets therefore require careful pagination and checkpointing.
Martini implementation pattern
Martini implementation pattern: the workflow processes pages in bounded batches, records the last successfully handled page or object, applies retry and throttling controls, and routes failed items for targeted replay instead of restarting the entire portfolio.
Implementation sequence
Common BitSight integration patterns
Pattern 1: Synchronize security ratings to a risk register
When to use this pattern
Use this pattern when security, procurement, or governance teams need a normalized view of BitSight Companies, Ratings, and Risk Vectors in an operational database or risk application. It is suited to recurring portfolio synchronization where no general webhook mechanism is available.
Integration direction
Example Mapping
| BitSight Field | Canonical Field | Target Field |
|---|---|---|
| company_guid | externalCompanyId | vendor.external_id |
| rating | securityRating | risk.rating |
| risk_vectors | riskVectorSummary | risk.vector_summary |
| observed_at | sourceObservedAt | risk.observed_at |
Martini implementation pattern
A scheduled Martini workflow retrieves portfolio-scoped data with endpoint-supported filters and pagination, validates the response, maps Companies, Ratings, and Risk Vectors into a canonical risk model, and upserts the result. It stores checkpoints and source identifiers, applies rating-change rules, and retries transient failures without duplicating records.
Martini capabilities used
- workflows
- scheduled triggers
- API consumption
- data mapping
- business rules
- SQL persistence
- error handling
Pattern 2: Route findings to remediation management
When to use this pattern
Use this pattern when security or engineering teams need actionable BitSight Findings represented as issues or remediation tasks. The workflow can prioritize high-severity findings, preserve traceability, and close or update downstream items only when approved lifecycle rules are met.
Integration direction
Example Mapping
| BitSight Field | Canonical Field | Target Field |
|---|---|---|
| finding_id | sourceFindingId | u_bitsight_finding_id |
| severity | priority | priority |
| status | findingStatus | state |
| company_guid | affectedCompanyId | cmdb_ci.external_id |
Martini implementation pattern
Martini polls filtered Findings, determines whether each finding is new or materially changed, and maps it to a ServiceNow remediation record. Idempotency keys combine stable BitSight identifiers with relevant status or change values; transient API failures are retried, while authorization and validation errors are quarantined for review.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- idempotency
- error handling
- retry handling
Pattern 3: Expose a controlled BitSight risk API
When to use this pattern
Use this pattern when internal applications need BitSight data but should not hold BitSight credentials or depend directly on BitSight response structures. The façade can aggregate current or persisted data and enforce portfolio-level access rules.
Integration direction
Example Mapping
| BitSight Field | Canonical Field | Target Field |
|---|---|---|
| company_guid | companyId | company.id |
| rating | currentRating | security.rating |
| risk_vectors | riskCategories | security.riskVectors |
| findings | openFindings | security.findings |
Martini implementation pattern
Martini exposes a secured REST API that validates the caller, applies portfolio and data-minimization rules, retrieves or reads persisted BitSight data, and returns a stable internal schema. Reusable workflows can cache results, aggregate related objects, and isolate consumers from BitSight schema changes while protecting the API key.
Martini capabilities used
- API exposure
- workflows
- API consumption
- data transformation
- authorization
- business rules
- error handling
Pattern 4: Alert on meaningful rating changes
When to use this pattern
Use this pattern when security or executive teams need notifications for deterioration, improvement, or risk-vector changes. It is appropriate for scheduled comparison because general-purpose BitSight outbound callbacks were not confirmed.
Integration direction
Example Mapping
| BitSight Field | Canonical Field | Target Field |
|---|---|---|
| company_guid | companyId | vendor_id |
| previous_rating | priorRating | custom_data.previous_rating |
| rating | currentRating | custom_data.current_rating |
| change_type | riskChangeType | event_type |
Martini implementation pattern
A scheduled Martini workflow retrieves current Ratings and Risk Vectors, compares them with stored state, applies thresholds for meaningful change, and emits an idempotent event to the target notification or security platform. The workflow persists state only after successful downstream handling and retries temporary failures with bounded backoff.
Martini capabilities used
- scheduled triggers
- API consumption
- state comparison
- business rules
- data mapping
- idempotency
- retry handling
Applications commonly integrated with BitSight
BitSight data can be routed to enterprise applications that manage third-party risk, remediation, reporting, security operations, or account governance. These are integration patterns rather than claims of native BitSight connectors; endpoint access and target-system licensing should be confirmed for each deployment.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| ServiceNow | Create or update third-party risk, security, or remediation records from BitSight ratings and findings. | BitSight → Martini → ServiceNow | A scheduled Martini workflow retrieves changed Companies, Ratings, and Findings, maps stable BitSight identifiers into ServiceNow records, applies severity and lifecycle rules, and retries transient API failures. |
| Salesforce | Add external security-rating context to account or customer assurance workflows. | BitSight → Martini → Salesforce | Martini polls BitSight Companies and Ratings, matches company identifiers to Salesforce accounts using governed matching rules, and upserts only the fields required by sales or assurance users. |
| Jira | Create or update engineering and security issues for actionable BitSight Findings. | BitSight → Martini → Jira | A Martini workflow filters new or materially changed findings, maps severity and company context to Jira issue fields, preserves the BitSight finding identifier, and prevents duplicate issues with an idempotency key. |
| RSA Archer | Synchronize BitSight ratings and third-party risk information with governance, risk, and compliance records. | BitSight → Martini → RSA Archer | Martini retrieves portfolio and rating data, transforms it to the Archer assessment model, validates required fields, and records rejected objects for targeted replay. |
| OneTrust | Enrich vendor-risk records and third-party assessments with external BitSight security ratings. | BitSight → Martini → OneTrust | A scheduled workflow matches BitSight Companies to OneTrust vendor records, updates normalized rating attributes, and routes ambiguous matches to an exception queue. |
| Splunk | Ingest rating and finding changes for security reporting, correlation, and operational monitoring. | BitSight → Martini → Splunk | Martini detects changes through incremental polling, converts them to a stable event schema, and sends only new or changed events to the receiving ingestion API with retry handling. |
| Microsoft Sentinel | Provide BitSight risk context to security operations and prioritization workflows. | BitSight → Martini → Microsoft Sentinel | Martini maps BitSight risk changes to the target ingestion schema, applies portfolio and severity filters, and logs downstream acknowledgements for replay and auditability. |
How to build a BitSight integration in Martini
Objective
Establish BitSight API access with an appropriately scoped API key and protect the credential throughout the integration lifecycle.
Instructions in Martini
- Create or obtain the BitSight API key with only the required account and portfolio permissions.
- Store the key in Martini Secrets Management.
- Configure HTTPS requests with the X-Api-Key header.
- Keep credentials out of workflow parameters, logs, and error payloads.
Objective
Select scheduled polling as the default trigger because a general BitSight webhook or callback mechanism was not confirmed.
Instructions in Martini
- Use a Scheduler Trigger for recurring synchronization.
- Define separate schedules for high-priority changes and full-portfolio retrieval where appropriate.
- Use a confirmed callback only for a product-specific BitSight notification mechanism.
Objective
Call the BitSight REST API for the Companies, Ratings, Risk Vectors, Findings, or Portfolios required by the use case.
Instructions in Martini
- Use endpoint-supported filters, date ranges, status values, and page-size controls.
- Process collections through pagination rather than assuming the first response is complete.
- Store source identifiers and retrieval timestamps.
Objective
Coordinate retrieval, state comparison, transformation, target writes, and checkpoint updates in a maintainable Martini workflow.
Instructions in Martini
- Separate company, rating, risk-vector, and finding synchronization where their volumes or schedules differ.
- Persist a durable checkpoint after successful processing.
- Route failed objects to a replayable error path instead of restarting the entire portfolio.
Objective
Convert BitSight responses into stable canonical and target-system models while preserving traceability.
Instructions in Martini
- Map company GUIDs, finding identifiers, ratings, statuses, severities, and risk-vector values explicitly.
- Validate required fields and distinguish Ratings from Findings in downstream schemas.
- Preserve selected source payload data where auditability is required.
Objective
Apply business rules for prioritization, deduplication, access scope, and meaningful changes before writing to target systems.
Instructions in Martini
- Use deterministic idempotency keys to prevent duplicate issues or alerts.
- Route high-severity Findings according to approved remediation rules.
- Upsert target records and retain BitSight identifiers for traceability.
- Expose a controlled Martini REST API when internal consumers need normalized BitSight data.
Common BitSight data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Companies | Identify organizations monitored by BitSight and provide company metadata, commonly using a company GUID. | ServiceNow, Salesforce, OneTrust, RSA Archer | Martini retrieves and paginates Companies, validates identifiers, applies matching rules, and maps them to downstream vendor or account models. |
| Ratings | Represent a company’s security rating and related rating information or history where available. | ServiceNow, Salesforce, RSA Archer, Microsoft Sentinel | Martini stores the latest rating and reporting metadata, compares it with prior state, and emits changes only when business rules identify a meaningful update. |
| Risk Vectors | Explain or analyze categories contributing to a company’s security risk profile. | RSA Archer, OneTrust, Splunk, Microsoft Sentinel | Martini normalizes risk-vector values, preserves source context where required, and maps categories to target-specific risk fields. |
| Findings | Capture detailed security observations or issues associated with a company. | ServiceNow, Jira, Splunk, Microsoft Sentinel | Martini retrieves Findings using supported filters and pagination, applies severity and status rules, and uses stable identifiers to prevent duplicate remediation records. |
| Portfolios | Group Companies for monitoring, reporting, and third-party risk management. | ServiceNow, RSA Archer, OneTrust, internal risk databases | Martini uses portfolio membership to scope synchronization, route records, enforce access rules, and control which companies are exposed to downstream applications. |
Authentication and security considerations
API-key authentication
BitSight’s confirmed API authentication mechanism uses an API key, commonly supplied in the X-Api-Key request header over HTTPS. OAuth 2.0, JWT bearer authentication, and granular OAuth scopes were not confirmed for the reviewed BitSight API.
Credential protection
- Store the BitSight API key in Martini Secrets Management.
- Use credentials with only the permissions required for the relevant companies, portfolios, ratings, or findings.
- Do not expose the key in workflow parameters, logs, error responses, or downstream payloads.
- Restrict any Martini API that exposes BitSight-derived information and apply data minimization.
Operational considerations for BitSight integrations
Pagination and rate limits
BitSight portfolios and finding collections can be large. Use endpoint-supported pagination, stable ordering where available, bounded concurrency, and durable checkpoints. Do not hard-code rate limits unless they are confirmed for the customer’s plan; handle HTTP 429 responses with exponential backoff and retry transient 5xx responses.
State and idempotency
Store company GUIDs, finding or rating identifiers, observed values, timestamps, and downstream status. Use deterministic event keys to prevent duplicate tickets, alerts, or database records during repeated polling.
Schema and testing
Map only required fields, preserve selected source payloads for auditability, and validate required response properties. Test authentication failures, authorization boundaries, pagination, rate limiting, malformed responses, downstream failures, and BitSight schema changes before production deployment.
Why use Martini instead of scripts or point-to-point integrations?
Reusable orchestration
Martini separates API consumption, scheduling, transformation, business rules, persistence, and downstream delivery into maintainable workflows rather than embedding all logic in a single script.
Controlled enterprise access
Martini can expose a secured API façade, protect BitSight credentials with Secrets Management, apply portfolio-level rules, and provide a stable internal model for consuming applications.
Reliable synchronization
Pagination, checkpoints, idempotency, retries, validation, and operational logging support large-portfolio synchronization and targeted replay when individual objects fail.
Frequently asked questions
BitSight is primarily integrated through its REST API, using API-key authentication to retrieve Companies, Ratings, Risk Vectors, Findings, Portfolios, and related data. Scheduled polling, pagination, incremental filters, local state comparison, and downstream API workflows are appropriate when general-purpose BitSight webhooks are unavailable or unconfirmed.
Yes. Martini can consume BitSight REST APIs from workflows, use the X-Api-Key authentication pattern, transform and synchronize BitSight data, and expose a controlled internal REST API for normalized or aggregated results.
No. A dedicated BitSight connector is not required. Martini can integrate using BitSight’s confirmed native REST APIs and API-key authentication, with scheduled workflows handling synchronization where webhook or callback support is not confirmed.
Lonti does not charge an additional per-connector or per-vendor fee to integrate BitSight. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from BitSight, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use the BitSight REST API as the primary integration method and API-key authentication through the X-Api-Key header. Collection endpoints support retrieval of multiple resources, but a separate bulk or asynchronous export API was not confirmed. GraphQL and SOAP APIs were also not confirmed.
A general-purpose BitSight webhook or outbound callback API was not confirmed. Product-specific alerts or notification features should be verified for the customer’s account and event type. Scheduled Martini polling with incremental filters and state comparison is the safer general-purpose pattern.
Martini can run scheduled workflows that retrieve BitSight data using supported date, update-time, status, or other filters, then compare it with durable local state. Stable company, finding, and rating identifiers, checkpoints, pagination, and idempotency keys help synchronize large portfolios without duplicate downstream actions.
Yes. Martini can expose a secured REST API that retrieves, transforms, filters, aggregates, or serves persisted BitSight data. This can protect the BitSight API key, apply portfolio-level access rules, minimize sensitive data, and provide internal applications with a stable response model.
Related Martini documentation
BitSight APIs
Workflows
Data processing
Integrate BitSight with Martini
Use Martini to connect BitSight security-risk data with enterprise workflows, applications, and reporting systems through secure REST API orchestration.