Verity471

The official Python SDK for the Verity471 API.

The client abstracts low-level API concerns by performing automatic query and payload validation and exposing a clean, typed interface to Verity471 data.

It also bridges the gap to standard CTI workflows by providing built-in STIX mapping for supported data items, allowing easier integration with threat intelligence platforms.

API bindings are generated via OpenAPI Generator, with manual extensions for validation and STIX support.

• API version: 1.1.12

  • creds: 1.0.4
  • indicators: 1.0.1
  • malware: 1.0.1
  • reports: 1.0.6
  • sources: 1.0.6
  • actors: 1.0.2
  • watchers: 1.0.2
  • observables: 1.0.1
  • entities: 1.0.1
  • girs: 1.0.1

• Package version: 1.1.12

• Generator version: 7.21.0

• Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements.

Python >= 3.10

Installation

Install from PyPI (recommended)

pip install verity471

This installs the core SDK without optional STIX support.

Optional features

STIX support:

pip install "verity471[stix]"

Development and test dependencies:

pip install "verity471[test]"

Both extras can be installed together:

pip install "verity471[stix,test]"

Install from GitHub

You can also install the SDK directly from the Git repository:

pip install git+ssh://git@github.com/intel471/verity471-python.git

With extras:

pip install "git+ssh://git@github.com/intel471/verity471-python.git#egg=verity471[stix,test]"

Getting Started

Please follow the installation procedure and then run the following:

