certgraph 0.3.0__tar.gz → 0.5.0__tar.gz

certgraph-0.5.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: certgraph
+Version: 0.5.0
+Summary: Utility for exploring and mapping X509 certificate chains.
+Author: Chris Adshead
+License: MIT License
+        
+        Copyright (c) 2026 Chris Adshead
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography
+Requires-Dist: networkx
+Requires-Dist: pydot
+Requires-Dist: rapidfuzz
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: license-file
+
+# certgraph
+
+[![PyPI version](https://img.shields.io/pypi/v/certgraph)](https://pypi.org/project/certgraph/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Python package for creating, exploring and displaying directed graphs of X.509 certificates.
+
+Build a directed graph by importing PEM/DER/`x509.Certificate` objects using subject/issuer relationships. Explore the
+generated digraph with the built in functions and then export the graph rendered in the DOT language.
+
+Basic example graph generated to DOT source with `certgraph.export_dot()` and then rendered to SVG with `dot` command line tool:
+
+![Basic example certificate graph](readme_basic_example.svg)
+
+## Features
+
+* Import certificates from:
+  * PEM strings (individually or whole PKIs)
+  * DER bytes
+  * `cryptography.x509.Certificate` objects
+* Dynamically built directed graphs from imported certificates
+* Imported certificates fuzzy-searchable based on distinguised name
+* Issuer and child certificates walkable to follow chains
+* Identify certificates not valid at a given time
+* Export DOT language graphs, with:
+  * RFC4514 distinguised names
+  * Valid time range
+  * Node highlighting for invalid certificates
+
+**Note on _fingerprints_**: This code relies extensively on certificate _fingerprints_. This is a SHA256 hash of the public bytes in the certificate. Nodes in the graph are stored with the fingerprint as their key and are indexed using the fingerprint value. While this initially seems awkward, it prevents malformed (or maliciously designed) distinguished names or serial numbers from clashing with other imported certificates. You can use `certgraph.fingerprint_from_distinguished_name()` to map from distinguised names to fingerprints for ease of use.
+
+## Installation
+
+### PyPI
+
+Install the latest version of the package from PyPI via `pip` with:
+
+```bash
+pip install certgraph
+```
+
+For development dependencies, install with:
+
+```bash
+pip install certgraph[dev]
+```
+
+### Optional
+
+* `dot` command line tool
+  * Used to render generated DOT language graphs into PNG/SVG/etc.
+  * E.g. `dot -Tsvg <generated_file>.dot -o graph.svg`
+  * Alternatively can use online tools.
+
+## Basic Examples
+
+Import the `certgraph` class from the module:
+
+```python
+>>> from certgraph import certgraph as cg
+```
+
+Load some varied data for later examples:
+
+```python
+>>> with open("path/to/cert.pem") as f:
+>>>   pem_data = f.read() # 1 cert
+>>> with open("path/to/pki.pem") as f:
+>>>   pki_data = f.read() # 3 certs in 1 PEM file
+>>> with open("path/to/cert.der", "rb") as f:
+>>>   der_data = f.read() # 1 cert
+```
+
+Import a PEM file with 1 certificate in it:
+
+```python
+>>> graph = cg().import_certificates(pem_data)
+>>> len(graph)
+1
+```
+
+Import mixed PEM/DER dataset, including PEMs with PKIs, using function chaining:
+
+```python
+>>> graph = (
+>>>   cg()
+>>>     .import_certificates(pem_data)
+>>>     .import_certificates(pki_data)
+>>>     .import_certificates(der_data)
+>>> )
+>>> len(graph)
+5
+```
+
+Get an imported certificate (as `cryptography.x509.Certificate`) by using a fingerprint. The fingerprint of the desired certificate can be retrieved using a fuzzy-searching function based on the distinguised name:
+
+```python
+>>> dn = "CN=f3ec133b-4"
+>>> fingerprint = cg.fingerprint_from_distinguished_name(dn) # Fuzzy-search the distinguised name in the list of imported certificates for the best match
+>>> print(fingerprint)
+"77c4b5b12b79887b8c709df826cff89a7268071593de5cc84053b8c00302b2fb"
+>>> cert = cg.get_certificate(fingerprint) # Get the certificate associated with the fingerprint
+>>> print(cert.subject.rfc4514_string())
+"CN=f3ec133b-4"
+```
+
+Get predecessor (issuer) and successor (child) fingerprints from a certificate fingerprint:
+
+```python
+>>> fingerprint = "77c4b5b12b79887b8c709df826cff89a7268071593de5cc84053b8c00302b2fb"
+>>> cg.get_issuer_fingerprint(fingerprint)
+"965e8d87f96ccf564726ff5e97ea4d6b18731d9b762ef9510479f628bc85837e"
+>>> cg.get_child_certificates(fingerprint)
+["3cf372288714b52298222bb1f8cf51dce3f1e60147ec53f9ee3dc28e8766c734", "2caf1b256bcbb327aea8d1442ba12e0fc6582b3c2980ee9f31d4ae3a62f62673"]
+```
+
+Export graph to DOT language and write to a file, where it can be rendered with the `dot` command line tool.
+
+```python
+>>> with open("path/to/output.dot", "w") as f:
+>>>   dot_str = cg.export_dot()
+>>>   f.write(dot_str)
+```
+
+See more complex examples in the `examples` directory of the repository (**WIP**).
+
+## Documentation
+
+Documentation for the package uses Sphinx with the read-the-docs template. Source can be found in `docs`.
+
+To build the source, execute the following from the repo root:
+
+```bash
+python -m sphinx -b html docs/source docs/build
+```

certgraph-0.5.0/README.md

@@ -0,0 +1,135 @@
+# certgraph
+
+[![PyPI version](https://img.shields.io/pypi/v/certgraph)](https://pypi.org/project/certgraph/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Python package for creating, exploring and displaying directed graphs of X.509 certificates.
+
+Build a directed graph by importing PEM/DER/`x509.Certificate` objects using subject/issuer relationships. Explore the
+generated digraph with the built in functions and then export the graph rendered in the DOT language.
+
+Basic example graph generated to DOT source with `certgraph.export_dot()` and then rendered to SVG with `dot` command line tool:
+
+![Basic example certificate graph](readme_basic_example.svg)
+
+## Features
+
+* Import certificates from:
+  * PEM strings (individually or whole PKIs)
+  * DER bytes
+  * `cryptography.x509.Certificate` objects
+* Dynamically built directed graphs from imported certificates
+* Imported certificates fuzzy-searchable based on distinguised name
+* Issuer and child certificates walkable to follow chains
+* Identify certificates not valid at a given time
+* Export DOT language graphs, with:
+  * RFC4514 distinguised names
+  * Valid time range
+  * Node highlighting for invalid certificates
+
+**Note on _fingerprints_**: This code relies extensively on certificate _fingerprints_. This is a SHA256 hash of the public bytes in the certificate. Nodes in the graph are stored with the fingerprint as their key and are indexed using the fingerprint value. While this initially seems awkward, it prevents malformed (or maliciously designed) distinguished names or serial numbers from clashing with other imported certificates. You can use `certgraph.fingerprint_from_distinguished_name()` to map from distinguised names to fingerprints for ease of use.
+
+## Installation
+
+### PyPI
+
+Install the latest version of the package from PyPI via `pip` with:
+
+```bash
+pip install certgraph
+```
+
+For development dependencies, install with:
+
+```bash
+pip install certgraph[dev]
+```
+
+### Optional
+
+* `dot` command line tool
+  * Used to render generated DOT language graphs into PNG/SVG/etc.
+  * E.g. `dot -Tsvg <generated_file>.dot -o graph.svg`
+  * Alternatively can use online tools.
+
+## Basic Examples
+
+Import the `certgraph` class from the module:
+
+```python
+>>> from certgraph import certgraph as cg
+```
+
+Load some varied data for later examples:
+
+```python
+>>> with open("path/to/cert.pem") as f:
+>>>   pem_data = f.read() # 1 cert
+>>> with open("path/to/pki.pem") as f:
+>>>   pki_data = f.read() # 3 certs in 1 PEM file
+>>> with open("path/to/cert.der", "rb") as f:
+>>>   der_data = f.read() # 1 cert
+```
+
+Import a PEM file with 1 certificate in it:
+
+```python
+>>> graph = cg().import_certificates(pem_data)
+>>> len(graph)
+1
+```
+
+Import mixed PEM/DER dataset, including PEMs with PKIs, using function chaining:
+
+```python
+>>> graph = (
+>>>   cg()
+>>>     .import_certificates(pem_data)
+>>>     .import_certificates(pki_data)
+>>>     .import_certificates(der_data)
+>>> )
+>>> len(graph)
+5
+```
+
+Get an imported certificate (as `cryptography.x509.Certificate`) by using a fingerprint. The fingerprint of the desired certificate can be retrieved using a fuzzy-searching function based on the distinguised name:
+
+```python
+>>> dn = "CN=f3ec133b-4"
+>>> fingerprint = cg.fingerprint_from_distinguished_name(dn) # Fuzzy-search the distinguised name in the list of imported certificates for the best match
+>>> print(fingerprint)
+"77c4b5b12b79887b8c709df826cff89a7268071593de5cc84053b8c00302b2fb"
+>>> cert = cg.get_certificate(fingerprint) # Get the certificate associated with the fingerprint
+>>> print(cert.subject.rfc4514_string())
+"CN=f3ec133b-4"
+```
+
+Get predecessor (issuer) and successor (child) fingerprints from a certificate fingerprint:
+
+```python
+>>> fingerprint = "77c4b5b12b79887b8c709df826cff89a7268071593de5cc84053b8c00302b2fb"
+>>> cg.get_issuer_fingerprint(fingerprint)
+"965e8d87f96ccf564726ff5e97ea4d6b18731d9b762ef9510479f628bc85837e"
+>>> cg.get_child_certificates(fingerprint)
+["3cf372288714b52298222bb1f8cf51dce3f1e60147ec53f9ee3dc28e8766c734", "2caf1b256bcbb327aea8d1442ba12e0fc6582b3c2980ee9f31d4ae3a62f62673"]
+```
+
+Export graph to DOT language and write to a file, where it can be rendered with the `dot` command line tool.
+
+```python
+>>> with open("path/to/output.dot", "w") as f:
+>>>   dot_str = cg.export_dot()
+>>>   f.write(dot_str)
+```
+
+See more complex examples in the `examples` directory of the repository (**WIP**).
+
+## Documentation
+
+Documentation for the package uses Sphinx with the read-the-docs template. Source can be found in `docs`.
+
+To build the source, execute the following from the repo root:
+
+```bash
+python -m sphinx -b html docs/source docs/build
+```

{certgraph-0.3.0 → certgraph-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "certgraph"
-version = "0.3.0"
+version = "0.5.0"
 description = "Utility for exploring and mapping X509 certificate chains."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,6 +25,11 @@ dev = [
     "pytest",
     "pytest-cov",
 ]
+docs = [
+    "sphinx",
+    "sphinx-autodoc-typehints",
+    "sphinx-rtd-theme",
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{certgraph-0.3.0 → certgraph-0.5.0}/src/certgraph/certgraph.py

@@ -1,6 +1,10 @@
+from __future__ import annotations
+
 from cryptography import x509
 from cryptography.hazmat.primitives import hashes
+from datetime import datetime, timezone
 import networkx as nx
+import pydot
 from rapidfuzz import fuzz
 
 
@@ -12,6 +16,10 @@ class certgraph:
         self._certlist: set[x509.Certificate] = []
         self._graph = nx.DiGraph()
 
+    def __len__(self) -> int:
+        """Get number of certificates imported."""
+        return len(self._certlist)
+
     def import_certificates(
         self,
         certificates: (
@@ -88,10 +96,43 @@ class certgraph:
         """
         return [f"{edge[0][:8]} -> {edge[1][:8]}" for edge in self._graph.edges()]
 
-    def export_dot(self) -> str:
+    def _generate_dot_legend(self) -> pydot.Cluster:
+        """Generate the optional legend for the dot output."""
+        cluster = pydot.Cluster("legend", label="Legend", style="dashed")
+
+        nodes = [
+            pydot.Node(
+                "legend_valid",
+                label="Valid",
+                shape="box",
+                style="filled",
+                fillcolor="white",
+            ),
+            pydot.Node(
+                "legend_invalid",
+                label="Invalid",
+                shape="box",
+                style="filled",
+                fillcolor="tomato",
+            ),
+        ]
+
+        for i, n in enumerate(nodes):
+            cluster.add_node(n)
+
+            # Add invisible edge to force the nodes to appear on different ranks (i.e. top-bottom direction)
+            if i != len(nodes) - 1:
+                cluster.add_edge(pydot.Edge(nodes[i], nodes[i + 1], style="invis"))
+
+        return cluster
+
+    def export_dot(self, add_legend: bool = True) -> str:
         """
         Export the current certificate digraph in the dot language.
 
+        Args:
+            add_legend: Add a legend with the node colours to the graph output. Default is True.
+
         Returns:
             The certificate digraph rendered as a dot language string.
         """
@@ -100,15 +141,31 @@ class certgraph:
         for fingerprint, data in self._graph.nodes(data=True):
             cert: x509.Certificate = data["certificate"]
             validity_time_str = f"{cert.not_valid_before_utc.isoformat()} → {cert.not_valid_after_utc.isoformat()}"
+            invalid = self.certificate_invalid_at(fingerprint)
 
             label = f"DN: {cert.subject.rfc4514_string()}"
             label += f"\nValid: {validity_time_str}"
 
-            dot_graph.add_node(fingerprint, label=label, shape="box")
+            if invalid:
+                node_color = "tomato"
+            else:
+                node_color = "white"
+
+            dot_graph.add_node(
+                fingerprint,
+                label=label,
+                shape="box",
+                style="filled",
+                fillcolor=node_color,
+            )
 
         dot_graph.add_edges_from(self._graph.edges())
+        dot_out = nx.drawing.nx_pydot.to_pydot(dot_graph)
+
+        if add_legend:
+            dot_out.add_subgraph(self._generate_dot_legend())
 
-        return nx.drawing.nx_pydot.to_pydot(dot_graph).to_string()
+        return dot_out.to_string()
 
     def clear(self) -> certgraph:
         """
@@ -172,7 +229,7 @@ class certgraph:
 
         Args:
             fingerprint: Fingerprint of the certificate to get the issuer of.
-        
+
         Returns:
             The fingerprint of the issuing certificate or None if not present in the digraph.
 
@@ -180,7 +237,9 @@ class certgraph:
             ValueError: If certificate with the supplied fingerprint isn't in the digraph.
         """
         if fingerprint not in self._graph.nodes:
-            raise ValueError(f"Fingerprint supplied doesn't match any imported certificate.")
+            raise ValueError(
+                f"Fingerprint supplied doesn't match any imported certificate."
+            )
 
         return next(self._graph.predecessors(fingerprint), None)
 
@@ -190,7 +249,7 @@ class certgraph:
 
         Args:
             fingerprint: Fingerprint of the certificate to get the child certificates of.
-        
+
         Returns:
             The list of fingerprints belonging to child certificates.
 
@@ -198,7 +257,9 @@ class certgraph:
             ValueError: If certificate with the supplied fingerprint isn't in the digraph.
         """
         if fingerprint not in self._graph.nodes:
-            raise ValueError(f"Fingerprint supplied doesn't match any imported certificate.")
+            raise ValueError(
+                f"Fingerprint supplied doesn't match any imported certificate."
+            )
 
         return list(self._graph.successors(fingerprint))
 
@@ -217,3 +278,29 @@ class certgraph:
             if cert in self._certlist:
                 self._certlist.remove(cert)
 
+    def certificate_invalid_at(
+        self, fingerprint: str, at_time: datetime | None = None
+    ) -> bool:
+        """
+        Check if an imported certificate is outside its validity period - either not yet valid or expired.
+
+        Args:
+            fingerprint: Fingerprint of the certificate to check.
+            at_time: When the certificate validity will be checked against. None value defaults to now (UTC).
+
+        Returns:
+            True if the certificate is not yet valid or expired at the given time, otherwise false.
+
+        Raises:
+            ValueError: If certificate with the supplied fingerprint isn't in the digraph.
+        """
+        if fingerprint not in self._graph.nodes:
+            raise ValueError(
+                f"Fingerprint supplied doesn't match any imported certificate."
+            )
+
+        if at_time is None:
+            at_time = datetime.now(timezone.utc)
+
+        cert = self.get_certificate(fingerprint)
+        return at_time < cert.not_valid_before_utc or at_time > cert.not_valid_after_utc

certgraph-0.5.0/src/certgraph.egg-info/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: certgraph
+Version: 0.5.0
+Summary: Utility for exploring and mapping X509 certificate chains.
+Author: Chris Adshead
+License: MIT License
+        
+        Copyright (c) 2026 Chris Adshead
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography
+Requires-Dist: networkx
+Requires-Dist: pydot
+Requires-Dist: rapidfuzz
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: license-file
+
+# certgraph
+
+[![PyPI version](https://img.shields.io/pypi/v/certgraph)](https://pypi.org/project/certgraph/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Python package for creating, exploring and displaying directed graphs of X.509 certificates.
+
+Build a directed graph by importing PEM/DER/`x509.Certificate` objects using subject/issuer relationships. Explore the
+generated digraph with the built in functions and then export the graph rendered in the DOT language.
+
+Basic example graph generated to DOT source with `certgraph.export_dot()` and then rendered to SVG with `dot` command line tool:
+
+![Basic example certificate graph](readme_basic_example.svg)
+
+## Features
+
+* Import certificates from:
+  * PEM strings (individually or whole PKIs)
+  * DER bytes
+  * `cryptography.x509.Certificate` objects
+* Dynamically built directed graphs from imported certificates
+* Imported certificates fuzzy-searchable based on distinguised name
+* Issuer and child certificates walkable to follow chains
+* Identify certificates not valid at a given time
+* Export DOT language graphs, with:
+  * RFC4514 distinguised names
+  * Valid time range
+  * Node highlighting for invalid certificates
+
+**Note on _fingerprints_**: This code relies extensively on certificate _fingerprints_. This is a SHA256 hash of the public bytes in the certificate. Nodes in the graph are stored with the fingerprint as their key and are indexed using the fingerprint value. While this initially seems awkward, it prevents malformed (or maliciously designed) distinguished names or serial numbers from clashing with other imported certificates. You can use `certgraph.fingerprint_from_distinguished_name()` to map from distinguised names to fingerprints for ease of use.
+
+## Installation
+
+### PyPI
+
+Install the latest version of the package from PyPI via `pip` with:
+
+```bash
+pip install certgraph
+```
+
+For development dependencies, install with:
+
+```bash
+pip install certgraph[dev]
+```
+
+### Optional
+
+* `dot` command line tool
+  * Used to render generated DOT language graphs into PNG/SVG/etc.
+  * E.g. `dot -Tsvg <generated_file>.dot -o graph.svg`
+  * Alternatively can use online tools.
+
+## Basic Examples
+
+Import the `certgraph` class from the module:
+
+```python
+>>> from certgraph import certgraph as cg
+```
+
+Load some varied data for later examples:
+
+```python
+>>> with open("path/to/cert.pem") as f:
+>>>   pem_data = f.read() # 1 cert
+>>> with open("path/to/pki.pem") as f:
+>>>   pki_data = f.read() # 3 certs in 1 PEM file
+>>> with open("path/to/cert.der", "rb") as f:
+>>>   der_data = f.read() # 1 cert
+```
+
+Import a PEM file with 1 certificate in it:
+
+```python
+>>> graph = cg().import_certificates(pem_data)
+>>> len(graph)
+1
+```
+
+Import mixed PEM/DER dataset, including PEMs with PKIs, using function chaining:
+
+```python
+>>> graph = (
+>>>   cg()
+>>>     .import_certificates(pem_data)
+>>>     .import_certificates(pki_data)
+>>>     .import_certificates(der_data)
+>>> )
+>>> len(graph)
+5
+```
+
+Get an imported certificate (as `cryptography.x509.Certificate`) by using a fingerprint. The fingerprint of the desired certificate can be retrieved using a fuzzy-searching function based on the distinguised name:
+
+```python
+>>> dn = "CN=f3ec133b-4"
+>>> fingerprint = cg.fingerprint_from_distinguished_name(dn) # Fuzzy-search the distinguised name in the list of imported certificates for the best match
+>>> print(fingerprint)
+"77c4b5b12b79887b8c709df826cff89a7268071593de5cc84053b8c00302b2fb"
+>>> cert = cg.get_certificate(fingerprint) # Get the certificate associated with the fingerprint
+>>> print(cert.subject.rfc4514_string())
+"CN=f3ec133b-4"
+```
+
+Get predecessor (issuer) and successor (child) fingerprints from a certificate fingerprint:
+
+```python
+>>> fingerprint = "77c4b5b12b79887b8c709df826cff89a7268071593de5cc84053b8c00302b2fb"
+>>> cg.get_issuer_fingerprint(fingerprint)
+"965e8d87f96ccf564726ff5e97ea4d6b18731d9b762ef9510479f628bc85837e"
+>>> cg.get_child_certificates(fingerprint)
+["3cf372288714b52298222bb1f8cf51dce3f1e60147ec53f9ee3dc28e8766c734", "2caf1b256bcbb327aea8d1442ba12e0fc6582b3c2980ee9f31d4ae3a62f62673"]
+```
+
+Export graph to DOT language and write to a file, where it can be rendered with the `dot` command line tool.
+
+```python
+>>> with open("path/to/output.dot", "w") as f:
+>>>   dot_str = cg.export_dot()
+>>>   f.write(dot_str)
+```
+
+See more complex examples in the `examples` directory of the repository (**WIP**).
+
+## Documentation
+
+Documentation for the package uses Sphinx with the read-the-docs template. Source can be found in `docs`.
+
+To build the source, execute the following from the repo root:
+
+```bash
+python -m sphinx -b html docs/source docs/build
+```

{certgraph-0.3.0 → certgraph-0.5.0}/src/certgraph.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/certgraph.egg-info/SOURCES.txt
 src/certgraph.egg-info/dependency_links.txt
 src/certgraph.egg-info/requires.txt
 src/certgraph.egg-info/top_level.txt
+tests/test_certificate_invalid_at.py
 tests/test_clear.py
 tests/test_export_dot.py
 tests/test_fingerprint_search.py

{certgraph-0.3.0 → certgraph-0.5.0}/src/certgraph.egg-info/requires.txt

@@ -7,3 +7,8 @@ rapidfuzz
 black
 pytest
 pytest-cov
+
+[docs]
+sphinx
+sphinx-autodoc-typehints
+sphinx-rtd-theme

certgraph-0.5.0/tests/test_certificate_invalid_at.py

@@ -0,0 +1,39 @@
+from datetime import timedelta
+
+import pytest
+from cryptography.hazmat.primitives import hashes
+
+
+def test_raises_for_unknown_fingerprint(graph):
+    with pytest.raises(ValueError):
+        graph.certificate_invalid_at("does-not-exist")
+
+
+def test_certificate_within_validity_period_is_valid(graph, self_signed_cert):
+    graph.import_certificates(self_signed_cert)
+    fingerprint = self_signed_cert.fingerprint(hashes.SHA256()).hex()
+
+    assert graph.certificate_invalid_at(fingerprint) is False
+
+
+def test_expired_certificate_is_invalid(graph, expired_cert):
+    graph.import_certificates(expired_cert)
+    fingerprint = expired_cert.fingerprint(hashes.SHA256()).hex()
+
+    assert graph.certificate_invalid_at(fingerprint) is True
+
+
+def test_not_yet_valid_certificate_is_invalid(graph, self_signed_cert):
+    graph.import_certificates(self_signed_cert)
+    fingerprint = self_signed_cert.fingerprint(hashes.SHA256()).hex()
+    before_validity = self_signed_cert.not_valid_before_utc - timedelta(days=1)
+
+    assert graph.certificate_invalid_at(fingerprint, at_time=before_validity) is True
+
+
+def test_at_time_controls_validity_check(graph, self_signed_cert):
+    graph.import_certificates(self_signed_cert)
+    fingerprint = self_signed_cert.fingerprint(hashes.SHA256()).hex()
+    after_validity = self_signed_cert.not_valid_after_utc + timedelta(days=1)
+
+    assert graph.certificate_invalid_at(fingerprint, at_time=after_validity) is True

{certgraph-0.3.0 → certgraph-0.5.0}/tests/test_export_dot.py

@@ -3,7 +3,7 @@ def test_export_dot_returns_string(graph):
 
 
 def test_export_dot_empty_graph_has_no_edges(graph):
-    dot = graph.export_dot()
+    dot = graph.export_dot(add_legend=False)
     assert "digraph" in dot
     assert "->" not in dot
 
@@ -36,10 +36,28 @@ def test_export_dot_node_shape_is_box(graph, self_signed_cert):
     assert "shape=box" in dot
 
 
+def test_export_dot_highlights_expired_certificate(graph, expired_cert):
+    graph.import_certificates(expired_cert)
+
+    dot = graph.export_dot()
+
+    assert "fillcolor=tomato" in dot
+
+
+def test_export_dot_does_not_highlight_valid_certificate(graph, self_signed_cert):
+    graph.import_certificates(self_signed_cert)
+
+    # legend is disabled so its own "tomato" legend node doesn't interfere
+    dot = graph.export_dot(add_legend=False)
+
+    assert "fillcolor=white" in dot
+    assert "tomato" not in dot
+
+
 def test_export_dot_includes_edges(graph, chain_certs):
     graph.import_certificates(chain_certs)
 
-    dot = graph.export_dot()
+    dot = graph.export_dot(add_legend=False)
 
     # one self-loop for the root, plus one edge per subsequent certificate
     assert dot.count("->") == len(chain_certs)
@@ -52,3 +70,36 @@ def test_export_dot_does_not_write_file(graph, self_signed_cert, tmp_path, monke
     graph.export_dot()
 
     assert not (tmp_path / "test_out.dot").exists()
+
+
+def test_export_dot_includes_legend_by_default(graph):
+    dot = graph.export_dot()
+
+    assert "subgraph cluster_legend" in dot
+    assert "label=Legend" in dot
+    assert "legend_valid [label=Valid, shape=box, style=filled, fillcolor=white]" in dot
+    assert (
+        "legend_invalid [label=Invalid, shape=box, style=filled, fillcolor=tomato]"
+        in dot
+    )
+
+
+def test_export_dot_legend_can_be_disabled(graph):
+    dot = graph.export_dot(add_legend=False)
+
+    assert "cluster_legend" not in dot
+    assert "legend_valid" not in dot
+    assert "legend_invalid" not in dot
+
+
+def test_export_dot_legend_is_dashed(graph):
+    dot = graph.export_dot()
+
+    assert "style=dashed" in dot
+
+
+def test_export_dot_legend_nodes_are_ranked_top_to_bottom(graph):
+    dot = graph.export_dot()
+
+    # invisible edge forces the two legend nodes onto separate ranks
+    assert "legend_valid -> legend_invalid [style=invis]" in dot

certgraph-0.3.0/PKG-INFO

@@ -1,42 +0,0 @@
-Metadata-Version: 2.4
-Name: certgraph
-Version: 0.3.0
-Summary: Utility for exploring and mapping X509 certificate chains.
-Author: Chris Adshead
-License: MIT License
-        
-        Copyright (c) 2026 Chris Adshead
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: cryptography
-Requires-Dist: networkx
-Requires-Dist: pydot
-Requires-Dist: rapidfuzz
-Provides-Extra: dev
-Requires-Dist: black; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Dynamic: license-file
-
-# certgraph
-Python package for displaying X509 certificate chains.

certgraph-0.3.0/README.md

@@ -1,2 +0,0 @@
-# certgraph
-Python package for displaying X509 certificate chains.

certgraph-0.3.0/src/certgraph.egg-info/PKG-INFO

@@ -1,42 +0,0 @@
-Metadata-Version: 2.4
-Name: certgraph
-Version: 0.3.0
-Summary: Utility for exploring and mapping X509 certificate chains.
-Author: Chris Adshead
-License: MIT License
-        
-        Copyright (c) 2026 Chris Adshead
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: cryptography
-Requires-Dist: networkx
-Requires-Dist: pydot
-Requires-Dist: rapidfuzz
-Provides-Extra: dev
-Requires-Dist: black; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Dynamic: license-file
-
-# certgraph
-Python package for displaying X509 certificate chains.