domaintools-api 2.3.0__tar.gz → 2.4.0__tar.gz

{domaintools_api-2.3.0/domaintools_api.egg-info → domaintools_api-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: domaintools_api
-Version: 2.3.0
+Version: 2.4.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)
@@ -40,12 +40,13 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx
+Requires-Dist: httpx==0.28.1
 Requires-Dist: rich
 Requires-Dist: typer
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: mock; extra == "test"
+Dynamic: license-file
 
 ![domaintools](https://github.com/DomainTools/python_api/raw/main/artwork/logo.png)
 ===================

domaintools_api-2.4.0/VERSION

@@ -0,0 +1 @@
+2.4.0

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/_version.py

@@ -20,4 +20,4 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 """
 
-current = "2.3.0"
+current = "2.4.0"

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/api.py

@@ -411,38 +411,6 @@ class API(object):
             **kwargs,
         )
 
-    def phisheye(self, query, days_back=None, **kwargs):
-        """Returns domain results for the specified term for today or the specified number of days_back.
-        Terms must be setup for monitoring via the web interface: https://research.domaintools.com/phisheye.
-
-        NOTE: Properties of a domain are only provided if we have been able to obtain them.
-              Many domains will have incomplete data because that information isn't available in their Whois records,
-              or they don't have DNS results for a name server or IP address.
-        """
-        return self._results(
-            "phisheye",
-            "/v1/phisheye",
-            query=query,
-            days_back=days_back,
-            items_path=("domains",),
-            **kwargs,
-        )
-
-    def phisheye_term_list(self, include_inactive=False, **kwargs):
-        """Provides a list of terms that are set up for this account.
-        This call is not charged against your API usage limit.
-
-        NOTE: The terms must be configured in the PhishEye web interface: https://research.domaintools.com/phisheye.
-              There is no API call to set up the terms.
-        """
-        return self._results(
-            "phisheye_term_list",
-            "/v1/phisheye/term-list",
-            include_inactive=include_inactive,
-            items_path=("terms",),
-            **kwargs,
-        )
-
     def iris(
         self,
         domain=None,
@@ -1065,7 +1033,21 @@ class API(object):
         )
 
     def nod(self, **kwargs) -> FeedsResults:
-        """Returns back list of the newly observed domains feed"""
+        """Returns back list of the newly observed domains feed.
+        Apex-level domains (e.g. example.com but not www.example.com) that we observe for the first time, and have not observed previously with our global DNS sensor network.
+
+        domain: str: Filter for an exact domain or a substring contained within a domain by prefixing or suffixing your substring with "*". Check the documentation for examples
+
+        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
+
+        top: int: Limit the number of results to the top N, where N is the value of this parameter.
+        """
         validate_feeds_parameters(kwargs)
         endpoint = kwargs.pop("endpoint", Endpoint.FEED.value)
         source = ENDPOINT_TO_SOURCE_MAP.get(endpoint)
@@ -1082,7 +1064,22 @@ class API(object):
         )
 
     def nad(self, **kwargs) -> FeedsResults:
-        """Returns back list of the newly active domains feed"""
+        """Returns back list of the newly active domains feed. Contains domains that have been observed after having not been seen for at least 10 days in passive DNS.
+        Apex-level domains (e.g. example.com but not www.example.com) that we observe based on the latest lifecycle of the domain. A domain may be seen either for the first time ever, or again after at least 10 days of inactivity (no observed resolutions in DNS).
+        Populated with our global passive DNS (pDNS) sensor network.
+
+        domain: str: Filter for an exact domain or a substring contained within a domain by prefixing or suffixing your substring with "*". Check the documentation for examples
+
+        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
+
+        top: int: Limit the number of results to the top N, where N is the value of this parameter.
+        """
         validate_feeds_parameters(kwargs)
         endpoint = kwargs.pop("endpoint", Endpoint.FEED.value)
         source = ENDPOINT_TO_SOURCE_MAP.get(endpoint).value
@@ -1099,7 +1096,22 @@ class API(object):
         )
 
     def domainrdap(self, **kwargs) -> FeedsResults:
-        """Returns changes to global domain registration information, populated by the Registration Data Access Protocol (RDAP)"""
+        """Returns changes to global domain registration information, populated by the Registration Data Access Protocol (RDAP).
+        Compliments the 5-Minute WHOIS Feed as registries and registrars switch from Whois to RDAP.
+        Contains parsed and raw RDAP-format domain registration data, emitted as soon as they are collected and parsed into a normalized structure.
+
+        domain: str: Filter for an exact domain or a substring contained within a domain by prefixing or suffixing your substring with "*". Check the documentation for examples
+
+        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
+
+        top: int: Limit the number of results to the top N, where N is the value of this parameter.
+        """
         validate_feeds_parameters(kwargs)
         endpoint = kwargs.pop("endpoint", Endpoint.FEED.value)
         source = ENDPOINT_TO_SOURCE_MAP.get(endpoint).value
@@ -1113,7 +1125,22 @@ class API(object):
         )
 
     def domaindiscovery(self, **kwargs) -> FeedsResults:
-        """Returns new domains as they are either discovered in domain registration information, observed by our global sensor network, or reported by trusted third parties"""
+        """Returns new domains as they are either discovered in domain registration information, observed by our global sensor network, or reported by trusted third parties".
+        Contains domains that are newly-discovered by Domain Tools in both passive and active DNS sources, emitted as soon as they are first observed.
+        New domains as they are either discovered in domain registration information, observed by our global sensor network, or reported by trusted third parties.
+
+        domain: str: Filter for an exact domain or a substring contained within a domain by prefixing or suffixing your substring with "*". Check the documentation for examples
+
+        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
+
+        top: int: Limit the number of results to the top N, where N is the value of this parameter.
+        """
         validate_feeds_parameters(kwargs)
         endpoint = kwargs.pop("endpoint", Endpoint.FEED.value)
         source = ENDPOINT_TO_SOURCE_MAP.get(endpoint).value
@@ -1128,3 +1155,35 @@ class API(object):
             cls=FeedsResults,
             **kwargs,
         )
+
+    def noh(self, **kwargs) -> FeedsResults:
+        """Returns back list of the newly observed hostnames feed.
+        Contains fully qualified domain names (i.e. host names) that have never been seen before in passive DNS, emitted as soon as they are first observed.
+        Hostname resolutions that we observe for the first time with our global DNS sensor network.
+
+        domain: str: Filter for an exact domain or a substring contained within a domain by prefixing or suffixing your substring with "*". Check the documentation for examples
+
+        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
+
+        top: int: Limit the number of results to the top N, where N is the value of this parameter.
+        """
+        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"newly-observed-hosts-feed-({source})",
+            f"v1/{endpoint}/noh/",
+            response_path=(),
+            cls=FeedsResults,
+            **kwargs,
+        )

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/cli/commands/__init__.py

@@ -2,6 +2,5 @@ from .accounts import *
 from .iris import *
 from .domains import *
 from .ips import *
-from .phisheye import *
 from .detects import *
 from .feeds import *

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/cli/commands/feeds.py

@@ -314,3 +314,83 @@ def feeds_domaindiscovery(
     ),
 ):
     DTCLICommand.run(name=c.FEEDS_DOMAINDISCOVERY, params=ctx.params)
+
+
+@dt_cli.command(
+    name=c.FEEDS_NOH,
+    help=get_cli_helptext_by_name(command_name=c.FEEDS_NOH),
+)
+def feeds_noh(
+    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",
+    ),
+    header_authentication: bool = typer.Option(
+        True,
+        "--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,
+    ),
+    domain: str = typer.Option(
+        None,
+        "-d",
+        "--domain",
+        help="A string value used to filter feed results",
+    ),
+    headers: bool = typer.Option(
+        False,
+        "--headers",
+        help="Adds a header to the first line of response when text/csv is set in header parameters",
+    ),
+    top: str = 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_NOH, params=ctx.params)

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/cli/constants.py

@@ -39,12 +39,9 @@ IRIS_DETECT_MANAGE_WATCHLIST_DOMAINS = "iris_detect_manage_watchlist_domains"
 IRIS_DETECT_ESCALATE_DOMAINS = "iris_detect_escalate_domains"
 IRIS_DETECT_IGNORED_DOMAINS = "iris_detect_ignored_domains"
 
-# phisheye
-PHISHEYE = "phisheye"
-PHISHEYE_TERM_LIST = "phisheye_term_list"
-
 # feeds
 FEEDS_NAD = "nad"
 FEEDS_NOD = "nod"
+FEEDS_NOH = "noh"
 FEEDS_DOMAINRDAP = "domainrdap"
 FEEDS_DOMAINDISCOVERY = "domaindiscovery"

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/cli/utils.py

@@ -29,25 +29,6 @@ def _iris_investigate_helptext():
     """
 
 
-def _phisheye_helptext():
-    return """
-        Returns domain results for the specified term for today or the specified number of days_back. Terms must be setup for monitoring via the web interface: https://research.domaintools.com/phisheye. \n
-
-        NOTE: Properties of a domain are only provided if we have been able to obtain them. \n
-        Many domains will have incomplete data because that information isn't available in their Whois records,
-        or they don't have DNS results for a name server or IP address.
-    """
-
-
-def _phisheye_termlist():
-    return """
-        Provides a list of terms that are set up for this account. This call is not charged against your API usage limit.
-
-        NOTE: The terms must be configured in the PhishEye web interface: https://research.domaintools.com/phisheye. \n
-        There is no API call to set up the terms.
-    """
-
-
 _command_help_mapper = {
     c.ACCOUNT_INFORMATION: "Provides a snapshot of your accounts current API usage.",
     c.AVAILABLE_API_CALLS: "Provides a list of api calls that you can use based on your account information.",
@@ -71,8 +52,6 @@ _command_help_mapper = {
     c.REVERSE_WHOIS: "Provides list of one or more terms to search for in the Whois record, as a Python list or separated with the pipe character ( | ).",
     c.WHOIS: "Pass in a domain name or an IP address to perform a whois lookup.",
     c.WHOIS_HISTORY: "Retrieve historical Whois records of a given domain name.",
-    c.PHISHEYE: _phisheye_helptext(),
-    c.PHISHEYE_TERM_LIST: _phisheye_termlist(),
     c.IRIS: "Performs a search for the provided search terms ANDed together, returning the pivot engine row data for the resulting domains.",
     c.RISK: "Returns back the risk score for a given domain.",
     c.RISK_EVIDENCE: "Returns back the detailed risk evidence associated with a given domain.",
@@ -84,6 +63,7 @@ _command_help_mapper = {
     c.IRIS_DETECT_IGNORED_DOMAINS: "Returns back a list of ignored domains in Iris Detect based on the provided filters.",
     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_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.",
 }

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools/constants.py

@@ -28,6 +28,8 @@ FEEDS_PRODUCTS_LIST = [
     "newly-active-domains-feed-(s3)",
     "newly-observed-domains-feed-(api)",
     "newly-observed-domains-feed-(s3)",
+    "newly-observed-hosts-feed-(api)",
+    "newly-observed-hosts-feed-(s3)",
     "domain-registration-data-access-protocol-feed-(api)",
     "domain-registration-data-access-protocol-feed-(s3)",
     "real-time-domain-discovery-feed-(api)",

{domaintools_api-2.3.0 → domaintools_api-2.4.0/domaintools_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: domaintools_api
-Version: 2.3.0
+Version: 2.4.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)
@@ -40,12 +40,13 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx
+Requires-Dist: httpx==0.28.1
 Requires-Dist: rich
 Requires-Dist: typer
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: mock; extra == "test"
+Dynamic: license-file
 
 ![domaintools](https://github.com/DomainTools/python_api/raw/main/artwork/logo.png)
 ===================

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools_api.egg-info/SOURCES.txt

@@ -25,7 +25,6 @@ domaintools/cli/commands/domains.py
 domaintools/cli/commands/feeds.py
 domaintools/cli/commands/ips.py
 domaintools/cli/commands/iris.py
-domaintools/cli/commands/phisheye.py
 domaintools_api.egg-info/PKG-INFO
 domaintools_api.egg-info/SOURCES.txt
 domaintools_api.egg-info/dependency_links.txt

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/domaintools_api.egg-info/requires.txt

@@ -1,4 +1,4 @@
-httpx
+httpx==0.28.1
 rich
 typer
 

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/pyproject.toml

@@ -4,7 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "domaintools_api"
-dependencies = ["httpx", "rich", "typer"]
+dependencies = [
+    "httpx==0.28.1",
+    "rich",
+    "typer"
+]
 requires-python = ">= 3.9"
 authors = [{ name = "DomainTools", email = "integrations@domaintools.com" }]
 description = "DomainTools Official Python API"

{domaintools_api-2.3.0 → domaintools_api-2.4.0}/tests/test_api.py

@@ -322,16 +322,6 @@ def test_dict_like_behaviour():
         assert isinstance(whois_google.pop("whois", {}), dict)
 
 
-@vcr.use_cassette
-def test_list_like_behaviour():
-    with api.phisheye("google") as data:
-        data.insert(0, {"domain": "woot", "tld": "com"})
-        assert data["term"] == "google"
-        for result in data:
-            assert result["domain"]
-            assert result["tld"]
-
-
 @vcr.use_cassette
 def test_exception_handling():
     exception = None
@@ -386,24 +376,6 @@ def test_formats():
         assert "\n" in str(data.as_list())
 
 
-@vcr.use_cassette
-def test_phisheye():
-    with api.phisheye("google") as data:
-        assert data["term"] == "google"
-        for result in data:
-            assert result["domain"]
-            assert result["tld"]
-
-
-@vcr.use_cassette
-def test_phisheye_term_list():
-    with api.phisheye_term_list() as data:
-        assert data
-        for term in data:
-            assert "term" in term
-            assert type(term["active"]) == bool
-
-
 @vcr.use_cassette
 def test_iris():
     with pytest.raises(ValueError):
@@ -545,6 +517,22 @@ def test_newly_observed_domains_feed():
             assert "domain" in feed_result.keys()
 
 
+@vcr.use_cassette
+def test_newly_observed_hosts_feed():
+    results = feeds_api.noh(after="-60", header_authentication=False)
+    for response in results.response():
+        assert results.status == 200
+
+        rows = response.strip().split("\n")
+        assert response is not None
+        assert len(rows) >= 1
+
+        for row in rows:
+            feed_result = json.loads(row)
+            assert "timestamp" in feed_result.keys()
+            assert "domain" in feed_result.keys()
+
+
 @vcr.use_cassette
 def test_newly_observed_domains_feed_pagination():
     results = feeds_api.nod(sessionID="integrations-testing", after="2025-01-16T10:20:00Z")

domaintools_api-2.3.0/VERSION

@@ -1 +0,0 @@
-2.3.0

domaintools_api-2.3.0/domaintools/cli/commands/phisheye.py

@@ -1,100 +0,0 @@
-import sys
-import typer
-
-
-from domaintools.cli.main import dt_cli
-from domaintools.cli.api import DTCLICommand
-from domaintools.cli.utils import get_cli_helptext_by_name
-from domaintools.cli import constants as c
-
-
-@dt_cli.command(
-    name=c.PHISHEYE,
-    help=get_cli_helptext_by_name(command_name=c.PHISHEYE),
-)
-def phisheye(
-    ctx: typer.Context,
-    query: str = typer.Option(..., "-q", "--query", help="The domain to query."),
-    days_back: str = typer.Option(
-        None,
-        "--days-back",
-        help="Use this parameter in exceptional circumstances where you need to search domains registered up to six days prior to the current date. Set the value to an integer in the range of 1-6.",
-    ),
-    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.",
-    ),
-    rate_limit: bool = typer.Option(
-        False,
-        "-l",
-        "--rate-limit",
-        help="Rate limit API calls against the API based on per minute limits.",
-    ),
-    format: str = typer.Option(
-        "json",
-        "-f",
-        "--format",
-        help="Output format in {'list', 'json', 'xml', 'html'}",
-        callback=DTCLICommand.validate_format_input,
-    ),
-    out_file: typer.FileTextWrite = typer.Option(
-        sys.stdout, "-o", "--out-file", help="Output file (defaults to stdout)"
-    ),
-    no_verify_ssl: bool = typer.Option(
-        False,
-        "--no-verify-ssl",
-        help="Skip verification of SSL certificate when making HTTPs API calls",
-    ),
-):
-    DTCLICommand.run(name=c.PHISHEYE, params=ctx.params)
-
-
-@dt_cli.command(
-    name=c.PHISHEYE_TERM_LIST,
-    help=get_cli_helptext_by_name(command_name=c.PHISHEYE_TERM_LIST),
-)
-def phisheye_termlist(
-    ctx: typer.Context,
-    include_inactive: bool = typer.Option(
-        False,
-        "--include-inactive",
-        help="Use this parameter to display terms that may have been inactivated in users' lists.",
-    ),
-    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.",
-    ),
-    rate_limit: bool = typer.Option(
-        False,
-        "-l",
-        "--rate-limit",
-        help="Rate limit API calls against the API based on per minute limits.",
-    ),
-    format: str = typer.Option(
-        "json",
-        "-f",
-        "--format",
-        help="Output format in {'list', 'json', 'xml', 'html'}",
-        callback=DTCLICommand.validate_format_input,
-    ),
-    out_file: typer.FileTextWrite = typer.Option(
-        sys.stdout, "-o", "--out-file", help="Output file (defaults to stdout)"
-    ),
-    no_verify_ssl: bool = typer.Option(
-        False,
-        "--no-verify-ssl",
-        help="Skip verification of SSL certificate when making HTTPs API calls",
-    ),
-):
-    DTCLICommand.run(name=c.PHISHEYE_TERM_LIST, params=ctx.params)
-
-
-__all__ = ["phisheye", "phisheye_termlist"]