Request Wrappers¶
These low-level wrappers provide direct access to specific PassiveTotal API endpoints. To determine which wrapper to use, review the API documentation for a specific dataset, then select a wrapper with a similar name.
Call the from_config() class method to obtain an instance of a request wrapper pre-configured with your API credentials (as set by the pt-config CLI command):
1from passivetotal import WhoisRequest
2whois_req = WhoisRequest.from_config()
Each wrapper class in this module can be directly imported from the passivetotal module for convenience.
Account Client¶
- class passivetotal.libs.account.AccountClient(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the account calls from the PassiveTotal API.
- get_account_classifications(**kwargs)¶
Get account items with the specified classification.
Reference: https://api.passivetotal.org/index.html#api-Account-GetV2AccountClassifications
- Parameters
classification (str) – Classification to retrieve items for, optional
- Returns
Dict of organization data
- get_account_details()¶
Get details about the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccount
- Returns
Dict of account data
- get_account_history(**kwargs)¶
Get history from the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccountHistory
- get_account_monitors()¶
Get monitors from the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccountMonitors
- Returns
Dict of monitor data
- get_account_notifications(**kwargs)¶
Get notifications from the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccountNotifications
- Returns
Dict of notifications data
- get_account_organization()¶
Get organization data from the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccountOrganization
- Returns
Dict of organization data
- get_account_organization_teamstream(**kwargs)¶
Get organization teamstream from the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccountOrganizationTeamstream
- get_account_quota()¶
Get current account and organization quotas from the requesting account.
Reference: https://api.passivetotal.org/index.html#api-Account-GetV2AccountQuota
- Returns
Dict of quota data
- get_account_sources(**kwargs)¶
Get sources from the requesting account.
Reference: https://api.passivetotal.org/api/docs/#api-Account-GetAccountSourcesSource
- Parameters
source (str) – A source to filter on, optional
- Returns
Dict of source data
Actions Request¶
- class passivetotal.libs.actions.ActionsClient(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the Actions calls from the PassiveTotal API.
Articles Request¶
- class passivetotal.libs.articles.ArticlesRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the Articles API calls from the PassiveTotal API.
- get_articles(**kwargs)¶
Get all articles.
Reference: https://api.passivetotal.org/index.html#api-Articles-GetV2Articles
- Parameters
page – Page number for results, optional
sort – order to sort - defaults to created, optional
order – ‘asc’ or ‘desc’, optional
- Returns
Dict of results
- get_articles_for_indicator(indicator, indicator_type=None)¶
Get articles that reference an indicator (typically a domain or IP).
Reference: https://api.riskiq.net/api/articles/#!/default/get_pt_v2_articles_indicator
- Parameters
indicator – Indicator to search, typically domain or IP
indicator_type – Type of indicator to search for (optional)
- Returns
Dict of results
- get_details(article_guid)¶
Get article details.
Reference: https://api.passivetotal.org/index.html#api-Articles-GetV2Articles
- Parameters
article_guid – GUID of the article (from get_articles)
- Returns
Dict of results
- get_indicators(**kwargs)¶
Get article indicators ordered by publish date oldest to newest.
Reference: https://api.passivetotal.org/index.html#api-Articles-GetV2ArticlesIndicators
- Parameters
articleGuid – GUID of the article, optional
startDate – Starting date in YYYY-MM-DD format, optional
- Returns
Dict of results
Artifacts Request¶
- class passivetotal.libs.artifacts.ArtifactsRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the Artifacts API calls from the PassiveTotal API.
- create_artifact(project_guid, artifact, **kwargs)¶
Create a new artifact on an existing project.
Reference: https://api.passivetotal.org/index.html#api-Artifact-PutV2Artifact
- Parameters
project_guid – Project ID the artifact will be attached to
artifact – The artifact itself - domain, IP, etc.
type – type of the artifact or inferred automatically if not provided, optional
tags – list of tags to label the new artifact with, optional
- Returns
Dict of results
- create_artifact_bulk(artifacts, **kwargs)¶
Create a bulk set of artifacts on an existing project.
Reference: https://api.passivetotal.org/index.html#api-Artifact-PutV2ArtifactBulk
- Parameters
artifacts – Array of artifact dictionaries with query, project guid, type, tags
- Returns
Dict of results
- delete_artifact(artifact_guid)¶
Delete an existing artifact.
Reference: https://api.passivetotal.org/index.html#api-Artifact-DeleteV2Artifact
- Parameters
artifact_guid – Artifact ID to delete
- Returns
Dict of results
- get_artifacts(**kwargs)¶
Get existing artifacts.
Reference: https://api.passivetotal.org/index.html#api-Artifact-GetV2Artifact
- Parameters
artifact – filter artifact ID, optional
project – filter by project ID, optional
owner – filter by owner (email or org id), optional
creator – filter by creator, optional
organization – filter by organization, optional
query – filter by query, optional
type – filter by artifact type, optional
- Returns
Dict of results
- update_artifact(artifact_guid, **kwargs)¶
Update an existing artifact.
Reference: https://api.passivetotal.org/index.html#api-Artifact-PostV2Artifact
- Parameters
artifact_guid – Artifact ID to update
monitor – Whether to monitor the artifact (true or false), optional
tags – list of tags to label the new artifact with, optional
- Returns
Dict of results
- update_artifact_bulk(artifacts, **kwargs)¶
Update a bulk set of artifacts on an existing project.
Reference: https://api.passivetotal.org/index.html#api-Artifact-PostV2ArtifactBulk
- Parameters
artifacts – Array of artifact dictionaries with artifact guid, monitor, tags
- Returns
Dict of results
- upsert_artifact(project_guid, artifact, artifact_type=None, tags=None, monitor=None)¶
Update a matching artifact or create it if it does not exist.
- Parameters
project_guid – Unique ID of the project containing the artifact
artifact – String of the artifact
type – Type of the artifact, optional (will be inferred if none provided)
monitor – Whether to monitor the artifact (true or false), optional
Attribute Request¶
- class passivetotal.libs.attributes.AttributeRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the Host Attribute calls from the PassiveTotal API.
- get_host_attribute_components(**kwargs)¶
Get components associated with a particular host or IP address.
Reference: https://api.passivetotal.org/api/docs/#api-Host_Attributes-GetComponents
- Returns
Dict of results with component information
- get_host_attribute_cookies(**kwargs)¶
Get cookies associated with a particular hostname.
Reference: https://api.passivetotal.org/index.html#api-Host_Attributes-GetV2HostAttributesCookies
- Returns
Dict of results with cookies information
- get_host_attribute_pairs(**kwargs)¶
Get pairs associated with a particular hostname.
Reference: https://api.passivetotal.org/api/docs/#api-Host_Attributes-GetV2HostAttributesPairsQuery
- Returns
Dict of results with hostpairs information
- get_host_attribute_trackers(**kwargs)¶
Get trackers associated with a particular host or IP address.
Reference: https://api.passivetotal.org/api/docs/#api-Host_Attributes-GetTrackers
- Returns
Dict of results with tracking IDs
- search_trackers(**kwargs)¶
Search tracking IDs for associated hosts.
Reference: https://api.passivetotal.org/api/docs/#api-Host_Attributes-SearchTrackers
- Returns
Dict of matching hosts using a tracking ID
Cards Request¶
- class passivetotal.libs.cards.CardsRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the cards API calls from the PassiveTotal API.
- get_summary(**kwargs)¶
Get services for an ip or domain.
Reference: https://api.passivetotal.org/index.html#api-Data_Card-GetV2CardsSummary
- Parameters
query – IP or domain to search
- Returns
Dict of results
DNS Request¶
- class passivetotal.libs.dns.DnsRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the DNS calls from the PassiveTotal API.
- get_passive_dns(**kwargs)¶
Get passive DNS data based on a query value.
Reference: https://api.passivetotal.org/api/docs/#api-DNS-GetDnsPassiveQuery
- Parameters
- Returns
List of passive DNS results
- get_unique_resolutions(**kwargs)¶
Get unique resolutions from passive DNS.
Reference: https://api.passivetotal.org/api/docs/#api-DNS-GetDnsPassiveUniqueQuery
- Parameters
- Returns
List of passive DNS unique resolutions
- search_keyword(**kwargs)¶
Search for a keyword across passive DNS data.
Reference: https://api.passivetotal.org/api/docs/#api-DNS-GetV2DnsSearchKeywordQuery
- Parameters
query (str) – Keyword value to search for in the dataset
- Returns
List of matching hits based on the keyword
Generic Request¶
- class passivetotal.libs.generic.GenericRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Class to interface with any PassiveTotal API endpoint.
- get(endpoint, action='', **params)¶
Make a generic request to the PassiveTotal API.
- Parameters
endpoint – Endpoint without version, i.e. ‘account’
action – Additional endpoint URL segments if needed, i.e. ‘quota’ or ‘whois/riskiq.net’, optional
params – Any additional key-value pairs to be passed to the API, optional
- Returns
Dict of returned data
- write(verb, endpoint, action='', data={})¶
Write data to an arbitrary PassiveTotal API endpoint.
- Parameters
verb – HTTP action - POST, PUT or DELETE
endpoint – API endpoint without version, i.e. ‘account’
action – Additional endpoint URL segments if needed, optional
data – Dict of data to write to the API endpoint, optional
Projects Request¶
- class passivetotal.libs.projects.ProjectsRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the Projects API calls from the PassiveTotal API.
- add_tags(project_guid, tags)¶
Add tags to an existing project.
Reference: https://api.passivetotal.org/index.html#api-Project-PostV2ProjectTag
- Parameters
project_guid – Project ID
tags – List of tags to add
- create_project(name, visiblity='analyst', **kwargs)¶
Create a new project.
Reference: https://api.passivetotal.org/index.html#api-Project-PutV2Project
- Parameters
name – Project name
visibility – allowed values ‘public’, ‘private’, or ‘analyst’
description – project description, optional
featured – whether to feature the project (true or false), optional
tags – sets the projects tags to a list, optional
- Returns
Dict of new project
- delete_project(guid)¶
Delete an existing project.
Reference: https://api.passivetotal.org/index.html#api-Project-DeleteV2Project
- Parameters
guid – Project ID
- find_projects(name_or_guid, visibility='analyst', owner=None, creator=None, org=None)¶
Obtain a list of all projects and find any project that match the criteria.
Set owner=’me’ or creator=’me’ to use the API username.
- Parameters
name_or_guid – Project name or project guid
visibility – Project visiblity: public, private, or analyst (default), optional
owner – Project owner, optional
creator – Project creater, optional
org – Project owner, optional
- get_projects(**kwargs)¶
Get all projects with optional filters.
Reference: https://api.passivetotal.org/index.html#api-Project-GetV2Project
IMPORTANT: If only one project matches the search, the API will return a single result instead of a list.
- Parameters
project – Project UUID, optional
owner – filter by owner (email or org id), optional
creator – filter by creator email, optional
organization – filter by organization, optional
visibility – filter by visiblity (public, private, or analyst), optional
featured – filter by featured status (true or false), optional
- Returns
Dict of results
- remove_tags(project_guid, tags)¶
Remove a list of tags from an existing project.
Reference: https://api.passivetotal.org/index.html#api-Project-DeleteV2ProjectTag
- Parameters
project_guid – Project ID
tags – List of tags to remove
- set_tags(project_guid, tags)¶
Set all tags on an existing project.
Reference: https://api.passivetotal.org/index.html#api-Project-PutV2ProjectTag
- Parameters
project_guid – Project ID
tags – List of tags to set
- update_project(guid, **kwargs)¶
Update an existing project.
Reference: https://api.passivetotal.org/index.html#api-Project-PostV2Project
- Parameters
guid – Project ID
name – New project name, optional
visibility – allowed values ‘public’, ‘private’, or ‘analyst’, optional
description – project description, optional
featured – whether to feature the project (true or false), optional
tags – sets the projects tags to a list, optional
- Returns
Dict of new project
Illuminate Request¶
- class passivetotal.libs.illuminate.IlluminateRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the RiskIQ Illuminate calls from the PassiveTotal API.
- get_asi_3p_vendor_insights(vendor_id, insight_id, **kwargs)¶
Get attack surface intelligence insights for a third-party vendor.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Returns
Dict of results
- get_asi_3p_vendor_priority(vendor_id, level, **kwargs)¶
Get attack surface intelligence priorities for a third-party vendor.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Returns
Dict of results
- get_asi_3p_vendor_summary(vendor_id)¶
Get attack surface intelligence summary for a third-party vendor.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Returns
Dict of results
- get_asi_3p_vendors(**kwargs)¶
Get list of attack surface intelligence third party vendors.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Returns
Dict of results
- get_asi_3p_vuln_components(vendor_id, **kwargs)¶
Get attack surface vulnerable components for a third-party vendor.
- Returns
Dict of results
- get_asi_3p_vuln_cve_observations(vendor_id, cve_id, **kwargs)¶
Get attack surface observations for a given CVE and third-party vendor ID.
- Returns
Dict of results
- get_asi_3p_vuln_cves(vendor_id, **kwargs)¶
Get attack surface vulnerabilities for a third-party vendor.
- Returns
Dict of results
- get_asi_insights(insight_id, **kwargs)¶
Get attack surface intelligence assets by insight ID.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Returns
Dict of results
- get_asi_priority(level, **kwargs)¶
Get attack surface intelligence priority detail.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Parameters
level – Priority level to retrieve details for [high, medium, low]
- Returns
Dict of results
- get_asi_summary()¶
Get attack surface intelligence summary for the main organization associated with an API account.
Reference: https://api.riskiq.net/api/asi_thirdparty/
- Returns
Dict of results
- get_asi_vuln_components(**kwargs)¶
Get attack surface vulnerable components.
Reference: https://api.riskiq.net/api/asi_thirdparty/#!/default/get_pt_v2_attack_surface_vuln_intel_components
- Returns
Dict of results
- get_asi_vuln_cve_observations(cve_id, **kwargs)¶
Get attack surface observations for a given CVE.
- Returns
Dict of results
- get_asi_vuln_cves(**kwargs)¶
Get attack surface vulnerabilities.
Reference: https://api.riskiq.net/api/asi_thirdparty/#!/default/get_pt_v2_attack_surface_vuln_intel_cves
- Returns
Dict of results
- get_intel_profile_details(profile_id)¶
Get intel profile details on a specific actor group.
Reference: https://api.riskiq.net/api/intel-profiles/
- Parameters
profile_id – Text identifier of the actor group.
- Returns
Dict of results
- get_intel_profile_indicators(profile_id, **kwargs)¶
Get IOCs associated with an intel profile.
Reference: https://api.riskiq.net/api/intel-profiles/
- Parameters
profile_id – Text identifier of the actor group.
- Returns
Dict of results
- get_intel_profiles(**kwargs)¶
Get RiskIQ Intel Profiles.
Reference: https://api.riskiq.net/api/intel-profiles/
- Returns
Dict of results
- get_intel_profiles_for_indicator(indicator, **kwargs)¶
Check whether an indicator is associated with any intel profiles.
Reference: https://api.riskiq.net/api/intel-profiles/
- Parameters
indicator – String representation of the IOC.
- Returns
Dict of results
- get_reputation(**kwargs)¶
Get RiskIQ Illuminate score for a domain or IP address.
Reference: https://api.riskiq.net/api/reputation/
- Parameters
query – Domain or IP address to search
- Returns
Dict of results
- get_vuln_article(cve_id, **kwargs)¶
Get details on a CVE vulnerability article.
Reference: https://api.riskiq.net/api/vulnerability/#!/default/get_pt_v2_vuln_intel_article_cveId
- Returns
Dict of results
Services Request¶
- class passivetotal.libs.services.ServicesRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the service calls from the PassiveTotal API.
- get_services(**kwargs)¶
Get services for an ip.
Reference: https://api.passivetotal.org/index.html#api-Services-GetV2Services
- Parameters
query – IP to search
- Returns
Dict of results
SSL Request¶
- class passivetotal.libs.ssl.SslRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the SSL calls from the PassiveTotal API.
- get_ssl_certificate_details(**kwargs)¶
Get SSL certificate details based on query value.
Reference: https://api.passivetotal.org/api/docs/#api-SSL_Certificates-GetSslCertificateQuery
- get_ssl_certificate_history(**kwargs)¶
Search SSL certificate history.
Reference: https://api.passivetotal.org/api/docs/#api-SSL_Certificates-GetSslCertificateHistoryQuery
- search_keyword(**kwargs)¶
Search for a keyword across SSL certificate data.
Reference: https://api.passivetotal.org/api/docs/#api-SSL_Certificates-GetV2SslCertificateSearchQueryField
- Parameters
query (str) – Keyword value to search for in the dataset
- Returns
List of matching hits based on the keyword
- search_ssl_certificate_by_field(**kwargs)¶
Search SSL certificate details based on query value and field.
Reference: https://api.passivetotal.org/api/docs/#api-SSL_Certificates-GetSslCertificateSearchQueryField
WHOIS Request¶
- class passivetotal.libs.whois.WhoisRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the WHOIS calls from the PassiveTotal API.
- get_whois_details(**kwargs)¶
Get WHOIS details based on query value.
Reference: https://api.passivetotal.org/api/docs/#api-WHOIS-GetV2WhoisQuery
- search_keyword(**kwargs)¶
Search for a keyword across WHOIS data.
Reference: https://api.passivetotal.org/api/docs/#api-WHOIS-GetV2WhoisSearchKeywordQuery
- Parameters
query (str) – Keyword value to search for in the dataset
- Returns
List of matching hits based on the keyword
- search_whois_by_field(**kwargs)¶
Search WHOIS details based on query value and field.
Reference: https://api.passivetotal.org/api/docs/#api-WHOIS-GetV2WhoisSearchQueryField
Enrichment Request¶
- class passivetotal.libs.enrichment.EnrichmentRequest(*args, **kwargs)¶
Bases:
passivetotal.api.Client
Client to interface with the enrichment calls from the PassiveTotal API.
- get_bulk_enrichment(**kwargs)¶
Get bulk enrichment data for a value.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentBulkQuery
- Parameters
query – Value to enrich
- Returns
Dict of results
- get_bulk_malware(**kwargs)¶
Get bulk malware data for a value.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentBulkMalwareQuery
- Parameters
query – Value to search for in OSINT
- Returns
Dict of results
- get_bulk_osint(**kwargs)¶
Get bulk OSINT data for a value.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentBulkOsintQuery
- Parameters
query – Value to search for in OSINT
- Returns
Dict of results
- get_enrichment(**kwargs)¶
Get enrichment data for a value.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentQuery
- Parameters
query – Value to enrich
- Returns
Dict of results
- get_malware(**kwargs)¶
Get malware data for a value.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentMalwareQuery
- Parameters
query – Value to search for in malware
- Returns
Dict of results
- get_osint(**kwargs)¶
Get OSINT data for a value.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentOsintQuery
- Parameters
query – Value to search for in OSINT
- Returns
Dict of results
- get_subdomains(**kwargs)¶
Get listing of subdomains for a given query.
Reference: https://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentSubdomains