fluidattacks_core_resolves 1.0.0__tar.gz → 2.0.0__tar.gz

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fluidattacks_core_resolves
-Version: 1.0.0
+Version: 2.0.0
 Summary: Fluid Attacks Core Resolves Library
 Author-email: Development <development@fluidattacks.com>
 License: MPL-2.0

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/fluidattacks_core/resolves/__init__.py

@@ -4,18 +4,20 @@ from fluidattacks_core.resolves._entries import (
     EntryKind,
     NameRecord,
     Outcome,
+    Record,
     RecordType,
     Refusal,
     Resolution,
     SeenBy,
     Sighting,
+    Unresolved,
 )
 from fluidattacks_core.resolves._envelope import (
     SCHEMA_VERSION,
     ResolvesOutput,
     SeedStatus,
 )
-from fluidattacks_core.resolves._hosts import HOST_PATTERN, MAX_HOST_LENGTH, Host, ensure_host
+from fluidattacks_core.resolves._hosts import HOST_PATTERN, MAX_HOST_LENGTH, Host
 from fluidattacks_core.resolves._instants import EVIDENCE_DATE_PATTERN, EvidenceDate
 from fluidattacks_core.resolves._schema import (
     SCHEMA_PATH,
@@ -37,6 +39,7 @@ __all__ = [
     "Host",
     "NameRecord",
     "Outcome",
+    "Record",
     "RecordType",
     "Refusal",
     "Resolution",
@@ -44,8 +47,8 @@ __all__ = [
     "SeedStatus",
     "SeenBy",
     "Sighting",
+    "Unresolved",
     "build_schema",
-    "ensure_host",
     "load_schema",
     "render_schema",
 ]

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/fluidattacks_core/resolves/_entries.py

@@ -1,7 +1,7 @@
 from enum import StrEnum
 from typing import Annotated, ClassVar, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+from pydantic import BaseModel, ConfigDict, Field, IPvAnyAddress, StringConstraints, WithJsonSchema
 
 from fluidattacks_core.resolves._hosts import Host
 from fluidattacks_core.resolves._instants import EvidenceDate
@@ -59,8 +59,18 @@ class Outcome(StrEnum):
 RecordValue = Annotated[str, StringConstraints(min_length=1, max_length=4096)]
 Port = Annotated[int, Field(ge=1, le=65535)]
 
-# An address literal is at most 45 characters in its longest IPv6 spelling.
-RefusedAddress = Annotated[str, StringConstraints(min_length=1, max_length=45)]
+RefusedAddress = Annotated[
+    IPvAnyAddress,
+    WithJsonSchema(
+        {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 45,
+            "pattern": "^[0-9a-fA-F.:]+$",
+            "anyOf": [{"format": "ipv4"}, {"format": "ipv6"}],
+        }
+    ),
+]
 
 
 class _Observed(BaseModel):
@@ -101,7 +111,7 @@ class NameRecord(_Observed):
     record_value: RecordValue
 
 
-class Resolution(_Observed):
+class Unresolved(_Observed):
     """A name that was asked and yielded no usable record, and why."""
 
     kind: Literal[EntryKind.RESOLUTION]
@@ -122,8 +132,8 @@ class Refusal(_Observed):
 
 
 Record = Annotated[AddressRecord | NameRecord, Field(discriminator="record_type")]
-Resolved = Annotated[Resolution | Refusal, Field(discriminator="outcome")]
+Resolution = Annotated[Unresolved | Refusal, Field(discriminator="outcome")]
 
 # Which type an entry is follows from `kind`, then from `record_type` or
 # `outcome`, so a field foreign to the kind is an unknown field, not a rule.
-Entry = Annotated[Sighting | Record | Resolved, Field(discriminator="kind")]
+Entry = Annotated[Sighting | Record | Resolution, Field(discriminator="kind")]

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/fluidattacks_core/resolves/_instants.py

@@ -4,6 +4,6 @@ from pydantic import StringConstraints
 
 # The one shape the producer's own type emits, and a strict subset of the
 # platform's `#isoDate`, so nothing downstream has to guess a spelling.
-EVIDENCE_DATE_PATTERN = r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$"
+EVIDENCE_DATE_PATTERN = r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$"
 
 EvidenceDate = Annotated[str, StringConstraints(pattern=EVIDENCE_DATE_PATTERN)]

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/fluidattacks_core/resolves/_schema.py

@@ -15,9 +15,9 @@ _SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
 def build_schema() -> dict[str, object]:
     """Render the canonical JSONSchema the Rust producer validates against.
 
-    Structural only. The host grammar and the rules conditional on `kind` are
-    not expressed here, so the producer implements them and the fixtures are
-    what prove the implementations agree.
+    Two rules hold across entries, which a schema reads one at a time: an
+    entry names a seed the run declares, and a run states each fact once. The
+    producer implements them and the fixtures prove the implementations agree.
     """
     schema = ResolvesOutput.model_json_schema()
 

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/fluidattacks_core/resolves/schemas/resolves_output.schema.json

@@ -5,7 +5,7 @@
       "description": "An A or AAAA answer, the only kind of record a port probe can follow.\n\n`open_ports` absent means the round did not probe; empty means it probed\nand found none. The envelope's seed status says whether it got to ask.",
       "properties": {
         "evidence_date": {
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$",
           "title": "Evidence Date",
           "type": "string"
         },
@@ -80,7 +80,7 @@
       "description": "An answer that names something else, so there is nothing to probe.",
       "properties": {
         "evidence_date": {
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$",
           "title": "Evidence Date",
           "type": "string"
         },
@@ -140,7 +140,7 @@
       "description": "A name whose address the scan declined to dial.\n\nThe address travels apart from any `record_value`, which only ever holds\nan answer a scan may act on: a reader walking entries can never mistake an\naddress the screen withheld for one it may publish.",
       "properties": {
         "evidence_date": {
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$",
           "title": "Evidence Date",
           "type": "string"
         },
@@ -162,8 +162,17 @@
           "type": "string"
         },
         "refused_address": {
+          "anyOf": [
+            {
+              "format": "ipv4"
+            },
+            {
+              "format": "ipv6"
+            }
+          ],
           "maxLength": 45,
-          "minLength": 1,
+          "minLength": 2,
+          "pattern": "^[0-9a-fA-F.:]+$",
           "title": "Refused Address",
           "type": "string"
         },
@@ -190,12 +199,35 @@
       "title": "Refusal",
       "type": "object"
     },
-    "Resolution": {
+    "SeedStatus": {
+      "description": "How much of one seed's surface the run covered.\n\nA consumer that treats absence as a removal must be able to refuse\nanything but `complete`. It is per seed because a run takes several and\ngives up on the ones it cannot enumerate, so one status for the file would\nmake a whole run unusable when a single seed failed.",
+      "enum": [
+        "complete",
+        "failed",
+        "partial"
+      ],
+      "title": "SeedStatus",
+      "type": "string"
+    },
+    "SeenBy": {
+      "description": "Which part of the run saw a name, not what it later found about it.\n\nNamed as the contextualizer contract names it, and deliberately not\n`source`: the platform spells an organization's source entity that way,\nand this is a module of the scanner, not one of those.",
+      "enum": [
+        "axfr",
+        "crt.name",
+        "crt.sh",
+        "records",
+        "seed",
+        "urlscan.io"
+      ],
+      "title": "SeenBy",
+      "type": "string"
+    },
+    "Sighting": {
       "additionalProperties": false,
-      "description": "A name that was asked and yielded no usable record, and why.",
+      "description": "A name a module saw, before anything was asked of it.",
       "properties": {
         "evidence_date": {
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$",
           "title": "Evidence Date",
           "type": "string"
         },
@@ -207,20 +239,10 @@
           "type": "string"
         },
         "kind": {
-          "const": "resolution",
+          "const": "sighting",
           "title": "Kind",
           "type": "string"
         },
-        "outcome": {
-          "enum": [
-            "absent",
-            "delegated",
-            "nonexistent",
-            "unknown"
-          ],
-          "title": "Outcome",
-          "type": "string"
-        },
         "seed": {
           "maxLength": 253,
           "minLength": 1,
@@ -237,41 +259,17 @@
         "host",
         "seen_by",
         "evidence_date",
-        "kind",
-        "outcome"
+        "kind"
       ],
-      "title": "Resolution",
+      "title": "Sighting",
       "type": "object"
     },
-    "SeedStatus": {
-      "description": "How much of one seed's surface the run covered.\n\nA consumer that treats absence as a removal must be able to refuse\nanything but `complete`. It is per seed because a run takes several and\ngives up on the ones it cannot enumerate, so one status for the file would\nmake a whole run unusable when a single seed failed.",
-      "enum": [
-        "complete",
-        "failed",
-        "partial"
-      ],
-      "title": "SeedStatus",
-      "type": "string"
-    },
-    "SeenBy": {
-      "description": "Which part of the run saw a name, not what it later found about it.\n\nNamed as the contextualizer contract names it, and deliberately not\n`source`: the platform spells an organization's source entity that way,\nand this is a module of the scanner, not one of those.",
-      "enum": [
-        "axfr",
-        "crt.name",
-        "crt.sh",
-        "records",
-        "seed",
-        "urlscan.io"
-      ],
-      "title": "SeenBy",
-      "type": "string"
-    },
-    "Sighting": {
+    "Unresolved": {
       "additionalProperties": false,
-      "description": "A name a module saw, before anything was asked of it.",
+      "description": "A name that was asked and yielded no usable record, and why.",
       "properties": {
         "evidence_date": {
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$",
           "title": "Evidence Date",
           "type": "string"
         },
@@ -283,10 +281,20 @@
           "type": "string"
         },
         "kind": {
-          "const": "sighting",
+          "const": "resolution",
           "title": "Kind",
           "type": "string"
         },
+        "outcome": {
+          "enum": [
+            "absent",
+            "delegated",
+            "nonexistent",
+            "unknown"
+          ],
+          "title": "Outcome",
+          "type": "string"
+        },
         "seed": {
           "maxLength": 253,
           "minLength": 1,
@@ -303,9 +311,10 @@
         "host",
         "seen_by",
         "evidence_date",
-        "kind"
+        "kind",
+        "outcome"
       ],
-      "title": "Sighting",
+      "title": "Unresolved",
       "type": "object"
     }
   },
@@ -343,17 +352,17 @@
             "resolution": {
               "discriminator": {
                 "mapping": {
-                  "absent": "#/$defs/Resolution",
-                  "delegated": "#/$defs/Resolution",
-                  "nonexistent": "#/$defs/Resolution",
+                  "absent": "#/$defs/Unresolved",
+                  "delegated": "#/$defs/Unresolved",
+                  "nonexistent": "#/$defs/Unresolved",
                   "refused": "#/$defs/Refusal",
-                  "unknown": "#/$defs/Resolution"
+                  "unknown": "#/$defs/Unresolved"
                 },
                 "propertyName": "outcome"
               },
               "oneOf": [
                 {
-                  "$ref": "#/$defs/Resolution"
+                  "$ref": "#/$defs/Unresolved"
                 },
                 {
                   "$ref": "#/$defs/Refusal"
@@ -392,17 +401,17 @@
           {
             "discriminator": {
               "mapping": {
-                "absent": "#/$defs/Resolution",
-                "delegated": "#/$defs/Resolution",
-                "nonexistent": "#/$defs/Resolution",
+                "absent": "#/$defs/Unresolved",
+                "delegated": "#/$defs/Unresolved",
+                "nonexistent": "#/$defs/Unresolved",
                 "refused": "#/$defs/Refusal",
-                "unknown": "#/$defs/Resolution"
+                "unknown": "#/$defs/Unresolved"
               },
               "propertyName": "outcome"
             },
             "oneOf": [
               {
-                "$ref": "#/$defs/Resolution"
+                "$ref": "#/$defs/Unresolved"
               },
               {
                 "$ref": "#/$defs/Refusal"

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fluidattacks_core_resolves"
-version = "1.0.0"
+version = "2.0.0"
 description = "Fluid Attacks Core Resolves Library"
 authors = [{ name = "Development", email = "development@fluidattacks.com" }]
 license = { text = "MPL-2.0" }

fluidattacks_core_resolves-2.0.0/tests/data/invalid_evidence_date_non_ascii_digits.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": 1,
+  "seeds": {
+    "example.com": "complete"
+  },
+  "entries": [
+    {
+      "seed": "example.com",
+      "host": "api.example.com",
+      "kind": "record",
+      "seen_by": "records",
+      "evidence_date": "٢٠٢٦-01-01T00:00:00.000Z",
+      "record_type": "A",
+      "record_value": "192.0.2.10",
+      "open_ports": [
+        80,
+        443
+      ]
+    }
+  ]
+}

fluidattacks_core_resolves-2.0.0/tests/data/invalid_refused_address_not_an_address.json

@@ -0,0 +1,17 @@
+{
+  "schema_version": 1,
+  "seeds": {
+    "example.com": "complete"
+  },
+  "entries": [
+    {
+      "seed": "example.com",
+      "host": "internal.example.com",
+      "kind": "resolution",
+      "seen_by": "records",
+      "evidence_date": "2026-01-01T00:00:03.000Z",
+      "outcome": "refused",
+      "refused_address": "not-an-address"
+    }
+  ]
+}

fluidattacks_core_resolves-1.0.0/tests/data/invalid_bidi_host.json

@@ -1,17 +0,0 @@
-{
-  "schema_version": 1,
-  "seeds": {
-    "example.com": "complete"
-  },
-  "entries": [
-    {
-      "seed": "example.com",
-      "host": "api.exam‮ple.com",
-      "kind": "record",
-      "seen_by": "records",
-      "evidence_date": "2026-01-01T00:00:01.000Z",
-      "record_type": "A",
-      "record_value": "192.0.2.10"
-    }
-  ]
-}

fluidattacks_core_resolves-1.0.0/tests/data/invalid_empty_host.json

@@ -1,17 +0,0 @@
-{
-  "schema_version": 1,
-  "seeds": {
-    "example.com": "complete"
-  },
-  "entries": [
-    {
-      "seed": "example.com",
-      "host": "",
-      "kind": "record",
-      "seen_by": "records",
-      "evidence_date": "2026-01-01T00:00:01.000Z",
-      "record_type": "A",
-      "record_value": "192.0.2.10"
-    }
-  ]
-}

fluidattacks_core_resolves-1.0.0/tests/data/invalid_empty_label_host.json

@@ -1,17 +0,0 @@
-{
-  "schema_version": 1,
-  "seeds": {
-    "example.com": "complete"
-  },
-  "entries": [
-    {
-      "seed": "example.com",
-      "host": "api..example.com",
-      "kind": "record",
-      "seen_by": "records",
-      "evidence_date": "2026-01-01T00:00:01.000Z",
-      "record_type": "A",
-      "record_value": "192.0.2.10"
-    }
-  ]
-}

fluidattacks_core_resolves-1.0.0/tests/data/invalid_non_ascii_host.json

@@ -1,17 +0,0 @@
-{
-  "schema_version": 1,
-  "seeds": {
-    "example.com": "complete"
-  },
-  "entries": [
-    {
-      "seed": "example.com",
-      "host": "apí.example.com",
-      "kind": "record",
-      "seen_by": "records",
-      "evidence_date": "2026-01-01T00:00:01.000Z",
-      "record_type": "A",
-      "record_value": "192.0.2.10"
-    }
-  ]
-}

fluidattacks_core_resolves-1.0.0/tests/data/invalid_trailing_dot_host.json

@@ -1,21 +0,0 @@
-{
-  "schema_version": 1,
-  "seeds": {
-    "example.com": "complete"
-  },
-  "entries": [
-    {
-      "seed": "example.com",
-      "host": "api.example.com.",
-      "kind": "record",
-      "seen_by": "records",
-      "evidence_date": "2026-01-01T00:00:01.000Z",
-      "record_type": "A",
-      "record_value": "192.0.2.10",
-      "open_ports": [
-        80,
-        443
-      ]
-    }
-  ]
-}

{fluidattacks_core_resolves-1.0.0 → fluidattacks_core_resolves-2.0.0}/fluidattacks_core/resolves/_envelope.py

@@ -24,6 +24,11 @@ class SeedStatus(StrEnum):
     PARTIAL = "partial"
 
 
+def _asserted(entry: Entry) -> frozenset[tuple[str, object]]:
+    # What an entry claims about its host, not how or when it was learned.
+    return frozenset(entry.model_dump(exclude={"evidence_date", "open_ports"}).items())
+
+
 class ResolvesOutput(BaseModel):
     """One scan's report over the seeds it was given.
 
@@ -66,8 +71,3 @@ class ResolvesOutput(BaseModel):
             raise ValueError(msg)
 
         return self
-
-
-def _asserted(entry: Entry) -> frozenset[tuple[str, object]]:
-    # What an entry claims about its host, not how or when it was learned.
-    return frozenset(entry.model_dump(exclude={"evidence_date", "open_ports"}).items())