Analyzer Module¶
The passivetotal.analyzer module provides high-level objects that directly
map to the most common starting points in security investigations, including
hostnames & IP addresses. Key features include:
API abstraction enables direct property access without knowing which endpoint to query.
On-demand API queries load data as needed and persist the data in the object instance.
List-like results objects are easy to iterate and provide useful filters.
Object instances stored as class members, ensuring efficient re-use of API results and enabling method chaining on complex result sets.
Helpful string and repr views to quickly inspect objects in an interactive environment.
Initialization¶
The analyzer module must be initialized before it can be used. This can be as
simple as calling the init() method at the module level:
from passivetotal import analyzer
analyzer.init()
This will read the API configuration setup by the pt-setup command line script
and prepare request wrappers for use in subsequent calls.
No other configuration is required to begin using the analyzer module, but you should review the module reference to become aware of configuration options that would normally be set in specific API calls.
Hostname Analysis¶
Example Usage
>>> from passivetotal import analyzer
>>> analyzer.init()
>>> host = analyzer.Hostname('riskiq.net')
>>> registrant = host.whois.organization
>>> print(registrant.organization)
RiskIQ UK Limited
- class passivetotal.analyzer.Hostname(hostname)¶
Represents a hostname such as api.passivetotal.org.
Instances are stored as class members so subsequent instantiations for the same hostname return the same object.
Because of this, storing instances in variables is optional, which can be especially useful in interactive sessions such as Jupyter notebooks.
- property articles¶
Threat intelligence articles that reference this host.
- Return type
- property artifacts¶
List of project artifacts that correspond with this object.
- Return type
- property certificates¶
List of certificates where this hostname is contained in the subjectAlternativeName field.
Creates an instance of
passivetotal.analyzer.ssl.CertificateFieldand performs a certificate search.- Return type
- property components¶
History of web components observed on this host.
Web components represent technology that powers Internet-facing services. Component categories are derived from detection logic explicitly created by RiskIQ analysts. Component values and, when available, component versions, describe the web technology discovered on a given web host.
- property cookies¶
History of cookies presented by this host.
- Return type
passivetotal.analyzer.components.CookieHistory
- property domain¶
Returns only the domain portion of the registered domain name for this hostname.
Uses the tldextract library and returns the domain property of the ExtractResults named tuple.
- get_host_identifier()¶
Alias for the hostname as a string.
Used for API queries that accept either a hostname or an IP address as the query value.
- property hostname¶
Hostname as a string.
- property hostpair_children¶
Hostpair relationships where this host is the parent.
- Return type
- property hostpair_parents¶
Hostpair relationships where this host is the child.
- Return type
- property intel_profiles¶
List of RiskIQ Threat Intel Profiles that reference this host.
For more granular searches, call the passivetotal.analyzer.illuminate.cti.IntelProfiles.find_by_indicators() method directly.
- property ip¶
Hostname’s current IP address.
Performs an local on-demand DNS query if needed.
- Return type
- property is_hostname¶
Whether this object is a hostname. Always returns true.
Useful when obtaining a host froma list that may provide either an analyzer.Hostname or analyzer.IPAddress object.
- property is_ip¶
Whether this object is an IP. Always returns false.
Useful when obtaining a host from a list that may provide either an analyzer.Hostname or analyzer.IPAddress object.
- property malware¶
List of malware hashes associated with this host.
- Return type
- property projects¶
List of projects that reference this object as an artifact.
- Return type
- property registered_domain¶
Returns the registered domain name (with TLD) for this hostname.
Uses the tldextract library and returns the registered_domain property of the ExtractResults named tuple.
- property reputation¶
RiskIQ Illuminate Reputation profile for a hostname or IP.
- reset(prop=None)¶
Reset this instance to clear all (default) or one cached properties.
Useful when changing module-level settings such as analyzer.set_date_range().
- Parameters
prop (str) – Property to reset (optional, if none provided all values will be cleared)
- property resolutions¶
Passive DNS records where this host was the DNS response value.
Bounded by dates set in
passivetotal.analyzer.set_date_range(). timeout and sources params are also set by the analyzer configuration.Provides a list of
passivetotal.analyzer.pdns.PdnsRecordobjects contained in apassivetotal.analyzer.pdns.PdnsResolutionsobject.- Return type
- save_to_project(artifact_tags=None)¶
Save this object to the active project as an artifact.
Before saving the object, call analyzer.set_project() to set or create the active project.
- Parameters
project_tags – List of tags to apply to the artifact, optional.
- property subdomain¶
Entire set of subdomains for this hostname (third level and higher).
Uses the tldextract library and returns the subdomain property of the ExtractResults named tuple.
- property subdomains¶
List of subdomains observed in pDNS records for this hostname.
This query always returns data on the apex domain, even if this object is a hostname.
- Return type
passivetotal.analyzer.enrich.SubdomainList
- property summary¶
Summary of PassiveTotal data available for this hostname.
- Return type
- property tld¶
Returns the top-level domain name (TLD) for this hostname.
Uses the tldextract library and returns the suffix property of the ExtractResults named tuple.
- property tracker_references¶
Hosts with trackers that have this host as the value.
Performs several API queries to create a composite result; create an instance of
passivetotal.analyzer.Trackerif you need more granular control.
- property trackers¶
History of trackers observed on this host.
Trackers are analytics codes, social network accounts, and other unique details extracted from the web page by RiskIQ crawlers based on detection logic programmed by RiskIQ analysts.
- Return type
- property whois¶
Most recently available Whois record for the hostname’s domain name.
- Return type
- property whois_history¶
Historical Whois records for this hostname.
IP Analysis¶
Example Usage
>>> from passivetotal import analyzer
>>> analyzer.init()
>>> ip = analyzer.IPAddress('35.189.71.51')
>>> print(ip.summary)
22 records available for 35.189.71.51
>>> for record in ip.resolutions:
print(record)
A "trafficplus.name" [ 6 days ] (2021-01-01 to 2021-03-01)
- class passivetotal.analyzer.IPAddress(ip)¶
Represents an IPv4 address such as 8.8.8.8
Instances are stored as class members so subsequent instantiations for the same IP return the same object.
Because of this, storing instances in variables is optional, which can be especially useful in interactive sessions such as Jupyter notebooks.
- property articles¶
Threat intelligence articles that reference this host.
- Return type
- property artifacts¶
List of project artifacts that correspond with this object.
- Return type
- property certificates¶
History of TLS certificates presented by services hosted on this IP address.
- Return type
- property components¶
History of web components observed on this host.
Web components represent technology that powers Internet-facing services. Component categories are derived from detection logic explicitly created by RiskIQ analysts. Component values and, when available, component versions, describe the web technology discovered on a given web host.
- property cookies¶
History of cookies presented by this host.
- Return type
passivetotal.analyzer.components.CookieHistory
- get_host_identifier()¶
Alias for the IP address as a string.
Used for API queries that accept either a hostname or an IP address as the query value.
- property hostpair_children¶
Hostpair relationships where this host is the parent.
- Return type
- property hostpair_parents¶
Hostpair relationships where this host is the child.
- Return type
- property intel_profiles¶
List of RiskIQ Threat Intel Profiles that reference this host.
For more granular searches, call the passivetotal.analyzer.illuminate.cti.IntelProfiles.find_by_indicators() method directly.
- property ip¶
IP address as a string.
- property is_hostname¶
Whether this object is a hostname. Always returns false.
Useful when obtaining a host froma list that may provide either an analyzer.Hostname or analyzer.IPAddress object.
- property is_ip¶
Whether this object is an IP. Always returns true.
Useful when obtaining a host from a list that may provide either an analyzer.Hostname or analyzer.IPAddress object.
- property malware¶
List of malware hashes associated with this host.
- Return type
- property projects¶
List of projects that reference this object as an artifact.
- Return type
- property reputation¶
RiskIQ Illuminate Reputation profile for a hostname or IP.
- reset(prop=None)¶
Reset this instance to clear all (default) or one cached properties.
Useful when changing module-level settings such as analyzer.set_date_range().
- Parameters
prop (str) – Property to reset (optional, if none provided all values will be cleared)
- property resolutions¶
Passive DNS records where this host was the DNS response value.
Bounded by dates set in
passivetotal.analyzer.set_date_range(). timeout and sources params are also set by the analyzer configuration.Provides a list of
passivetotal.analyzer.pdns.PdnsRecordobjects contained in apassivetotal.analyzer.pdns.PdnsResolutionsobject.- Return type
- save_to_project(artifact_tags=None)¶
Save this object to the active project as an artifact.
Before saving the object, call analyzer.set_project() to set or create the active project.
- Parameters
project_tags – List of tags to apply to the artifact, optional.
- property services¶
Record of services observed on this host.
- Return type
- property summary¶
Summary of PassiveTotal data available for this hostname.
- Return type
- property tracker_references¶
Hosts with trackers that have this host as the value.
Performs several API queries to create a composite result; create an instance of
passivetotal.analyzer.Trackerif you need more granular control.
- property trackers¶
History of trackers observed on this host.
Trackers are analytics codes, social network accounts, and other unique details extracted from the web page by RiskIQ crawlers based on detection logic programmed by RiskIQ analysts.
- Return type
- property whois¶
Most recently available Whois record for IP.
- Return type
- property whois_history¶
Historical Whois (ownership) records for this IP.
Analyzer Module Reference¶
Analyzer package for the RiskIQ PassiveTotal API.
- passivetotal.analyzer.AttackSurface(id_or_name=None)¶
Find one attack surface.
Call with no parameters to find your Attack Surface. Pass a number to load a specific Attack Surface by ID, or pass a string to load the entire list of Attack Surfaces and search them by case-insensitive substring.
Raises AnalyzerError if no attack surfaces are found or if more than one Attack Surface name matches the parameter.
- Returns
passivetotal.illuminate.AttackSurface
- passivetotal.analyzer.clear_datesort()¶
Unset the sort and order param for date-aware searches to restore default behavior.
- passivetotal.analyzer.get_api(name)¶
Return an instance of an API client by name.
- passivetotal.analyzer.get_config(key=None)¶
Get the active configuration for the analyzer module.
- passivetotal.analyzer.get_object(input, type=None)¶
Get an Analyzer object for a given input and type. If no type is specified, type will be autodetected based on the input.
If the input is already an Analyzer object it will be returned as-is.
Returns
analyzer.Hostnameoranalyzer.IPAddress.
- passivetotal.analyzer.get_project()¶
Get the active project.
- Return type
- passivetotal.analyzer.get_version()¶
Get the current version of this package.
- passivetotal.analyzer.init(**kwargs)¶
Instantiate API clients.
Arguments are passed to the request wrapper constructors; if none are provided, the class method from_config() is called to instantiate an API client from config files.
- passivetotal.analyzer.set_context(provider, variant, version, feature='')¶
Define the application context for an implementation using the analyzer module.
Sets a header to be sent in API requests that is used for metrics and troubleshooting.
- Parameters
provider – The company, partner, provider or other top-level application context.
variant – The specific app, libary subcomponent, or feature category.
version – Version of the app, feature or code setting the context.
feature – Optional sub-feature, dashboard or script name.
- passivetotal.analyzer.set_date_range(days_back=90, start=None, start_date=None, end=None, end_date=None)¶
Set a range of dates for all date-bounded API queries.
By default, queries will be bounded by analyzer.DEFAULT_DAYS_BACK. Set days_back to calculate the starting and ending dates automatically relative to today’s date.
Or, set the start and end params explicitly using a string in YYYY-MM-DD 00:00:00 format or start_date and end_date params as datetime objects.
- Parameters
days_back – Number of days back to query (optional, defaults to DEFAULT_DAYS_BACK).
start – Starting date as string in YYYY-MM-DD 00:00:00 format (optional).
start_date – Starting date as datetime object (optional).
end – Ending date as string in YYYY-MM-DD 00:00:00 format (optional).
end_date – Ending date as datetime object (optional).
- passivetotal.analyzer.set_dateorder_descending()¶
Set the order param for date-aware searches to ‘firstSeen’.
Especially relevant when searching crawl data such as components, cookies, hostpairs, and trackers.
- passivetotal.analyzer.set_datesort_ascending()¶
Set the order param for date-aware searches to ‘asc’.
Especially relevant when searching crawl data such as components, cookies, hostpairs, and trackers.
- passivetotal.analyzer.set_datesort_firstseen()¶
Set the sort param for date-aware searches to ‘firstSeen’.
Especially relevant when searching crawl data such as components, cookies, hostpairs, and trackers.
- passivetotal.analyzer.set_datesort_lastseen()¶
Set the sort param for date-aware searches to ‘lastSeen’.
Especially relevant when searching crawl data such as components, cookies, hostpairs, and trackers.
- passivetotal.analyzer.set_pdns_sources(sources)¶
Set a list of third-sources for pDNS queries.
- passivetotal.analyzer.set_pdns_timeout(timeout)¶
Set a timeout on pDNS queries to third-party sources.
- passivetotal.analyzer.set_pprint_params(**kwargs)¶
Configure options for the Python prettyprint module.
- passivetotal.analyzer.set_project(name_or_guid, visibility='analyst', description='', tags=None, create_if_missing=True)¶
Set the active Illuminate Project for this investigation.
Used by Analyzer objects to persist results to projects. Performs an API query to determine if project exists, create it if it is missing, and obtain necessary details.
- Parameters
name_or_guid – Project name or project GUID.
visibility – Who can see the project: public, private or analyst (optional, defaults to ‘analyst’).
description – Description of the project (optional).
tags – List of tags to apply to the project (optional).
create_if_missing – Whether to auto-create the project if it doesn’t exist (optional, defaults to true).
Summary Data¶
Hostnames and IPs offer a summary property that provides insight into how many records are available across multiple PassiveTotal datasets, along with a few key metrics about the host.
Summary data offers an ideal starting point for hostname and IP analysis. The counts directly inform security research and may guide subsequent searches.
- class passivetotal.analyzer.summary.HostnameSummary(api_response)¶
Summary of available PassiveTotal data and key facts for hostnames.
- property articles¶
Count of open-source intelligence (OSINT) articles referencing this IP or hostname.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property asn¶
Autonomous System Number the host resides in.
- property available¶
List of datasets with at least one record.
- property certificates¶
Count of available SSL certificate historical records.
- property components¶
Count of available web component records for this hostname.
- property cookies¶
Count of available cookies records for this hostname.
- property hosting_provider¶
Name of the web hosting provider.
- property hostpairs¶
Count of available hostpair records for this hostname.
- property link¶
Link to the entire summary card in the UI.
- property links¶
Dictionary of links to continue research on a dataset in the UI.
- property malware_hashes¶
Count of available malware hash records.
- property name¶
Queried name.
- property netblock¶
IP Netblock the host or IP is in.
- property os¶
Operating system of the host.
- property pdns¶
Alias for resolutions property.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property projects¶
Count of PassiveTotal projects containing this IP or hostname.
- property querytype¶
Determined type of the query name.
- property resolutions¶
Count of available pDNS historical resolutions.
- to_dataframe(exclude_links=True)¶
Render this object as a Pandas DataFrame.
- Parameters
exclude_links – Whether to exclude links from the dataframe (optional, defaults to True)
- Return type
pandas.DataFrame
- property total¶
Sum of all available records.
- property trackers¶
Count of available trackers records for this hostname.
- class passivetotal.analyzer.summary.IPSummary(api_response)¶
Summary of available PassiveTotal data and key facts for IPs.
- property articles¶
Count of open-source intelligence (OSINT) articles referencing this IP or hostname.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property asn¶
Autonomous System Number the host resides in.
- property available¶
List of datasets with at least one record.
- property certificates¶
Count of available SSL certificate historical records.
- property hosting_provider¶
Name of the web hosting provider.
- property link¶
Link to the entire summary card in the UI.
- property links¶
Dictionary of links to continue research on a dataset in the UI.
- property malware_hashes¶
Count of available malware hash records.
- property name¶
Queried name.
- property netblock¶
IP Netblock the host or IP is in.
- property os¶
Operating system of the host.
- property pdns¶
Alias for resolutions property.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property projects¶
Count of PassiveTotal projects containing this IP or hostname.
- property querytype¶
Determined type of the query name.
- property resolutions¶
Count of available pDNS historical resolutions.
- property services¶
Number of service (port) history records for this IP.
- to_dataframe(exclude_links=True)¶
Render this object as a Pandas DataFrame.
- Parameters
exclude_links – Whether to exclude links from the dataframe (optional, defaults to True)
- Return type
pandas.DataFrame
- property total¶
Sum of all available records.
Whois Records¶
Domain Name Whois¶
The whois property for host names returns the DomainWhois record for the registered domain name portion of the host name.
>>> from passivetotal import analyzer
>>> analyzer.init()
>>> print(analyzer.Hostname('riskiq.net').whois.registrant.organization)
RiskIQ UK Limited
Whois data varies widely across Internet registrars and registries, and although the API tries to normalize and parse the data into fields, your code should always be prepared for missing or malformed data. Access the raw record for the API response directly as a Python dict or use the record property to get the raw Whois response.
IP Whois Records¶
The whois property is also available for IP addresses. Some of the fields are different than domain whois records, but most are the same.
>>> from passivetotal import analyzer
>>> analyzer.init()
>>> print(analyzer.IPAddress('160.69.1.37').whois.organization)
PACCAR, Inc.
Using Whois Fields¶
Fields in the IP and Hostname Whois record are returned as WhoisField objects to faciliate field-level searching. Cast the field as a string if you need to get the actual value:
>>> org = analyzer.IPAddress('160.69.1.37').whois.organization
>>> org
WhoisField('organization','PACCAR, Inc.')
>>> print(org)
Paccar, Inc.
>>> org_str = str(org)
>>> org_str
Paccar, Inc.
You can also start with a field name and a string and search for it directly to find domains or IPs associated with a name, email address, or other supported field type.
>>> from passivetotal.analyzer.whois import WhoisField
>>> WhoisField('email','domains@riskiq.com').records.domains
Search Whois Records¶
The RiskIQ PassiveTotal API can search Whois records by field to find related domain names with the same contact information. Use the records property of supported fields (any property that returns type WhoisField).
>>> from passivetotal import analyzer
>>> analyzer.Hostname('riskiq.net').whois.organization.records.domains
{Hostname('riskiq.com'), Hostname('riskiq.net'), Hostname('riskiqeg.com')}
The records property returns the same type of list-like object that other analyzer objects return, so you can filter, sort, and convert to pandas DataFrames as needed. See below for reference.
Historical Whois Records¶
Historical whois records may be available for domain names and IP addresses. Access the whois_history property of an IPAddress or Hostname object to obtain a list of historically observed records as a standard analyzer RecordList.
>>> from passivetotal import analyzer
>>> for record in analyzer.Hostname('passivetotal.org').whois_history:
print(record.last_seen, record.registrant_email)
2022-02-11 19:16:29.334000-08:00 passivetotal.org-registrant@anonymised.email
2021-04-05 09:13:10.330000-07:00 passivetotal.org-registrant@anonymised.email
2021-04-04 08:40:41.295000-07:00 passivetotal.org-registrant@anonymised.email
2021-04-03 16:25:42.455000-07:00 passivetotal.org-registrant@anonymised.email
2021-04-06 08:42:07.273000-07:00 passivetotal.org-registrant@anonymised.email
2021-03-04 15:45:41.026000-08:00 passivetotal.org-Registrant@anonymised.email
2021-03-03 13:56:05.605000-08:00 passivetotal.org-registrant@anonymised.email
2020-10-06 02:41:38.359000-07:00 passivetotal.org-registrant@anonymised.email
2020-10-06 14:01:33.575000-07:00 passivetotal.org-registrant@anonymised.email
2020-08-21 04:20:43.757000-07:00 passivetotal.org-Registrant@anonymised.email
2020-06-20 03:57:01.411000-07:00 abuse@comlaude.com
2020-03-16 15:22:46.043000-07:00 abuse@comlaude.com
2020-03-17 06:57:02.899000-07:00 abuse@comlaude.com
2019-09-29 07:45:02.096000-07:00 domains@riskiq.com
In this example, we accessed only two fields of each record, but the complete Whois record remains available. Consider using the as_dict or as_df properties of the whois_history object to get the complete list as a Python dictionary or a Pandas dataframe.
>>> analyzer.Hostname('passivetotal.org').whois_history.as_dict
{'records': [{'admin': {'email': 'passivetotal.org-admin@anonymised.email'},
'billing': {},
'registrant': {'country': 'US',
'email': 'passivetotal.org-registrant@anonymised.email',
...
Whois Object Reference¶
- class passivetotal.analyzer.whois.DomainWhois(record)¶
Whois record for an Internet domain name.
- property admin¶
Admin contact record.
- Return type
- property age¶
Number of days between now and when the domain was registered.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property billing¶
Billing contact record.
- Return type
- property contacts¶
Primary domain contact records.
- Return type
- property date_expires¶
Date the domain expires.
- Return type
datetime
- property date_loaded¶
Date when the domain or IP was loaded into the database.
- Return type
datetime
- property date_registered¶
Date the domain or IP was registered.
- Return type
datetime
- property date_updated¶
Date when the domain or IP was updated at the registrar or registry.
Be aware that registrars and registries may not reliably update this date when the contents of the record changes. Even when they do, it usually only means the domain was renewed or expired, or the nameservers were changed.
- Return type
datetime
- property domain¶
The domain name as returned by the API.
- property email¶
Primary contact email address.
- property emails¶
Set of all email addresses in the Whois record.
- property host¶
Get the IP or domain name this record is associated with, as an
analyzer.IPAddressoranalyzer.Hostnameobject.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property name¶
Primary registrant name.
- property nameservers¶
List of nameservers.
- property organization¶
Primary contact organization name.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property raw¶
Raw API response.
- property record¶
Raw Whois record as text.
- property registrant¶
Whois registrant contact record.
- Return type
- property registrant_email¶
Registrant email from the registrant contact record.
- property registrant_name¶
Registrant name from the registrant contact record.
- property registrant_org¶
Registrant organization from the registrant contact record.
- property registrant_phone¶
Registrant telephone number from the registrant contact record.
- property registrar¶
Registrar of record for the domain or IP.
- property server¶
Whois server that delivered the record.
- property tech¶
Technical contact record.
- Return type
- property telephone¶
Primary contact telephone number.
- to_dataframe(include_record=False, only_registrant=True)¶
Render this object as a Pandas DataFrame.
- class passivetotal.analyzer.whois.IPWhois(record)¶
Whois record for an IP Address.
- property admin¶
Admin contact record.
- Return type
- property age¶
Number of days between now and when the domain was registered.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property billing¶
Billing contact record.
- Return type
- property contacts¶
Primary domain contact records.
- Return type
- property date_loaded¶
Date when the domain or IP was loaded into the database.
- Return type
datetime
- property date_registered¶
Date the domain or IP was registered.
- Return type
datetime
- property date_updated¶
Date when the domain or IP was updated at the registrar or registry.
Be aware that registrars and registries may not reliably update this date when the contents of the record changes. Even when they do, it usually only means the domain was renewed or expired, or the nameservers were changed.
- Return type
datetime
- property email¶
Primary contact email address.
- property emails¶
Set of all email addresses in the Whois record.
- property host¶
Get the IP or domain name this record is associated with, as an
analyzer.IPAddressoranalyzer.Hostnameobject.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property name¶
Primary registrant name.
- property organization¶
Primary contact organization name.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property raw¶
Raw API response.
- property record¶
Raw Whois record as text.
- property registrant¶
Whois registrant contact record.
- Return type
- property registrant_email¶
Registrant email from the registrant contact record.
- property registrant_name¶
Registrant name from the registrant contact record.
- property registrant_org¶
Registrant organization from the registrant contact record.
- property registrant_phone¶
Registrant telephone number from the registrant contact record.
- property registrar¶
Registrar of record for the domain or IP.
- property server¶
Whois server that delivered the record.
- property tech¶
Technical contact record.
- Return type
- property telephone¶
Primary contact telephone number.
- to_dataframe(include_record=False, only_registrant=True)¶
Render this object as a Pandas DataFrame.
- class passivetotal.analyzer.whois.WhoisField(name, value)¶
Searchable field in a Whois record.
Print or cast as string to access the value directly.
Provides a records property that searches the API for other Whois records that match the value provided in the field.
- property name¶
Name of the field.
- property records¶
List of
DomainWhoisrecords that match the key/value of this field.
- property value¶
Value of the field.
- class passivetotal.analyzer.whois.WhoisContact(organization, name, email, telephone)¶
- count(value, /)¶
Return number of occurrences of value.
- property email¶
Alias for field number 2
- index(value, start=0, stop=9223372036854775807, /)¶
Return first index of value.
Raises ValueError if the value is not present.
- property name¶
Alias for field number 1
- property organization¶
Alias for field number 0
- property telephone¶
Alias for field number 3
- class passivetotal.analyzer.whois.HistoricalWhoisRecords(api_response=None, query=None)¶
List of
HistoricalDomainWhoisorHistoricalIPWhoisrecords.- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property domains¶
Return a set of unique domains in this record list.
- property emails¶
Return a set of unique emails in this record list.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property names¶
Return a set of unique names in this record list.
- property orgs¶
Return a set of unique org names in this record list.
- parse(api_response)¶
Parse an API response into a list of HistoricalDomainWhois or HistoricalIPWhois records.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- class passivetotal.analyzer.whois.HistoricalDomainWhois(record)¶
Historical Whois record for a domain name.
- property admin¶
Admin contact record.
- Return type
- property age¶
Number of days between now and when the domain was registered.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property billing¶
Billing contact record.
- Return type
- property contacts¶
Primary domain contact records.
- Return type
- property date_expires¶
Date the domain expires.
- Return type
datetime
- property date_loaded¶
Date when the domain or IP was loaded into the database.
- Return type
datetime
- property date_registered¶
Date the domain or IP was registered.
- Return type
datetime
- property date_updated¶
Date when the domain or IP was updated at the registrar or registry.
Be aware that registrars and registries may not reliably update this date when the contents of the record changes. Even when they do, it usually only means the domain was renewed or expired, or the nameservers were changed.
- Return type
datetime
- property domain¶
The domain name as returned by the API.
- property email¶
Primary contact email address.
- property emails¶
Set of all email addresses in the Whois record.
- property host¶
Get the IP or domain name this record is associated with, as an
analyzer.IPAddressoranalyzer.Hostnameobject.
- property last_seen¶
Date the historical record was last seen.
Alias for date_loaded. :rtype: datetime
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property name¶
Primary registrant name.
- property nameservers¶
List of nameservers.
- property organization¶
Primary contact organization name.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property raw¶
Raw API response.
- property record¶
Raw Whois record as text.
- property registrant¶
Whois registrant contact record.
- Return type
- property registrant_email¶
Registrant email from the registrant contact record.
- property registrant_name¶
Registrant name from the registrant contact record.
- property registrant_org¶
Registrant organization from the registrant contact record.
- property registrant_phone¶
Registrant telephone number from the registrant contact record.
- property registrar¶
Registrar of record for the domain or IP.
- property server¶
Whois server that delivered the record.
- property tech¶
Technical contact record.
- Return type
- property telephone¶
Primary contact telephone number.
- to_dataframe(include_record=False, only_registrant=True)¶
Render this object as a Pandas DataFrame.
- class passivetotal.analyzer.whois.HistoricalIPWhois(record)¶
Historical Whois record for a IP address.
- property admin¶
Admin contact record.
- Return type
- property age¶
Number of days between now and when the domain was registered.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property billing¶
Billing contact record.
- Return type
- property contacts¶
Primary domain contact records.
- Return type
- property date_loaded¶
Date when the domain or IP was loaded into the database.
- Return type
datetime
- property date_registered¶
Date the domain or IP was registered.
- Return type
datetime
- property date_updated¶
Date when the domain or IP was updated at the registrar or registry.
Be aware that registrars and registries may not reliably update this date when the contents of the record changes. Even when they do, it usually only means the domain was renewed or expired, or the nameservers were changed.
- Return type
datetime
- property email¶
Primary contact email address.
- property emails¶
Set of all email addresses in the Whois record.
- property host¶
Get the IP or domain name this record is associated with, as an
analyzer.IPAddressoranalyzer.Hostnameobject.
- property last_seen¶
Date the historical record was last seen.
Alias for date_loaded. :rtype: datetime
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property name¶
Primary registrant name.
- property organization¶
Primary contact organization name.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property raw¶
Raw API response.
- property record¶
Raw Whois record as text.
- property registrant¶
Whois registrant contact record.
- Return type
- property registrant_email¶
Registrant email from the registrant contact record.
- property registrant_name¶
Registrant name from the registrant contact record.
- property registrant_org¶
Registrant organization from the registrant contact record.
- property registrant_phone¶
Registrant telephone number from the registrant contact record.
- property registrar¶
Registrar of record for the domain or IP.
- property server¶
Whois server that delivered the record.
- property tech¶
Technical contact record.
- Return type
- property telephone¶
Primary contact telephone number.
- to_dataframe(include_record=False, only_registrant=True)¶
Render this object as a Pandas DataFrame.
Threat Intel Articles¶
RiskIQ publishes threat intelligence articles with lists of IOCs (indicators of compromise). Using the Analyzer module, you can retrieve the entire list of currently published articles, or only those articles that are associated with an IP or hostname.
Fetch all articles
>>> from passivetotal import analyzer
>>> analyzer.init()
>>> articles = analyzer.AllArticles()
>>> for article in articles[0:3]: # retrieve the first 3 articles
print(article)
Threat Roundup for April 23 to April 30
PortDoor: New Chinese APT Backdoor Attack Targets Russian Defense Sector
UNC2447 SOMBRAT and FIVEHANDS Ransomware: A Sophisticated Financial Threat
Get articles for an IP and list other IOCs.
>>> from passivetotal import analyzer
>>> analyzer.init()
>>> for article in analyzer.IPAddress('23.95.97.59').articles:
print(article.title)
print(' HOSTNAMES:')
for hostname in article.hostnames:
print(f' {hostname}')
print(' IPs:')
for ip in article.ips:
print(f' {ip}')
Alert (AA20-302A) - Ransomware Activity Targeting the Healthcare and Public Health Sector
HOSTNAMES:
biillpi.com
chishir.com
dns1.yastatic.cf
...
IPs:
195.123.240.219
195.123.241.12
195.123.242.119
...
...
- class passivetotal.analyzer.articles.AllArticles(created_after=None, autoload=True)¶
All threat intelligence articles currently published by RiskIQ.
Contains a list of
passivetotal.analyzer.articles.Articleobjects.By default, instantiating the class will automatically load the entire list of threat intelligence articles. Pass autoload=False to the constructor to disable this functionality.
Only articles created after the start date specified in the analyzer.set_date_range() method will be returned unless a different created_after parameter is supplied to the object constructor.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- filter_tags(tags)¶
Filtered article list that includes articles with an exact match to one or more tags.
Tests the match_tags method on each article.
- Parameters
tags – String with one or multiple comma-separated tags, or a list
- Return type
- filter_text(text, fields=['tags', 'title', 'summary'])¶
Filtered article list that contain the text in one or more fields.
Searches tags, title and summary by default - set fields param to a smaller list to narrow the search.
- Parameters
text – text to search for
fields – list of fields to search (optional)
- Return type
- static find(query)¶
Query the Articles API endpoint and find articles that match the search term.
- Return type
- load(created_after=None)¶
Query the API for articles and load them into an articles list.
- Parameters
created_after – only return articles created after this date (optional, defaults to date set by analyzer.set_date_range()
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- class passivetotal.analyzer.articles.Article(api_response, query=None)¶
A threat intelligence article.
- property age¶
Age of the article in days, measured from create date.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property categories¶
List of categories this article is listed in.
- property date_created¶
Date the article was created in the RiskIQ database.
- property date_published¶
Date the article was published, as a datetime object.
- property guid¶
Article unique ID within the RiskIQ system.
- has_tag(tag)¶
Whether this article has a given tag.
- property hostnames¶
List of hostnames in this article.
- Return type
passivetotal.analyzer.ip.Hostname
- property indicator_count¶
Sum of all types of indicators in this article.
- property indicator_types¶
List of the types of indicators associated with this article.
- property indicators¶
List of indicators associated with this article.
This is the raw result retuned by the API. Expect an array of objects each representing a grouping of a particular type of indicator.
- property ips¶
List of IP addresses in this article.
- Return type
- property link¶
URL to a page with article details.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- match_tags(tags)¶
Exact match search for one or more tags in this article’s list of tags.
- Parameters
tags – String with one or multiple comma-seperated tags, or a list
- Rtype bool
Whether any of the tags are included in this article’s list of tags.
- match_text(text, fields=['tags', 'title', 'summary'])¶
Case insensitive substring search across article text fields.
Searches tags, title and summary by default - set fields param to a smaller list to narrow the search. :param text: text to search for :param fields: list of fields to search (optional) :rtype bool: whether the text was found in any of the fields
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property summary¶
Article summary.
- property tags¶
List of tags attached to this article.
- property title¶
Article short title.
- to_dataframe(ensure_details=True, include_indicators=False)¶
Render this object as a Pandas DataFrame.
- property type¶
Article visibility type (i.e. public, private).
Pandas Integration¶
The analyzer module contains an optional integration with the Pandas Python library. pandas is a robust data analytics toolset that integrates especially well with Jupyter Notebooks. Even if you don’t plan to use the more sophisticated features pandas offers, the vastly improved display of analyzer results in notebooks is well worth enabling the integration.
To get started, install the pandas Python package, ideally in a virtual environment:
pip install pandas
Nearly all analyzer objects offer results formatted as a Pandas DataFrame, which is the standard two-dimensional (tabluar) data format in Pandas. You can access the data with the as_df property or by calling the to_dataframe() method on an analyzer object. For example:
analyzer.Hostname('riskiq.net').summary.as_df
If this is the last line of a cell in a Jupyter notebook, and you run that cell, you’ll get a one-line tabular output with the summary data in columns.
To view a list of pDNS records:
analyzer.Hostname('riskiq.net').resolutions.as_df
Internally, the as_df property calls to_dataframe() on each object with
no parameters, which results in a default rendering of the dataframe. Some objects,
like passivetotal.analyzer.illuminate.ReputationScore, offer additional options
in their implementation of to_dataframe(). For example:
analyzer.Hostname('jquery.su').reputation.to_dataframe(explode_rules=True)
This will show the reputation score with one row for each rule returned by the Reputation API. It uses the pandas DataFrame.explode method to unstack a list into a set of rows and columns, hence the parameter name explode_rules.
Pandas dataframes are easily exported as CSV and offer capabilities to perform SQL-style joins and Excel-style VLOOKUPs. Consult the docs to learn what’s possible.
Using Record Lists¶
Several attributes of Hostnames and IPs return lists of records from the API. The analyzer module delivers these as list-like objects that can be looped through like regular Python lists. They also provide analytic methods to sort and filter records in meaningful ways.
Under normal usage, it should not be necessary to instantiate these objects directly. You will interact with them through the properties of higher-level objects like Hostnames and IPs.
Passive DNS Record Lists¶
- class passivetotal.analyzer.pdns.PdnsResolutions(api_response=None, query=None)¶
Historical passive DNS resolution records.
Provides a list-like interface to a collection of
PdnsRecordobjects.- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property dateend¶
End date of API query range.
- property datestart¶
Start date of API query range.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property firstseen¶
Earliest data available for this host.
- property lastseen¶
Most recent data available for this host.
- property newest¶
Most recently seen pDNS record.
- Return type
- property oldest¶
Oldest pDNS record (earliest firstseen date).
- Return type
- property only_a_records¶
Filter recordtype=’A’.
- Return type
- property only_hostnames¶
Filter resolvetype=’domain’.
- Return type
- property only_ips¶
Filter resolvetype=’ip’.
- Return type
- property pager¶
Pager value from API response.
- parse(api_response)¶
Implementations must accept an API response and populate themselves with a list of the correct record types.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property querytype¶
Interpreted query type form API response.
- property queryvalue¶
Interpreted query value from API response.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total number of records available for this query.
- class passivetotal.analyzer.pdns.PdnsRecord(record, query=None)¶
Individual pDNS record returned by the API.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property collected¶
Date & time the record was collected.
- Return type
datetime
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property hostname¶
passivetotal.analyzer.Hostnamethe record resolves to.Will return None if the resolvetype is not ‘domain’.
- property ip¶
passivetotal.analyzer.IPAddressthe record resolves to.Will return None if the resolvetype is not ‘ip’.
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property recordtype¶
DNS record type (A, CNAME, NS, MX, etc).
- property resolve¶
Resolve value of the pDNS record.
- property resolvetype¶
Type of the resolve value (hostname, ip, etc).
- property sources¶
Sources of API data.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Parameters
exclude_links – Whether to exclude links from the dataframe (optional, defaults to True)
- Return type
pandas.DataFrame
- property value¶
Query value used in pDNS record search.
SSL Certificate Record Lists¶
- class passivetotal.analyzer.ssl.Certificates(api_response=None, query=None)¶
List of historical SSL certificates.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property expired¶
Filtered list of
Certificatesthat have expired.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property newest¶
Most recently seen
CertificateRecord.
- property not_expired¶
Filtered list of
Certificatesthat have not expired.
- property oldest¶
Earliest seen
CertificateRecord.
- parse(api_response)¶
Implementations must accept an API response and populate themselves with a list of the correct record types.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- class passivetotal.analyzer.ssl.CertificateRecord(record)¶
SSL Certificate record.
This base class is suited for API responses with complete certificate details.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property date_expires¶
Date & time when the certificate expires.
- Return type
datetime
- property date_issued¶
Date & time the certificate was issued.
- Return type
datetime
- property days_valid¶
Number of days the certificate is valid.
Returns the timedelta between date_expires and date_issued. :rtype: int
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property expirationDate¶
Certificate expiration date field.
- Return type
- property expired¶
Whether the certificate has expired (if the expiration date is in the past).
- Return type
- property fingerprint¶
Certificate fingerprint field.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property hash¶
Certificate hash value.
- property iphistory¶
Get the direct API response for a history query on this certificates hash.
For most use cases, the ips property is a more direct route to get the list of IPs previously associated with this SSL certificate.
- property ips¶
Provides list of
passivetotal.analyzer.IPAddressinstances representing IP addresses associated with this SSL certificate.
- property issueDate¶
Certificate issue date field.
- Return type
- property issuerCommonName¶
Certificate issuer common name field.
- Return type
- property issuerCountry¶
Certificate issuer country.
- Return type
- property issuerDate¶
Certificate issue date field.
- Return type
- property issuerEmailAddress¶
Certificate issuer email address field.
- Return type
- property issuerGivenName¶
Certificate issuer given name field.
- Return type
- property issuerLocalityName¶
Certificate issuer locality name field.
- Return type
- property issuerOrganizationName¶
Certificate issuer organization name field.
- Return type
- property issuerOrganizationUnitName¶
Certificate issuer orgnaizational unit name field.
- Return type
- property issuerProvince¶
Certificate issuer province field.
- Return type
- property issuerSerialNumber¶
Certificate serial number field.
- Return type
- property issuerStateOrProvinceName¶
Certificate issuer state or province name field.
- Return type
- property issuerStreetAddress¶
Certificate issuer street address field.
- Return type
- property issuerSurname¶
Certificate issuer surname field.
- Return type
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property serialNumber¶
Certificate issuer serial number field.
- Return type
- property sha1¶
Certificate hash value (alias for hash).
- property sslVersion¶
Certificate ssl version field.
- Return type
- property subjectAlternativeNames¶
Certificate subject alternative names field.
- Return type
- property subjectCommonName¶
Certificate subject common name field.
- Return type
- property subjectCountry¶
Certificate subject country field.
- Return type
- property subjectEmailAddress¶
Certificate subject email address field.
- Return type
- property subjectGivenName¶
Certificate subject given name field.
- Return type
- property subjectLocalityName¶
Certificate subject locality name field.
- Return type
- property subjectOrganizationName¶
Certificate subject organization name field.
- Return type
- property subjectOrganizationUnitName¶
Certificate subject organizational unit name field.
- Return type
- property subjectProvince¶
Certificate subject province field.
- Return type
- property subjectSerialNumber¶
Certificate subject serial number field.
- Return type
- property subjectStateOrProvinceName¶
Certificate subject state or province name field.
- Return type
- property subjectStreetAddress¶
Certificate subject street address field.
- Return type
- property subjectSurname¶
Certificate subject surname field.
- Return type
- to_dataframe(include_ips=False)¶
Render this object as a Pandas DataFrame.
- Parameters
include_ips – Whether to include historical IP data in the dataframe (optional, defaults to False, will likely trigger new API query for each record.)
- Return type
pandas.DataFrame
- class passivetotal.analyzer.ssl.CertHistoryRecord(record)¶
SSL Certificate historical record.
Suited for API responses that may not provide SSL certificate details. Provides a mechanism to populate missing data with a call to the SSL certificate detail API upon first request of a missing field.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property date_expires¶
Date & time when the certificate expires.
- Return type
datetime
- property date_issued¶
Date & time the certificate was issued.
- Return type
datetime
- property days_valid¶
Number of days the certificate is valid.
Returns the timedelta between date_expires and date_issued. :rtype: int
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property expirationDate¶
Certificate expiration date field.
- Return type
- property expired¶
Whether the certificate has expired (if the expiration date is in the past).
- Return type
- property fingerprint¶
Certificate fingerprint field.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property hash¶
Certificate hash value.
- property iphistory¶
Get the direct API response for a history query on this certificates hash.
For most use cases, the ips property is a more direct route to get the list of IPs previously associated with this SSL certificate.
- property ips¶
Provides list of
passivetotal.analyzer.IPAddressinstances representing IP addresses associated with this SSL certificate.
- property issueDate¶
Certificate issue date field.
- Return type
- property issuerCommonName¶
Certificate issuer common name field.
- Return type
- property issuerCountry¶
Certificate issuer country.
- Return type
- property issuerDate¶
Certificate issue date field.
- Return type
- property issuerEmailAddress¶
Certificate issuer email address field.
- Return type
- property issuerGivenName¶
Certificate issuer given name field.
- Return type
- property issuerLocalityName¶
Certificate issuer locality name field.
- Return type
- property issuerOrganizationName¶
Certificate issuer organization name field.
- Return type
- property issuerOrganizationUnitName¶
Certificate issuer orgnaizational unit name field.
- Return type
- property issuerProvince¶
Certificate issuer province field.
- Return type
- property issuerSerialNumber¶
Certificate serial number field.
- Return type
- property issuerStateOrProvinceName¶
Certificate issuer state or province name field.
- Return type
- property issuerStreetAddress¶
Certificate issuer street address field.
- Return type
- property issuerSurname¶
Certificate issuer surname field.
- Return type
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property serialNumber¶
Certificate issuer serial number field.
- Return type
- property sha1¶
Certificate hash value (alias for hash).
- property sslVersion¶
Certificate ssl version field.
- Return type
- property subjectAlternativeNames¶
Certificate subject alternative names field.
- Return type
- property subjectCommonName¶
Certificate subject common name field.
- Return type
- property subjectCountry¶
Certificate subject country field.
- Return type
- property subjectEmailAddress¶
Certificate subject email address field.
- Return type
- property subjectGivenName¶
Certificate subject given name field.
- Return type
- property subjectLocalityName¶
Certificate subject locality name field.
- Return type
- property subjectOrganizationName¶
Certificate subject organization name field.
- Return type
- property subjectOrganizationUnitName¶
Certificate subject organizational unit name field.
- Return type
- property subjectProvince¶
Certificate subject province field.
- Return type
- property subjectSerialNumber¶
Certificate subject serial number field.
- Return type
- property subjectStateOrProvinceName¶
Certificate subject state or province name field.
- Return type
- property subjectStreetAddress¶
Certificate subject street address field.
- Return type
- property subjectSurname¶
Certificate subject surname field.
- Return type
- to_dataframe(include_ips=False)¶
Render this object as a Pandas DataFrame.
- Parameters
include_ips – Whether to include historical IP data in the dataframe (optional, defaults to False, will likely trigger new API query for each record.)
- Return type
pandas.DataFrame
- class passivetotal.analyzer.ssl.CertificateField(name, value)¶
A field on an SSL certificate.
Print or cast as string to access the value directly.
In addition to a simple key/value mapping, this class also provides a certificates property that searches the API for other SSL certificates that match the key/value pair of the instance.
- property certificates¶
List of
Certificatesthat match the key/value of this field.
- property name¶
Name of the field.
- property value¶
Value of the field.
May return a list if the name is ‘subjectAlternativeName’.
Services Record Lists¶
- class passivetotal.analyzer.services.Services(api_response=None, query=None)¶
Historical port, service and banner data.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total records available as returned by the API.
- class passivetotal.analyzer.services.ServiceRecord(api_response, query=None)¶
Record of an observed port with current and recent services.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property banners¶
List of banners observed on the service port.
- property certificate¶
SSL Certificate presented by the service.
- Return type
- property count¶
Number of records observed.
- property current_services¶
List of current services.
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property is_open¶
Whether the port status is ‘open’.
- property is_tcp¶
Whether the protocol is ‘TCP’.
- property is_udp¶
Whether the protocol is ‘UDP’.
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property port¶
Port number.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property protocol¶
Network protocol for the service.
- property recent_services¶
List of recent services.
- property status¶
Port status.
- to_dataframe(explode=None)¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
Hostpairs Record Lists¶
- class passivetotal.analyzer.hostpairs.HostpairHistory(api_response=None, direction=None, query=None)¶
Historical connections between hosts.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property causes¶
Set of unique causes in the hostpair record list.
- property children¶
Set of unique child hostnames in the hostpairs record list.
- property direction¶
Direction of the paired relationship - children or parents.
- property domains¶
List of unique registered domains.
- exclude_domains_in(hosts)¶
Filter the list to exclude records where the registered domain of the parent or child is not in a list of hosts. Accepts either a list of strings or a list of analyzer.Hostname objects.
Will apply to parents if direction is parents (from hostpair_parents property) or to children if direction is children(from hostpair_children property).
- Parameters
hosts – List of hostnames to directly match against, as a comma-separated string or a list.
- exclude_hosts_in(hosts)¶
Filter the list to exclude records where the parent or child is contained in not in a list of hosts. Accepts either a list of strings or a list of analyzer.Hostname objects.
Will apply to parents if direction is parents (from hostpair_parents property) or to children if direction is children(from hostpair_children property).
Use exclude_domains_in() to match against only the registered domain.
- Parameters
hosts – List of hostnames to directly match against, as a comma-separated string or a list.
- exclude_tlds_in(tlds)¶
Filter the list to exclude records where the tld of the registered domain of the parent or child is not in a list of tlds. Accepts either a list of strings or a list of analyzer.Hostname objects.
Will apply to parents if direction is parents (from hostpair_parents property) or to children if direction is children(from hostpair_children property).
- Parameters
hosts – List of hostnames to directly match against, as a comma-separated string or a list.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property hosts¶
List of unique paired hosts (IPs or hostnames).
Returns Hostpairs.children or Hostpairs.parents depending on the value of Hostpairs.direction
- load_all_pages()¶
Load all pages of results from the API.
- load_next_page()¶
Load the next page of results from the API.
Throws AnalyzerError when has_more_records is False.
- property parents¶
Set of unique parent hostnames in the hostpairs record list.
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total number of available records as reported by the API.
- class passivetotal.analyzer.hostpairs.HostpairRecord(api_response, direction=None, query=None)¶
Record of observed trackers.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property cause¶
Cause or category of the pairing, if known.
- property child¶
Descendant hostname for this pairing.
- property direction¶
Direction of the relationship - parent or child.
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property host¶
Returns the parent or the child host depending on whether the direction is “parent” or “child”.
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property parent¶
Parent hostname for this pairing.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
Web Component Record Lists¶
- class passivetotal.analyzer.components.ComponentHistory(api_response=None, query=None)¶
Historical web component data.
Web components represent technology that powers Internet-facing services. Component categories are derived from detection logic explicitly created by RiskIQ analysts. Component values and, when available, component versions, describe the web technology discovered on a given web host.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property categories¶
List of unique categories in the component record list.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property hostnames¶
List of unique hostnames in the component record list.
- load_all_pages()¶
Load all pages of results from the API.
- load_next_page()¶
Load the next page of results from the API.
Throws AnalyzerError when has_more_records is False.
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total number of available records as reported by the API.
- property values¶
List of unique values (labels) in the component record list.
- class passivetotal.analyzer.components.ComponentRecord(api_response, query=None)¶
Record of an observed web component.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property category¶
Category or type of the web component.
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property hostname¶
Hostname where the component was identified.
- property label¶
Value of the web component; alias of ComponentRecord.value.
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property query¶
API query value (hostname or IP address).
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
- property value¶
Value of the web component.
- property version¶
Version of the web component, if available.
Trackers Record Lists¶
- class passivetotal.analyzer.trackers.TrackerHistory(api_response=None, query=None)¶
Historical web component data.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property categories¶
List of unique categories (types) in the tracker record list.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property hostnames¶
List of unique hostnames in the tracker record list.
- load_all_pages()¶
Load all pages of results from the API.
- load_next_page()¶
Load the next page of results from the API.
Throws AnalyzerError when has_more_records is False.
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total number of available records as reported by the API.
- property values¶
List of unique tracker values in the tracker record list.
- class passivetotal.analyzer.trackers.TrackerRecord(api_response, query=None)¶
Record of an observed trackers.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property category¶
Category or type of web tracker; alias of TrackerRecord.trackertype.
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property hostname¶
Hostname the tracker was observed on.
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
- property tracker¶
Tracker as a Tracker object to aid pivoting to other related IPs or hosts.
- Return type
- property trackertype¶
Type or category of web tracker.
- property value¶
Value of the tracker.
- class passivetotal.analyzer.trackers.TrackerSearchResults(query=None, tracker_type=None, search_type=None)¶
Search results from a tracker query.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- exclude_domains_in(hosts)¶
Filter the list to exclude records where the registered domain of the parent or child is not in a list of hosts. Accepts either a list of strings or a list of analyzer.Hostname objects.
Will apply to parents if direction is parents (from hostpair_parents property) or to children if direction is children(from hostpair_children property).
- Parameters
hosts – List of hostnames to directly match against, as a comma-separated string or a list.
- exclude_hosts_in(hosts)¶
Filter the list to exclude records where the parent or child is contained in not in a list of hosts. Accepts either a list of strings or a list of analyzer.Hostname objects.
Will apply to parents if direction is parents (from hostpair_parents property) or to children if direction is children(from hostpair_children property).
Use exclude_domains_in() to match against only the registered domain.
- Parameters
hosts – List of hostnames to directly match against, as a comma-separated string or a list.
- exclude_tlds_in(tlds)¶
Filter the list to exclude records where the tld of the registered domain of the parent or child is not in a list of tlds. Accepts either a list of strings or a list of analyzer.Hostname objects.
Will apply to parents if direction is parents (from hostpair_parents property) or to children if direction is children(from hostpair_children property).
- Parameters
hosts – List of hostnames to directly match against, as a comma-separated string or a list.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- load_all_pages()¶
Load all pages of results from the API.
- load_next_page()¶
Load the next page of results from the API.
Throws AnalyzerError when has_more_records is False.
- parse(api_response)¶
Implementations must accept an API response and populate themselves with a list of the correct record types.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property query¶
Query used to return this set of search results.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total number of available records; may be greater than the number of results returned by the API.
- class passivetotal.analyzer.trackers.TrackerSearchRecord(api_response, query=None, tracker_type=None, search_type=None)¶
Record representing a single search result in a tracker search.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property duration¶
Length of time record was observed, in days.
Calculates the timedelta between firstseen and lastseen.
- Return type
- property entity¶
Entity where a tracker was found - typically a hostname or an IP address.
Returns the actual value returned by the API in the ‘entity’ response field.
- property firstseen¶
Date & time the record was first seen.
- Return type
datetime
- property firstseen_date¶
Date record was first seen.
- Return type
date
- property firstseen_raw¶
Raw firstseen value returned by the API.
- property host¶
Host where a tracker was found.
Returns either an analyzer.Hostname or analyzer.IPAddress object depending on the type of search which produced this record.
- property lastseen¶
Date & time the record was most recently observed.
- Return type
datetime
- property lastseen_date¶
Date the record was most recently observed.
- Return type
date
- property lastseen_raw¶
Raw lastseen value returned by the API.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property query¶
Query that produced this search result.
- property searchtype¶
Type of search (hostnames or IP addresses) that produced this search result.
This value defines the type of records returned - either hostnames or IPs.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
- property tracker¶
Tracker as a Tracker object to aid pivoting to other related IPs or hosts.
- Return type
- property trackertype¶
Type of tracker found on the entity (host) referenced in this search result.
- class passivetotal.analyzer.trackers.Tracker(trackertype, value)¶
A web tracker with a type and value.
In addition to a simple type/value mapping, this class also provides ips and hostname properties to find other entities that have the same type/value tuple.
- property observations_by_hostname¶
Hostnames of sites where this tracker was observed.
- property observations_by_ip¶
IP addresses of hosts where this tracker was observed.
- property trackertype¶
Type of tracker as defined by RiskIQ analysts.
- property value¶
Tracker value as observed.
Whois Record Lists¶
- class passivetotal.analyzer.whois.WhoisRecords(api_response=None, query=None)¶
List of Whois records.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- property domains¶
Return a set of unique domains in this record list.
- property emails¶
Return a set of unique emails in this record list.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- property names¶
Return a set of unique names in this record list.
- property orgs¶
Return a set of unique org names in this record list.
- parse(api_response)¶
Parse an API response into a list of DomainWhois records.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
Articles Lists¶
- class passivetotal.analyzer.articles.ArticlesList(api_response=None, query=None)¶
List of threat intelligence articles.
Contains a list of
passivetotal.analyzer.articles.Articleobjects.- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- filter_tags(tags)¶
Filtered article list that includes articles with an exact match to one or more tags.
Tests the match_tags method on each article.
- Parameters
tags – String with one or multiple comma-separated tags, or a list
- Return type
- filter_text(text, fields=['tags', 'title', 'summary'])¶
Filtered article list that contain the text in one or more fields.
Searches tags, title and summary by default - set fields param to a smaller list to narrow the search.
- Parameters
text – text to search for
fields – list of fields to search (optional)
- Return type
- static find(query)¶
Query the Articles API endpoint and find articles that match the search term.
- Return type
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
Malware Lists¶
- class passivetotal.analyzer.enrich.MalwareList(api_response=None, query=None)¶
List of malware hashes associated with a host or domain.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- parse(api_response)¶
Parse an API response into a list of records.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- class passivetotal.analyzer.enrich.MalwareRecord(api_response, query=None)¶
Record of malware associated with a host.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property date_collected¶
Date the malware was collected, as a Python date object.
- property hash¶
Hash of the malware sample.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property query¶
Query submitted to the API (typically the hostname or IP address).
- property source¶
Source where the malware sample was obtained.
- property source_url¶
URL to malware sample source.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
Project Lists¶
- class passivetotal.analyzer.projects.ProjectList(api_response=None, query=None)¶
List of Projects with artifacts.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- static find(name_or_guid, visibility=None, owner=None, creator=None, org=None)¶
Obtain a list of all projects that match a name or GUID and optionally other 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
- Return type
passivetotal.analyzer.projects.ProjectList
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- class passivetotal.analyzer.projects.Project(api_response, query=None)¶
Project record with collection of artifacts.
- property artifacts¶
List of artifacts in this project.
- Return type
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property can_edit¶
Whether the project can be edited.
- property collaborators¶
List of user IDs collaborating on this project.
- property created¶
Date this project was created.
- property creator¶
User ID of the project creator.
- property description¶
Description of the project.
- static find(name_or_guid, visibility='analyst', owner=None, creator=None, org=None)¶
Find one project that matches the other criteria.
Raises AnalyzerError if more than one project is found.
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
- property guid¶
Alias for project_guid; project’s unique identifier.
- property is_featured¶
Whether this is a featured project.
- property link¶
Project link.
- property links¶
Dictionary of various links to this project in the UI.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property name¶
Name of the project.
- property organization¶
Organization this project is connected to.
- property owner¶
Owner of the project.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property project_guid¶
Project unique identifier.
- property subscribers¶
List of users who receive notifcations about artifacts in this project.
- property tags¶
List of tags associated with this project.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
- property visibility¶
Visiblity of the project.
Artifact Lists¶
- class passivetotal.analyzer.projects.ArtifactList(api_response=None, query=None)¶
List of artifact entries.
- property all¶
All the records as a list.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return the recordlist as a list of dictionary objects.
- filter(**kwargs)¶
Shortcut for filter_and.
- filter_and(**kwargs)¶
Return only records that match all key/value arguments.
- filter_dateseen_after(date_string: str)¶
Filter only results where the firstseen date property is after a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_before(date_string: str)¶
Filter only results where the lastseen date property is before a specified date.
The date should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_dateseen_between(start_date_string: str, end_date_string: str)¶
Filter only results where the lastseen date property is <= end_date_string and firstseen date property is on or after start_date_string.
Date strings should be parseable by datetime.fromisoformat i.e. ‘2021-01-01’
- filter_fn(fn)¶
Return only records where a function returns true.
- filter_in(**kwargs)¶
Return only records where a field contains one or more values.
- Usage:
filter_in(fieldname=[‘value1’,’value2’]) or filter_in(fieldname=’value1,value2)
- filter_or(**kwargs)¶
Return only records that match any key/value arguments.
- filter_substring(**kwargs)¶
Return only records where a case-insensitive match on the field returns true.
- filter_substring_in(**kwargs)¶
Return only records where a case-insensitive match on any item in a list of substrings returns true for a specific field.
- Usage:
filter_substring_in(fieldname=[‘substring’,’othersub’]) or filter_substring_in(fieldname=’substring,othersub’)
- parse(api_response)¶
Parse an API response.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- sorted_by(field, reverse=False)¶
Return a sorted list.
- Parameters
field – name of the attribute to sort on
reverse – whether to sort in reverse order.
- to_dataframe(**kwargs)¶
Render this object as a Pandas DataFrame.
Implementations may add additional keywords to customize building the data structure.
Default implementation tries to iterate through self and calls to_dataframe on each record with the same parameters passed to this method. If that fails (usually because self isn’t iterable), it uses the as_dict param of self.
- Return type
pandas.DataFrame
- property totalrecords¶
Total number of artifacts.
- class passivetotal.analyzer.projects.Artifact(api_response, query=None)¶
An artifact in a project.
- property alerts¶
Alerts for this indicator, scoped by the date range set in analzyer.set_date_range(). For more arbitrary control, call passivetotal.analyzer.projects.Artifact.get_alerts() directly.
- Return type
passivetotal.analyzer.projects.ArtifactAlerts
- property alerts_available¶
Number of alerts available within the scope of the current date range set in analyzer.set_date_range().
Makes a single query to the API to retrieve one page of results and gets the totalrecords property from that (abbreviated) recordlist.
- property artifact_guid¶
Unique ID of the artifact.
- property as_df¶
Get this object as a Pandas DataFrame.
Use to_dataframe() instead if you need to control how the dataframe is built.
Requires the pandas Python library. Throws AnalyzerError if it is missing. :rtype:
pandas.DataFrame
- property as_dict¶
Return a dictionary representation of the object.
- property created¶
Date the artifact was created.
- property creator¶
User ID that created the artifact.
- delete()¶
Delete this artifact record.
- Rtype bool
Whether the deletion was successful.
- disable_monitoring()¶
Deactivate monitoring on this artifact.
- Rtype bool
Whether monitoring was deactivated successfully.
- enable_monitoring()¶
Activate monitoring on this artifact.
- Rtype bool
Whether monitoring was activated successfully.
- get_alerts(date_start, date_end, abbreviated=False)¶
Get alerts for this indicator.
Loads all pages of alerts by default. Calls with identical params are cached.
- Parameters
start_date – Only return alerts created on or after this date/time
end_date – Only return alerts created before this date/time
abbreviated – Whether to return only the first page with size=0
- Return type
passivetotal.analyzer.projects.ArtifactAlerts
- property guid¶
Unique ID of the artifact; alias of artifact_guid.
- property hostname¶
Hostname object for this artifact, if artifact type is domain.
- property ip¶
IPAddress object for this artifact, if artifact type is IP.
- property is_monitorable¶
Whether the artifact can be monitored.
- property is_monitored¶
Whether the artifact is actively being monitored.
- property links¶
Dictionary of various link types to get more details in the UI.
- match_all(**kwargs)¶
Whether attributes of this record match all the key/value arguments.
- match_any(**kwargs)¶
Whether attributes of this record match any of the key/value arguments.
- property name¶
Name of the artifact (the actual ip, domain, hash, etc.)
- property organization¶
Organization that owns the artifact record.
- property owner¶
User or organization that owns the artifact record.
- property pretty¶
Pretty printed version of this object’s dictionary representation.
- property project_guid¶
Unique ID of the project that contains this artifact.
- property query¶
Name of the artifact (alias for name property).
- property tags_global¶
List of global tags for this artifact.
- property tags_meta¶
Descriptive data about the tags on this artifact.
- property tags_system¶
List of system tags for this artifact.
- property tags_user¶
List of user-defined tags for this artifact.
- to_dataframe()¶
Render this object as a Pandas DataFrame.
- Return type
pandas.DataFrame
- property type¶
Type of the artifact (IP, domain, hash, etc.)
- update_tags(new_tags)¶
Set a new list of tags on this artifact.
The new tag list will overwrite the existing tag list. :rtype bool: Whether tags were updated successfully.