domaintools-api 2.8.0__tar.gz → 2.9.0__tar.gz

{domaintools_api-2.8.0/domaintools_api.egg-info → domaintools_api-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domaintools_api
-Version: 2.8.0
+Version: 2.9.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)

domaintools_api-2.9.0/VERSION

@@ -0,0 +1 @@
+2.9.0

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/_version.py

@@ -20,4 +20,4 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 """
 
-current = "2.8.0"
+current = "2.9.0"

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/api.py

@@ -34,6 +34,7 @@ from domaintools.filters import (
     filter_by_field,
     DTResultFilter,
 )
+from domaintools.exceptions import ServiceUnavailableException, ServiceException
 from domaintools.utils import validate_feeds_parameters
 
 
@@ -163,7 +164,12 @@ class API(object):
         if product != "account-information" and self.rate_limit and not self.limits_set and not self.limits:
             always_sign_api_key_previous_value = self.always_sign_api_key
             header_authentication_previous_value = self.header_authentication
-            self._rate_limit(product)
+            try:
+                self._rate_limit(product)
+            except (ServiceUnavailableException, ServiceException):
+                # If account_information fails (e.g. rate limited itself),
+                # skip client-side rate limiting and proceed with the original call.
+                self.limits_set = True
             # Reset always_sign_api_key and header_authentication to its original
             # User-set values as these might be affected when self.account_information() was executed
             self.always_sign_api_key = always_sign_api_key_previous_value
@@ -1406,3 +1412,71 @@ class API(object):
             cls=FeedsResults,
             **kwargs,
         )
+    
+    def iphotlist(self, **kwargs) -> FeedsResults:
+        """Returns back list of ip hotlist feed.
+        Captures IP addresses that meet strict criteria for both risk level and recent activity, making it ideal for immediate blocking and threat response.
+
+        before: str: Filter for records before the given time value inclusive or time offset relative to now
+
+        after: str: Filter for records after the given time value inclusive or time offset relative to now
+
+        headers: bool: Use in combination with Accept: text/csv headers to control if headers are sent or not
+
+        sessionID: str: A custom string to distinguish between different sessions
+
+        fromBeginning: bool: Requires a sessionID. When used with a new session ID, returns the first hour of data in the time window (rather than the last). Returns an error if the session ID already exists
+
+        top: int: Limits the number of results in the response payload. Primarily intended for testing. When you apply this parameter to risk feeds, results are sorted by all_threats_combined_percent (descending).
+        """
+        validate_feeds_parameters(kwargs)
+        endpoint = kwargs.pop("endpoint", Endpoint.FEED.value)
+        source = ENDPOINT_TO_SOURCE_MAP.get(endpoint).value
+        if (
+            endpoint == Endpoint.DOWNLOAD.value
+            or kwargs.get("output_format", OutputFormat.JSONL.value) != OutputFormat.CSV.value
+        ):
+            # headers param is allowed only in Feed API and CSV format
+            kwargs.pop("headers", None)
+
+        return self._results(
+            f"real-time-ip-hotlist-({source})",
+            f"v1/{endpoint}/iphotlist/",
+            response_path=(),
+            cls=FeedsResults,
+            **kwargs,
+        )
+    
+    def iprisk(self, **kwargs) -> FeedsResults:
+        """Returns back list of domain hotlist feed.
+        Captures all IP addresses that actively host one or more domains, providing risk assessment and enrichment data for each IP address.
+
+        before: str: Filter for records before the given time value inclusive or time offset relative to now
+
+        after: str: Filter for records after the given time value inclusive or time offset relative to now
+
+        headers: bool: Use in combination with Accept: text/csv headers to control if headers are sent or not
+
+        sessionID: str: A custom string to distinguish between different sessions
+
+        fromBeginning: bool: Requires a sessionID. When used with a new session ID, returns the first hour of data in the time window (rather than the last). Returns an error if the session ID already exists
+        
+        top: int: Limits the number of results in the response payload. Primarily intended for testing. When you apply this parameter to risk feeds, results are sorted by all_threats_combined_percent (descending).
+        """
+        validate_feeds_parameters(kwargs)
+        endpoint = kwargs.pop("endpoint", Endpoint.FEED.value)
+        source = ENDPOINT_TO_SOURCE_MAP.get(endpoint).value
+        if (
+            endpoint == Endpoint.DOWNLOAD.value
+            or kwargs.get("output_format", OutputFormat.JSONL.value) != OutputFormat.CSV.value
+        ):
+            # headers param is allowed only in Feed API and CSV format
+            kwargs.pop("headers", None)
+
+        return self._results(
+            f"real-time-ip-risk-({source})",
+            f"v1/{endpoint}/iprisk/",
+            response_path=(),
+            cls=FeedsResults,
+            **kwargs,
+        )

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/base_results.py

@@ -140,7 +140,7 @@ class Results(MutableMapping, MutableSequence):
         wait_for = self._wait_time()
         if self.api.rate_limit and (wait_for is None or self.product == "account-information"):
             data = self._make_request()
-            if data.status_code == 503:  # pragma: no cover
+            if data.status_code == 503 and self.product != "account-information":  # pragma: no cover
                 sleeptime = 60
                 log.info(
                     "503 encountered for [%s] - sleeping [%s] seconds before retrying request.",

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/cli/commands/feeds.py

@@ -79,7 +79,7 @@ def feeds_nad(
         "--headers",
         help="Adds a header to the first line of response when text/csv is set in header parameters",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload. This is ignored in download endpoint",
@@ -159,7 +159,7 @@ def feeds_nod(
         "--headers",
         help="Adds a header to the first line of response when text/csv is set in header parameters",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload. This is ignored in download endpoint",
@@ -227,7 +227,7 @@ def feeds_domainrdap(
         "--domain",
         help="A string value used to filter feed results",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload",
@@ -307,7 +307,7 @@ def feeds_domaindiscovery(
         "--headers",
         help="Adds a header to the first line of response when text/csv is set in header parameters",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload. This is ignored in download endpoint",
@@ -387,7 +387,7 @@ def feeds_noh(
         "--headers",
         help="Adds a header to the first line of response when text/csv is set in header parameters",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload. This is ignored in download endpoint",
@@ -467,7 +467,7 @@ def feeds_domainhotlist(
         "--headers",
         help="Adds a header to the first line of response when text/csv is set in header parameters",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload. This is ignored in download endpoint",
@@ -547,10 +547,170 @@ def feeds_realtime_domain_risk(
         "--headers",
         help="Adds a header to the first line of response when text/csv is set in header parameters",
     ),
-    top: str = typer.Option(
+    top: int = typer.Option(
         None,
         "--top",
         help="Number of results to return in the response payload. This is ignored in download endpoint",
     ),
 ):
     DTCLICommand.run(name=c.FEEDS_REALTIME_DOMAIN_RISK, params=ctx.params)
+
+
+@dt_cli.command(
+    name=c.FEEDS_IPHOTLIST,
+    help=get_cli_helptext_by_name(command_name=c.FEEDS_IPHOTLIST),
+)
+def feeds_iphotlist(
+    ctx: typer.Context,
+    user: str = typer.Option(None, "-u", "--user", help="Domaintools API Username."),
+    key: str = typer.Option(None, "-k", "--key", help="DomainTools API key"),
+    creds_file: str = typer.Option(
+        "~/.dtapi",
+        "-c",
+        "--credfile",
+        help="Optional file with API username and API key, one per line.",
+    ),
+    no_verify_ssl: bool = typer.Option(
+        False,
+        "--no-verify-ssl",
+        help="Skip verification of SSL certificate when making HTTPs API calls",
+    ),
+    no_sign_api_key: bool = typer.Option(
+        False,
+        "--no-sign-api-key",
+        help="Skip signing of api key",
+    ),
+    no_header_authentication: bool = typer.Option(
+        False,
+        "--no-header-auth",
+        help="Don't use header authentication",
+    ),
+    output_format: str = typer.Option(
+        "jsonl",
+        "-f",
+        "--format",
+        help=f"Output format in [{OutputFormat.JSONL.value}, {OutputFormat.CSV.value}]",
+        callback=DTCLICommand.validate_feeds_format_input,
+    ),
+    endpoint: str = typer.Option(
+        Endpoint.FEED.value,
+        "-e",
+        "--endpoint",
+        help=f"Valid endpoints: [{Endpoint.FEED.value}, {Endpoint.DOWNLOAD.value}]",
+        callback=DTCLICommand.validate_endpoint_input,
+    ),
+    sessionID: str = typer.Option(
+        None,
+        "--session-id",
+        help="Unique identifier for the session",
+    ),
+    after: str = typer.Option(
+        None,
+        "--after",
+        help="Start of the time window, relative to the current time in seconds, for which data will be provided",
+        callback=DTCLICommand.validate_after_or_before_input,
+    ),
+    before: str = typer.Option(
+        None,
+        "--before",
+        help="The end of the query window in seconds, relative to the current time, inclusive",
+        callback=DTCLICommand.validate_after_or_before_input,
+    ),
+    fromBeginning: bool = typer.Option(
+        None,
+        "-fb",
+        "--frombeginning",
+        help="Requires a sessionID. When used with a new session ID, returns the first hour of data in the time window (rather than the last). Returns an error if the session ID already exists",
+    ),
+    top: int = typer.Option(
+        None,
+        "--top",
+        help="Number of results to return in the response payload. This is ignored in download endpoint",
+    ),
+    headers: bool = typer.Option(
+        False,
+        "--headers",
+        help="Adds a header to the first line of response when text/csv is set in header parameters",
+    ),
+):
+    DTCLICommand.run(name=c.FEEDS_IPHOTLIST, params=ctx.params)
+
+
+@dt_cli.command(
+    name=c.FEEDS_IPRISK,
+    help=get_cli_helptext_by_name(command_name=c.FEEDS_IPRISK),
+)
+def feeds_iprisk(
+    ctx: typer.Context,
+    user: str = typer.Option(None, "-u", "--user", help="Domaintools API Username."),
+    key: str = typer.Option(None, "-k", "--key", help="DomainTools API key"),
+    creds_file: str = typer.Option(
+        "~/.dtapi",
+        "-c",
+        "--credfile",
+        help="Optional file with API username and API key, one per line.",
+    ),
+    no_verify_ssl: bool = typer.Option(
+        False,
+        "--no-verify-ssl",
+        help="Skip verification of SSL certificate when making HTTPs API calls",
+    ),
+    no_sign_api_key: bool = typer.Option(
+        False,
+        "--no-sign-api-key",
+        help="Skip signing of api key",
+    ),
+    no_header_authentication: bool = typer.Option(
+        False,
+        "--no-header-auth",
+        help="Don't use header authentication",
+    ),
+    output_format: str = typer.Option(
+        "jsonl",
+        "-f",
+        "--format",
+        help=f"Output format in [{OutputFormat.JSONL.value}, {OutputFormat.CSV.value}]",
+        callback=DTCLICommand.validate_feeds_format_input,
+    ),
+    endpoint: str = typer.Option(
+        Endpoint.FEED.value,
+        "-e",
+        "--endpoint",
+        help=f"Valid endpoints: [{Endpoint.FEED.value}, {Endpoint.DOWNLOAD.value}]",
+        callback=DTCLICommand.validate_endpoint_input,
+    ),
+    sessionID: str = typer.Option(
+        None,
+        "--session-id",
+        help="Unique identifier for the session",
+    ),
+    after: str = typer.Option(
+        None,
+        "--after",
+        help="Start of the time window, relative to the current time in seconds, for which data will be provided",
+        callback=DTCLICommand.validate_after_or_before_input,
+    ),
+    before: str = typer.Option(
+        None,
+        "--before",
+        help="The end of the query window in seconds, relative to the current time, inclusive",
+        callback=DTCLICommand.validate_after_or_before_input,
+    ),
+    fromBeginning: bool = typer.Option(
+        None,
+        "-fb",
+        "--frombeginning",
+        help="Requires a sessionID. When used with a new session ID, returns the first hour of data in the time window (rather than the last). Returns an error if the session ID already exists",
+    ),
+    top: int = typer.Option(
+        None,
+        "--top",
+        help="Number of results to return in the response payload. This is ignored in download endpoint",
+    ),
+    headers: bool = typer.Option(
+        False,
+        "--headers",
+        help="Adds a header to the first line of response when text/csv is set in header parameters",
+    ),
+):
+    DTCLICommand.run(name=c.FEEDS_IPRISK, params=ctx.params)

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/cli/constants.py

@@ -48,3 +48,5 @@ FEEDS_DOMAINHOTLIST = "domainhotlist"
 FEEDS_DOMAINRDAP = "domainrdap"
 FEEDS_DOMAINDISCOVERY = "domaindiscovery"
 FEEDS_REALTIME_DOMAIN_RISK = "realtime_domain_risk"
+FEEDS_IPHOTLIST = "iphotlist"
+FEEDS_IPRISK = "iprisk"

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/cli/utils.py

@@ -65,10 +65,12 @@ _command_help_mapper = {
     c.FEEDS_NAD: "Returns back newly active domains feed.",
     c.FEEDS_NOD: "Returns back newly observed domains feed.",
     c.FEEDS_NOH: "Returns back newly observed hosts feed.",
-    c.FEEDS_DOMAINHOTLIST: "Returns domaint hotlist feed.",
+    c.FEEDS_DOMAINHOTLIST: "Returns domain hotlist feed.",
     c.FEEDS_DOMAINRDAP: "Returns changes to global domain registration information, populated by the Registration Data Access Protocol (RDAP).",
     c.FEEDS_DOMAINDISCOVERY: "Returns new domains as they are either discovered in domain registration information, observed by our global sensor network, or reported by trusted third parties.",
     c.FEEDS_REALTIME_DOMAIN_RISK: "Returns realtime domain risk information for apex-level domains, regardless of observed traffic.",
+    c.FEEDS_IPHOTLIST: "Returns ip hotlist feed.",
+    c.FEEDS_IPRISK: "Returns ip risk feed.",
 }
 
 

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools/constants.py

@@ -38,6 +38,10 @@ RTTF_PRODUCTS_LIST = [
     "real-time-domain-risk-(s3)",
     "real-time-domain-discovery-feed-(api)",
     "real-time-domain-discovery-feed-(s3)",
+    "real-time-ip-hotlist-(api)",
+    "real-time-ip-hotlist-(s3)",
+    "real-time-ip-risk-(api)",
+    "real-time-ip-risk-(s3)",
 ]
 
 RTTF_PRODUCTS_CMD_MAPPING = {
@@ -55,6 +59,10 @@ RTTF_PRODUCTS_CMD_MAPPING = {
     "real-time-domain-risk-(s3)": "realtime_domain_risk",
     "real-time-domain-discovery-feed-(api)": "domaindiscovery",
     "real-time-domain-discovery-feed-(s3)": "domaindiscovery",
+    "real-time-ip-hotlist-(api)": "iphotlist",
+    "real-time-ip-hotlist-(s3)": "iphotlist",
+    "real-time-ip-risk-(api)": "iprisk",
+    "real-time-ip-risk-(s3)": "iprisk",
 }
 
 SPECS_MAPPING = {

{domaintools_api-2.8.0 → domaintools_api-2.9.0/domaintools_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domaintools_api
-Version: 2.8.0
+Version: 2.9.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/domaintools_api.egg-info/SOURCES.txt

@@ -42,5 +42,6 @@ tests/test_cli.py
 tests/test_decorators.py
 tests/test_docstring_patcher.py
 tests/test_filters.py
+tests/test_iris_enrich_account_info.py
 tests/test_request_validator.py
 tests/test_utils.py

{domaintools_api-2.8.0 → domaintools_api-2.9.0}/tests/test_api.py

@@ -827,6 +827,43 @@ def test_domain_hotlist():
         assert "proximity_risk" in feed_result.keys()
         assert "overall_risk" in feed_result.keys()
 
+@vcr.use_cassette
+def test_ip_hotlist():
+    results = feeds_api.iphotlist(after="-60", top=5)
+    for response in results.response():
+        assert results.status == 200
+
+        response = response.strip()
+        assert response is not None
+
+        feed_result = json.loads(response)
+        assert "timestamp" in feed_result.keys()
+        assert "ip" in feed_result.keys()
+        assert "asn" in feed_result.keys()
+        assert "organization" in feed_result.keys()
+        assert "total_domains" in feed_result.keys()
+        assert "all_threats_combined_count" in feed_result.keys()
+        assert "all_threats_combined_percent" in feed_result.keys()
+
+
+@vcr.use_cassette
+def test_ip_risk():
+    results = feeds_api.iprisk(after="-60", top=5)
+    for response in results.response():
+        assert results.status == 200
+
+        response = response.strip()
+        assert response is not None
+
+        feed_result = json.loads(response)
+        assert "timestamp" in feed_result.keys()
+        assert "ip" in feed_result.keys()
+        assert "asn" in feed_result.keys()
+        assert "organization" in feed_result.keys()
+        assert "total_domains" in feed_result.keys()
+        assert "all_threats_combined_count" in feed_result.keys()
+        assert "all_threats_combined_percent" in feed_result.keys()
+
 
 @vcr.use_cassette
 def test_feeds_endpoint_should_raise_error_if_signed_api_key_is_used():
@@ -835,3 +872,4 @@ def test_feeds_endpoint_should_raise_error_if_signed_api_key_is_used():
         feeds_api.domaindiscovery(after="-60")
 
     assert str(excinfo.value) == "Real Time Threat Feeds do not support signed API keys."
+

domaintools_api-2.9.0/tests/test_iris_enrich_account_info.py

@@ -0,0 +1,142 @@
+"""Test that iris_enrich only triggers account_information once per API instance."""
+
+from unittest.mock import patch, MagicMock
+
+from domaintools import API
+from domaintools.exceptions import ServiceUnavailableException
+
+
+def test_iris_enrich_does_not_repeat_account_info_call():
+    """Confirm account_information is fetched only once for multiple iris_enrich calls on same API instance."""
+    # Reset class-level state that may have been set by previous tests
+    API.limits = {}
+    API.limits_set = False
+
+    api = API("test_user", "test_key", rate_limit=True)
+
+    # Fake account info response
+    fake_account_data = {
+        "response": {
+            "products": [
+                {"id": "iris-enrich", "per_minute_limit": 10, "per_hour_limit": 100}
+            ]
+        }
+    }
+
+    # Fake iris-enrich response
+    fake_enrich_data = {
+        "response": {
+            "results": [{"domain": "google.com"}],
+            "results_count": 1,
+            "missing_domains": [],
+            "limit_exceeded": False,
+        }
+    }
+
+    call_log = []
+
+    with patch("domaintools.base_results.Client") as mock_client:
+        mock_session = MagicMock()
+        mock_client.return_value.__enter__ = MagicMock(return_value=mock_session)
+        mock_client.return_value.__exit__ = MagicMock(return_value=False)
+
+        def fake_get(url, **kwargs):
+            call_log.append(("GET", url))
+            resp = MagicMock()
+            resp.status_code = 200
+            if "/v1/account" in url:
+                resp.json.return_value = fake_account_data
+            return resp
+
+        def fake_post(url, **kwargs):
+            call_log.append(("POST", url))
+            resp = MagicMock()
+            resp.status_code = 200
+            resp.json.return_value = fake_enrich_data
+            return resp
+
+        mock_session.get.side_effect = fake_get
+        mock_session.post.side_effect = fake_post
+
+        # First call - should trigger account_information (GET /v1/account)
+        api.iris_enrich("google.com")
+        # Second call - should NOT trigger account_information again
+        api.iris_enrich("amazon.com")
+
+    # Count how many times /v1/account was called
+    account_calls = [c for c in call_log if "/v1/account" in c[1]]
+    enrich_calls = [c for c in call_log if "/v1/iris-enrich" in c[1]]
+
+    assert len(account_calls) == 1, (
+        f"Expected exactly 1 account_information call, got {len(account_calls)}. "
+        f"Full call log: {call_log}"
+    )
+    assert len(enrich_calls) == 2, (
+        f"Expected exactly 2 iris_enrich calls, got {len(enrich_calls)}. "
+        f"Full call log: {call_log}"
+    )
+
+
+def test_iris_enrich_succeeds_when_account_info_is_rate_limited():
+    """Verify that iris_enrich proceeds normally even if account_information returns a 503."""
+    # Reset class-level state that may have been set by previous tests
+    API.limits = {}
+    API.limits_set = False
+
+    api = API("test_user", "test_key", rate_limit=True)
+
+    # Fake iris-enrich response
+    fake_enrich_data = {
+        "response": {
+            "results": [{"domain": "google.com"}],
+            "results_count": 1,
+            "missing_domains": [],
+            "limit_exceeded": False,
+        }
+    }
+
+    call_log = []
+
+    with patch("domaintools.base_results.Client") as mock_client, \
+         patch("domaintools.base_results.time.sleep"):
+        mock_session = MagicMock()
+        mock_client.return_value.__enter__ = MagicMock(return_value=mock_session)
+        mock_client.return_value.__exit__ = MagicMock(return_value=False)
+
+        def fake_get(url, **kwargs):
+            call_log.append(("GET", url))
+            resp = MagicMock()
+            if "/v1/account" in url:
+                # Simulate a 503 rate limit on account_information
+                resp.status_code = 503
+                resp.json.return_value = {"error": {"message": "Rate limit exceeded"}}
+            else:
+                resp.status_code = 200
+                resp.json.return_value = {}
+            return resp
+
+        def fake_post(url, **kwargs):
+            call_log.append(("POST", url))
+            resp = MagicMock()
+            resp.status_code = 200
+            resp.json.return_value = fake_enrich_data
+            return resp
+
+        mock_session.get.side_effect = fake_get
+        mock_session.post.side_effect = fake_post
+
+        # This should NOT raise an exception despite account_info returning 503
+        result = api.iris_enrich("google.com")
+
+    # Verify the iris_enrich call succeeded
+    enrich_calls = [c for c in call_log if "/v1/iris-enrich" in c[1]]
+    assert len(enrich_calls) == 1, (
+        f"Expected 1 iris_enrich call, got {len(enrich_calls)}. Full call log: {call_log}"
+    )
+
+    # Verify limits_set was set to True so it won't retry account_info
+    assert api.limits_set is True
+
+    # Verify the result contains expected data
+    assert result["results_count"] == 1
+    assert result["results"][0]["domain"] == "google.com"

domaintools_api-2.8.0/VERSION

@@ -1 +0,0 @@
-2.8.0