import verity471
from verity471.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.intel471.cloud
# See configuration.py for a list of all supported configuration parameters.
configuration = verity471.Configuration(
    host = "https://api.intel471.cloud"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure HTTP basic authorization: basicAuth
configuration = verity471.Configuration(
    username = os.environ["USERNAME"],
    password = os.environ["PASSWORD"]
)


# Enter a context with an instance of the API client
with verity471.ApiClient(configuration) as api_client:

    # Create an instance of the API class
    api_instance = verity471.IndicatorsApi(api_client)

    threat_type = 'malware' # str | Search indicators by threat type
    malware_family_name = 'trickbot' # str | Search indicators by malware family
    var_from = 1767225600000 # int | Search from specific date (UNIX timestamp in milliseconds)
    size = 10 # int | Number from 1 to 1000 (default to 1000)

    try:
        # Indicators stream
        api_response = api_instance.get_indicators_stream(threat_type=threat_type, malware_family_name=malware_family_name, var_from=var_from, size=size)
        print("The response of IndicatorsApi->get_indicators_stream:\n")
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling IndicatorsApi->get_indicators_stream: %s\n" % e)

Serialization

Each call to an API instance returns a structure composed of Python objects. The response can be serialized into one of the common formats, if needed.

Python dict

To convert the response into a Python dict, call the to_dict() method on the response object.

serialized = api_response.to_dict()

STIX format

Note
STIX support requires optional dependencies.
Install with:

pip install "verity471[stix]"

To convert the response into the STIX format (v2.1), call the to_stix() method on the response object. This method converts the API response into the corresponding STIX objects and returns them wrapped in a Bundle object (from stix2 package). The Bundle object can be serialized into a JSON string using its serialize() method.

bundle = api_response.to_stix()
json_repr = bundle.serialize()

Some responses can be augmented with additional data obtained via extra API calls. This applies only to report-related stream endpoints.

Stream endpoints are designed for search. When a report is large, the returned payload may be truncated: inline images are always removed, and in some cases entire fields are omitted. When fields are omitted, the is_truncated flag is set to true. As a result, the streamed representation may not contain the full report content.

If an instance of verity471.verity_stix.STIXMapperSettings is passed to the to_stix() method with the report_full_content flag set to True, the mapper will issue additional API calls to retrieve the full representation of each truncated report referenced in the stream results. This allows to execute a stream (search) endpoint and serialize it into STIX while still obtaining complete report data.

The STIXMapperSettings instance must be initialized with the verity471 package and an initialized api_client.

For the complete list of available settings, see the implementation of the STIXMapperSettings class in verity471/verity_stix/init.py.

import verity471
from verity471.verity_stix import STIXMapperSettings

configuration = verity471.Configuration(...)

with verity471.ApiClient(configuration) as api_client:
    api_instance = verity471.ReportsApi(api_client)
    api_response = api_instance.get_reports_info_stream(size=1)
    mapper_settings = STIXMapperSettings(
        verity471,
        api_client,
        report_full_content=True
    )
    bundle = api_response.to_stix(mapper_settings)

If the objects returned by the endpoint for some reason can't be mapped into STIX format, EmptyBundle exception will be raised.

At the moment following API methods provide the response in STIX format:

Empty cells inherit the value from the previous row.

Helper: fetch_alert_targets

The alerts stream endpoint returns lightweight StreamingWatcherAlert objects that carry metadata (status, watcher IDs, timestamps, highlights) but not the actual content the alert refers to. fetch_alert_targets resolves each alert's API link in parallel and pairs it with the fully fetched target object — a report, forum post, credential, indicator, or any other supported type.

When a target cannot be fetched (no link, no known SDK route, forbidden, or an unexpected error), the alert is still returned by default with target=None and a status explaining why, so nothing is silently lost. Pass skip_missing_targets=True to omit such alerts instead. Marketplace hits have no SDK route yet, so they come back as bare alerts with status=UNRESOLVABLE (or are omitted when skip_missing_targets=True), the same as any other unresolvable target.

from verity471.helpers import fetch_alert_targets, AlertTarget, AlertTargetStatus

Parameters

Returns

A list of AlertTarget objects in the same order as alerts_response.alerts.

Each AlertTarget exposes:

Watcher and group data is fetched once per fetch_alert_targets call (two parallel API requests) and shared by reference across all AlertTarget objects — there is no duplication even when many alerts share the same watcher.

Example usage

import verity471
from verity471.helpers import fetch_alert_targets

configuration = verity471.Configuration(
    username="your_username",
    password="your_password",
)

with verity471.ApiClient(configuration) as api_client:
    alerts_api = verity471.AlertsApi(api_client)
    alerts_response = alerts_api.get_alerts_stream(size=10)

    targets = fetch_alert_targets(alerts_response, api_client)
    for t in targets:
        watcher_name = t.watcher.name if t.watcher else None
        group_name = t.watcher_group.name if t.watcher_group else None
        print(t.alert.source_type, t.alert.status, watcher_name, group_name, t.target_summary)

Example output

fintel read threat_actor Ransomware actors [Fintel] Threat Landscape: Q1 2025 Summary | 2025-03-15T12:00:00Z | Key findings from the first quarter include…
forum_post unread ddos_monitor My Watchers [Forum Post] Selling access to corporate VPN… | 2025-03-14T08:30:00Z
credential_occurrence unread cred_watcher Credential Alerts [Credential Occurrence] https://example.com/login | email | 2025-03-13T10:00:00Z
malware_report read malware_tracker My Watchers [Malware Report] New variant of Lumma Stealer | 2025-03-12T15:45:00Z | A new variant has been observed…

Helper: get_latest

Stream endpoints return data in ascending (oldest-first) order only — there is no way to sort descending or jump directly to the most recent page. get_latest works around this by probing the API with a small time window, expanding it until enough items exist, and then fetching and slicing the tail.

from verity471.helpers import get_latest

Parameters

Returns

A list of at most n items in ascending order (oldest first), so the last element is always the single most-recent item. When fewer than n items exist in the full history the function returns however many are available.

How probing works

The helper issues lightweight size=1 probe calls to count matching items in progressively wider time windows (doubling each round), starting from an endpoint-specific seed tuned to typical data density. Once count >= n, the helper drains that window by paging through the cursor and keeps only the newest n items. Because responses are best-effort — a page may contain fewer items than requested when the payload is large — paging continues until the window is drained or an empty page arrives, rather than assuming one request returns the whole window.

Example usage

import verity471
from verity471.helpers import get_latest

configuration = verity471.Configuration(
    username="your_username",
    password="your_password",
)

with verity471.ApiClient(configuration) as api_client:
    reports_api = verity471.ReportsApi(api_client)

    # 20 most recent spot reports
    reports = get_latest(reports_api.get_reports_spot_stream, n=20)
    for r in reports:
        print(r.title, r.released_ts)

    # 50 most recent malware events for a specific family
    events_api = verity471.EventsApi(api_client)
    events = get_latest(
        events_api.get_events_stream,
        n=50,
        malware_family_name="Cobalt Strike",
    )

Documentation for API Endpoints

All URIs are relative to https://api.intel471.cloud

Documentation For Models

• Activity
• ActivityLocation
• ActivityResponse
• Actor
• ActorObject
• ActorStreamPage
• ActorSubjectOfReport
• AdmiraltyCode
• AllMalwareProfiles
• Assessment
• AttachmentClassification
• AttachmentData
• AuthorActor1
• BadRequest
• BotSettings
• BreachAlertByIdResponse
• BreachAlertResponse
• BreachAlertsResponseStream
• BulletproofHosting
• ChatMessageStream
• ChatMessagesStreamingPage
• ChatRoomMessageStream
• ChatServerType
• ChatServerTypeStream
• Classification
• ClassificationResponse
• Confidence
• ConfidenceLevel
• Conflict
• ControllerUrl
• CountryProfileResponse
• CredCredentialSetResponse
• CredDataResponse
• CredPasswordComplexityResponse
• CredPasswordResponse
• CredSetAccessedDomainDataResponse
• CredSetAccessedUrlDataResponse
• CredSetDataResponse
• CredSetStatisticsResponse
• CredStatisticsResponse
• CredentialOccurrenceCredResponse
• CredentialOccurrenceDataResponse
• Cvss
• DataLeakSiteFileListingUrl
• DataLeakSitePost
• DataLeakSitePost1
• DataLeakSitePostItem
• DataLeakSitePostWebsite
• DataLeakSitePostsStreamingPage
• DataLeakSitesWebsite
• Encryption
• Entities
• Entity
• EntityItem
• EntityStreamPage
• EntityType
• ErrorResponse
• ErrorResponseGirs
• EventController
• EventData
• EventTag
• EventsStream
• ExploitStatus
• File
• FintelReportSubType
• FintelReportsResponseStream
• FintelResponse
• Forbidden
• Forum
• ForumObject
• ForumsPostsStreamingPage
• ForumsPrivateMessagesStreamingPage
• ForumsResponse1
• GIR
• GeoIp
• GeoIpObservables
• GeopolReportDetailsResponse
• GeopolReportSubType
• GeopolReportsResponseStream
• GetCredOccurrenceResponse
• GetCredOccurrenceResponseStream
• GetCredResponse
• GetCredResponseStream
• GetCredSetAccessedDomainResponse
• GetCredSetAccessedDomainsResponseStream
• GetCredSetAccessedUrlResponse
• GetCredSetAccessedUrlResponseStream
• GetCredSetResponse
• GetCredSetResponseStream
• GetWatcherGroupResponse
• GetWatcherGroupResponseWrapper
• GetWatcherResponse
• GetWatcherResponseWrapper
• GirTree
• GirsResponse
• GirsTreeResponse
• Highlight
• HighlightWatchers
• Href
• ImServer
• ImageType
• IndicatorData
• IndicatorsStream
• Industries
• InfoReportResponse
• InfoReportsResponseStream
• InfoStealerResponseOption
• InfoStealerResponseSet
• IntegrationsEvent
• IntegrationsIndicator
• IntelligenceEstimateResponse
• InterestLevel
• InternalServerError
• Ipv4
• Isp
• IspData
• KillChainPhase
• Link
• Links
• LinksSource
• Location
• Malware
• MalwareFamily
• MalwareReportResponse
• MalwareReportsResponseStream
• Motivation
• NotFound
• NotificationPreferenceType
• NotificationSettingsResponse
• Observable
• ObservableStreamPage
• ObservableType
• PatchStatus
• Poc
• PostDetails1
• PostResponse1
• PrivateMessageDetails1
• PrivateMessageResponse1
• ProcessingStatus
• RecipientDomain
• Redirect
• Report
• ReportAttachment
• ReportContent
• ReportLocation
• ReportResponseStream
• ReportType
• ReportingStatus
• ReportsVictimResponse
• Revocation
• RiskLevel
• RoomStream
• SecurityAssessment
• ServerStream
• Settings
• ShareSettingsResponse
• SignificantActivity
• SimplifiedMalwareProfile
• SourceLink
• SourceLinks
• SourcesLinks
• SourcesResponse
• SpotReportResponse
• SpotReportsResponseStream
• StreamingAlertsResponse
• StreamingWatcherAlert
• SubForumResponse1
• SubscriptionType
• Template
• TensionPointResponse
• ThreadResponse1
• Threat
• ThreatData
• ThreatInfo
• ThreatRating
• TranslationStatus
• Trigger
• Unauthorized
• VictimResponse
• VulnerabilitiesReportDetailsResponse
• VulnerabilitiesReportDetailsResponseStream
• VulnerabilitiesReportsResponseStream
• VulnerabilityStatus
• WatcherAlertStatus
• WatcherGroupType
• YaraData

Documentation For Authorization

Authentication schemes defined for the API:

basicAuth

• Type: HTTP basic authentication

Author

Intel 471 Inc.