- 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_historyproperty ofHostnameandIPAddressentities 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_surfacesproperty 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_surfacesproperty. Also updated theinfoview of the Pandas dataframe on a vulnerability article so theimpactscolumn 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_observationsproperties of theall_active_insightsrecord 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
VulnArticlethat was causing an exception when rendering a vulnerability article as a dictionary with theas_dictproperty. - Handle vuln articles with no impacted assets without raising an exception.
certificatesproperty ofanalyzer.Hostnameobjects 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 thesubjectAlternativeNamesfield. A more narrow search across specific fields is still available by instantiating ananalyzer.CertificateFieldobject 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.Trackerobjects works correctly with new API library. It is now possible to download hundreds of thousands of tracker search results by accessing theobservations_by_iporobservations_by_hostnameproperty 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
cvesproperty 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
AttackSurfaceCVEsrecord list to contain a list ofAttackSurfaceCVEobjects, with properties to access the vulnerability report, RiskIQ priority score, and list of impacted assets. - New
VulnArticleobject 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
analyzermodule 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
analyzermodule, includingtracker_referencesproperty onHostnameandIPAddressobjects to find other sites referencing the focus host in their tracker values. - New
analyzer.Trackertop-level entity withobservations_by_ipandobservations_by_hostnameproperties to find other hosts with the same tracker type and value. - New
filter_fnmethod 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
alertsproperty 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_dictandas_df). - Small change to the
get_objectmethod to tolerate passing it objects that are alreadyanalyzer.Hostnameoranalyzer.IPAddressobjects. - New
is_ipandis_hostnamemethods on bothHostnameandIPAddressobjects 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
ageproperty on Articles that was also causingas_dfandas_dictto 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_dateArticles 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. ageproperty of an Article analyzer object is now based oncreate_dateinstead of publish date.
[ none ]
- Send new request headers for metrics and troubleshooting with the
set_contextmethod on theanalyzermodule 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_versionmethod toanalyzermodule for easy access to the current version number.
- Adds support for the Illuminate CTI module with Intel Profile API library
calls and
analzyerobjects. 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_inmethod. - Ability to filter all RecordList analyzer objects by a case-insensitive
substring search using new
filter_substringmethod. 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
durationproperty to pDNSresolutions.as_dict - Fixed save_to_project() API call; was broken after introduction of new API exception types.
- Raise
AnalyzerAPIErrorwhen 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
datetimeobjects for easier integration with other libraries. - Subdomain API support with the
subdomainsproperty of Hostname objects.
is_ip()regex fix to avoid matching on hostnames with embedded IPs.- Fixed broken
availableproperty on summary objects. - Fixed missing publish date on Articles
- Throw
AnalyzerErrorwhen a hostname cannot be resolved to an IP - Add links to summary card as_dict method
- Added missing docstring for
servicesproperty - Fixed various issues with
as_dictproperty 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
MalwareListmethod - Ensured all str methods in
analyzerobjects always return a string - Upserting an artifact triggered an API error when setting a tag
- Ensure
summaryproperty 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_dictproperty across all Analyzer objects to simplify integration with other systems. Returns a dictionary representation of the object or the list. - New
projectsattribute 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
ProjectandArtifactobjects 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
ipproperty, accessing the SSL history API when needed to fill in the details. - New
iphistoryproperty of SSL certs to support theipproperty and give direct access to the historial results. - Used the
tldextractPython 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