- Significant improvements to the Attack Surface Intelligence (ASI) documentation. Added class references for ASI, CTI and vulnerability intelligence to ensure the docs and links generated properly. Introduced a new Sphinx module to help generate inline table-of-contents for complex classes. Corrected typos in docstrings and ensured consistent type references when methods returned RecordList-type objects.
- Implemented new config files for readthedocs to align with current documentation practices.
- New
whois_history
property ofHostname
andIPAddress
entities gives direct access to historical Whois (ownership) records. Includes more consistent implementation of RecordList functionality and better pandas dataframe support for both historical Whois and field-level Whois searches. - New
impacted_attack_surfaces
property of vulnerability articles (VulnArticle
) filters the list of third-party vendors to only those with at least one observation. The Illuminate API returns all attack surfaces associated with an API key regardless of whether they are impacted; the complete list is still available in theattack_surfaces
property. Also updated theinfo
view of the Pandas dataframe on a vulnerability article so theimpacts
column shows the count of impacted attack surfaces.
- Correctly sum insight and observation counts when accessing Attack Surface Insights
(ASIs) across multiple severity levels. Previously the
active_insight_count
,total_insight_count
, andtotal_observations
properties of theall_active_insights
record list were only counting high-priority insights. - Fixed issue that caused an exception when trying to generate a dictionary view of an AttackSurfaceComponent (detection).
- Removed reference to non-existant field in
VulnArticle
that was causing an exception when rendering a vulnerability article as a dictionary with theas_dict
property. - Handle vuln articles with no impacted assets without raising an exception.
certificates
property ofanalyzer.Hostname
objects now returns same list of SSL certificates as the UI, enabled by a CertificateField search with the field set toname
. This activates special-case functionality in the API that performs a substring search for a hostname across both subjectAlternativeNames and subjectCommonName fields The previous version only looked at thesubjectAlternativeNames
field. A more narrow search across specific fields is still available by instantiating ananalyzer.CertificateField
object directly.- Docs now show current version number and link to this changelog hosted on GitHub.
- New example notebook explaining how to use projects, artifacts, and alerts.
- New filter for lists of substrings on all RecordList objects.
- New API library for Trackers to support recently-introduced endpoints that enable
pagination. Ensured pagination for
analyzer.Tracker
objects works correctly with new API library. It is now possible to download hundreds of thousands of tracker search results by accessing theobservations_by_ip
orobservations_by_hostname
property of a Tracker.
- Add missing docstring for filter_date* functions on RecordList objects.
- Resolved issue that blocked filtering of project alerts with filter* functions.
- Fixed dataframe column names on vulnerability objects to match properties.
- Fixed issue that broke Illuminate ASI and Vuln Intel analyzer modules in Python 3.7 and earlier due to a missing param on the lru_cache decorator required in those versions.
- Fixed default end date behavior in analyzer to include a full day rather than stopping at midnight "today". Was causing records with a last-seen date equal to the current date to be excluded from analyzer record list objects (including pDNS, certificates, and anything else that supported date-bounded queries).
- Support for new RiskIQ Illuminate Vulnerability Intelligence API endpoints in core API library.
- New
cves
property of AttackSurface objects finds vulnerabilities impacting assets within that attack surface. Works identically for the primary (your own) attack surface and third-party attack surfaces. - New
AttackSurfaceCVEs
record list to contain a list ofAttackSurfaceCVE
objects, with properties to access the vulnerability report, RiskIQ priority score, and list of impacted assets. - New
VulnArticle
object to provide details on a CVE and discover the list of third-party vendors with assets impacted by the vuln. Custom views in the article'sto_dataframe()
method render dataframes focused on article references, component detections, and third-party impacts. - New helper method
analyzer.AttackSurface()
to directly load an attack surface. Works without params to load the main attack surface, with an ID to load a third-party vendor attack surface by ID, or with a string to find an attack surface by vendor name. - Re-organized Illuminate-specific code in the
analyzer
module into distinct files located under a subpackage. Existing imports in client code should not be impacted.
- Publishes pull request #38 "Remove ez_setup dependancy."
- Removed strict checking on tracker type to permit querying by arbitrary tracker types. Updated list of common trackers. Added searchType param to docs to reflect API's capability of returning either hostnames or addresses.
- New methods to search trackers in the
analyzer
module, includingtracker_references
property onHostname
andIPAddress
objects to find other sites referencing the focus host in their tracker values. - New
analyzer.Tracker
top-level entity withobservations_by_ip
andobservations_by_hostname
properties to find other hosts with the same tracker type and value. - New
filter_fn
method on all RecordList objects enables filtering a list by an arbitrary function. Helps reduce code duplication and enables more advanced filtering. - Monitoring API endpoint support in the core library, and new
alerts
property on project artifacts to easily retrieve the list of new alerts for an artifact in a project. Handles pagination automatically and returns results in new analyzer objects to enable standard filtering and data representation (i.e.as_dict
andas_df
). - Small change to the
get_object
method to tolerate passing it objects that are alreadyanalyzer.Hostname
oranalyzer.IPAddress
objects. - New
is_ip
andis_hostname
methods on bothHostname
andIPAddress
objects to simplify code that operates against a list of hosts that may include objects of both types. - New methods on Tracker search results and Hostpair results to exclude records with hostnames, domains or tlds in a given list. This helps refine results to focus on "foreign" sites and enables direct application of proven phishing site detection use cases.
- Fixed incorrect constant reference in trackers API (by removing strict checking on tracker type).
- Fixed broken
age
property on Articles that was also causingas_df
andas_dict
to fail. Likely caused by missing time zone info in dates returned from the API.
- Better support for unit tests in client libraries with ability to set a session to override default request methods.
- Add flexibility to library class instantiation to prefer keyword parameters over config file keys.
- Support for new
create_date
Articles API data field and query parameter. Enables searching for most recent articles instead of returning all of them at once, and provides visiblity to situations where an article published in the past was recently added to the Articles collection.
- Previously, calls to
analyzer.AllArticles()
would return all articles without a date limit. Now, it will return only articles created after the starting date set withanalyzer.set_date_range()
. The current module-level default for all date-bounded queries is 90 days back, so now this function will return all articles created in the last 90 days. age
property of an Article analyzer object is now based oncreate_date
instead of publish date.
[ none ]
- Send new request headers for metrics and troubleshooting with the
set_context
method on theanalyzer
module and within the core API request libs. - Abstract package version into a distinct file to consolidate updates and ensure
consistency across docs and pypi. Add
get_version
method toanalyzer
module for easy access to the current version number.
- Adds support for the Illuminate CTI module with Intel Profile API library
calls and
analzyer
objects. Includes support for all API parameters and handles pagination automatically. - Adds support for Illuminate Attack Surface Intelligence including third-party attack surfaces.
- Ability to filter all RecordList analyzer objects by a list of values using
new
filter_in
method. - Ability to filter all RecordList analyzer objects by a case-insensitive
substring search using new
filter_substring
method. Especially useful for filtering a list of Attack Surface Insights or Attack Surface Third-Party vendors.
- Filter methods on RecordList objects now consistently return lists instead of filters.
- Property return NotImplemented type for base methods.
- Ensure strings are returned for firstseen / lastseen dates in certificates
property. Was causing json encoding errors when trying to encode
certificates.as_dict
. - Add missing
duration
property to pDNSresolutions.as_dict
- Fixed save_to_project() API call; was broken after introduction of new API exception types.
- Raise
AnalyzerAPIError
when a non-200 response is returned from the API. - Add SSL hash field to list of SSL fields in dictionary output for more convenient integrations.
- Add firstseen and lastseen dates to SSL Certificate records.
- Optional support for the Pandas data analysis library. Adds as_df property to all Analyzer objects to render the object as a Pandas dataframe.
- Add option to specify module-level date ranges with
datetime
objects for easier integration with other libraries. - Subdomain API support with the
subdomains
property of Hostname objects.
is_ip()
regex fix to avoid matching on hostnames with embedded IPs.- Fixed broken
available
property on summary objects. - Fixed missing publish date on Articles
- Throw
AnalyzerError
when a hostname cannot be resolved to an IP - Add links to summary card as_dict method
- Added missing docstring for
services
property - Fixed various issues with
as_dict
property to ensure only serializable types made it into the dictionary. - Ensured Projects would load by GUID regardless of visiblity.
- Removed a partially-implemented str method in
MalwareList
method - Ensured all str methods in
analyzer
objects always return a string - Upserting an artifact triggered an API error when setting a tag
- Ensure
summary
property returns ints, not None, when fields are missing - Properly handle defanged ip addresses
- Exclude Nones from sets in various properties to avoid problems with
NoneTypes
- Added an
as_dict
property across all Analyzer objects to simplify integration with other systems. Returns a dictionary representation of the object or the list. - New
projects
attribute on IPAddress and Hostname objects returns list of projects that contain that host as an artifact. - New
analyzer.set_project()
method on the Analyzer module to set an active project by name or guid, and newadd_to_project()
methods on Analyzer objects to quickly add the object to the active project. - Direct methods on new
Project
andArtifact
objects to directly manipulate monitoring status and tags.
- Added missing ArtifactsRequest to package-level imports
- Early implementation of exception handling for SSL properties; analyzer. AnalyzerError now available as a base exception type.
- SSL certs will now populate their own
ip
property, accessing the SSL history API when needed to fill in the details. - New
iphistory
property of SSL certs to support theip
property and give direct access to the historial results. - Used the
tldextract
Python library to expose useful properties on Hostname objects such astld
,registered_domain
, andsubdomain
- Change default days back for date-aware searches to 90 days (was 30)
- Reject IPs as strings for Hostname objects
- Ensure IPs are used when instantiating IPAddress objects
- Defang hostnames (i.e.
analyzer.Hostname('api[.]riskiq[.]net')
) - Support for Articles as a property of Hostnames and IPs, with autoloading
for detailed fields including indicators, plus easy access to a list of all
articles directly from
analyzer.AllArticles()
- Support for Malware as a property of Hostnames and IPs
- Better coverage of pretty printing and dictionary representation across analyzer objects.
- Exception handling when no details found for an SSL certificate.
- Proper handling of None types that may have prevented result caching