k8stools 2.0.2__tar.gz → 2.0.3__tar.gz

{k8stools-2.0.2 → k8stools-2.0.3}/CLAUDE.md

@@ -60,7 +60,22 @@ Tools in `k8s_tools.py` follow three patterns:
 2. **API-typed** — Pydantic models that match K8s client types with lesser-used fields omitted (e.g. `get_pod_container_statuses`)
 3. **Raw dict** — `to_dict()` on the K8s client object; return type is `dict[str, Any]` with fields documented in the docstring (e.g. `get_pod_spec`)
 
-Use `datetime.timedelta` for age/duration fields. Use snake_case field names. Include `pod_name`/`namespace` in container-level models for context.
+Use the `Duration` type (`k8s_tools.Duration`) for age/duration fields, not a bare
+`datetime.timedelta`. It is a `timedelta` that normalizes to whole, non-negative
+seconds on validation. Pydantic describes a `timedelta` as
+`{"type": "string", "format": "duration"}` but serializes a microsecond-bearing one
+as `"P2DT5M27.978616S"`; JSON Schema's `duration` format points at RFC 3339
+Appendix A, whose grammar allows neither a decimal point nor a sign. An MCP client
+that validates structured output against the declared schema (ajv does; Python's
+`jsonschema` skips `duration` unless the optional `isoduration` extra is installed)
+therefore rejected the whole call, on every row of every list tool. Since every age
+is `now() - <k8s timestamp>` and Kubernetes timestamps are whole-second, the
+fractional part was never information — just the microseconds of that one `now()`.
+This is the same rule `MockState`'s replay clock already applies, for the same
+reason. `tests/test_duration_format.py` checks each model's serialized output
+against the format its own schema declares.
+
+Use snake_case field names. Include `pod_name`/`namespace` in container-level models for context.
 
 All tools are collected in the `TOOLS` list in `k8s_tools.py` for agent/MCP registration.
 
@@ -163,6 +178,31 @@ keys) and values under keys/env-var names matching
 separators and camelCase, so `apiKey` matches and `VALKEY_ADDR` does not),
 replacing them with a visible `[REDACTED]` marker.
 
+Redaction is **span-granular, with two deliberate exceptions.** A matched token
+(AWS key, JWT) is replaced where it sits, leaving the surrounding text readable.
+The exceptions:
+
+- **PEM blocks go whole.** The pattern matches only the `-----BEGIN ... PRIVATE
+  KEY-----` header, and the secret is the base64 body *after* it — substituting
+  just the matched span would black out the header and publish the key. Hence the
+  `_TOKEN_SHAPE_RES` / `_CONTAINMENT_SHAPE_RES` split: never move a pattern into
+  the former unless its match is the entire secret.
+- **A string that parses as a JSON object/array is recursed into** and
+  re-serialized, rather than treated as one opaque value. Config-as-JSON under a
+  single ConfigMap key is common, and opacity failed in both directions: one
+  incidental token match blacked out an entire non-secret config file, while a real
+  `{"password": ...}` inside a blob was invisible to the name rule and passed
+  through verbatim. Nothing is re-serialized when nothing matched, so clean values
+  keep their exact formatting.
+
+  The `key` exemption below applies *inside* these blobs too. Lifting it there
+  looked obviously right — those names are the author's, not Kubernetes schema —
+  and re-measuring said otherwise: on the 38-pod cluster it added 12 redactions,
+  every one `tags[].key: "instance"` in a Grafana dashboard ConfigMap, and no
+  secrets. Structural `key` fields dominate inside config documents just as they do
+  in the API. With the exemption kept, this whole change is redaction-neutral on
+  that cluster: same 6 redactions, same paths, same values as before it.
+
 A field named *exactly* `key` is exempt — in the Kubernetes API that is always
 structural (taint, map entry, label selector, projected-volume item), never a
 credential. Before that exemption a real 38-pod capture produced 139 redactions of

{k8stools-2.0.2 → k8stools-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.0.2
+Version: 2.0.3
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
 Author: Jeff Fischer

{k8stools-2.0.2 → k8stools-2.0.3}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "k8stools"
-version = "2.0.2"
+version = "2.0.3"
 description = "Tools and an MCP server for building Kubernetes agents"
 readme = "README.md"
 requires-python = ">=3.12"

k8stools-2.0.3/redaction-bug.md

@@ -0,0 +1,25 @@
+# get_configmap / ConfigMap.data redaction: a single value-shape match anywhere in a JSON-serialized ConfigMap value blacks out the entire value, not just the match
+## Repro:
+any ConfigMap whose data value is a JSON-encoded blob (common pattern: config-as-JSON-string under one key) where some substring incidentally matches the JWT/AKIA/PEM regexes.
+
+## Impact:
+legitimate, non-secret operational config (in our case: warm-runtime pool target count) becomes fully unreadable via the MCP tool, forcing a workaround (grep-ing cronjob logs instead).
+
+## Suggested fixes (in rough order of effort):
+* When a string value looks like JSON (json.loads succeeds), recurse redaction into the parsed structure and re-serialize, instead of treating it as one opaque string.
+* At minimum, redact only the matched span within the string (rx.sub(REDACTED, s)) rather than replacing the whole value when a partial match is found — this alone would have kept the rest of warm-runtimes.json visible.
+* Note in output when a value is a "detected JSON string with an internal match" vs. a flat credential-shaped value, so callers can tell which failure mode they hit.
+
+## What we saw
+Reading the warm-runtimes-config ConfigMap in openhands-cloud-c3:
+```
+{
+  "name": "warm-runtimes-config",
+  "namespace": "openhands-cloud-c3",
+  "data": {
+    "warm-runtimes.json": "[REDACTED]"
+  },
+  "binary_data_keys": []
+}
+```
+The whole value came back redacted, even though this ConfigMap is just warm-pool sizing config (count, runtime spec names) — nothing secret. We had to fall back to the reconciler's own log line (Missing N runtimes for v1, creating N warm runtimes...) to get the real number (5).

{k8stools-2.0.2 → k8stools-2.0.3}/src/k8stools/__init__.py

@@ -78,4 +78,4 @@ the built-in OTel Demo snapshot by default, or your own via load_mock_state() or
 the server's --state-file option.
 """
 
-__version__ = "2.0.2"
+__version__ = "2.0.3"

{k8stools-2.0.2 → k8stools-2.0.3}/src/k8stools/k8s_tools.py

@@ -16,9 +16,9 @@ import sys
 import os
 import logging
 import datetime
-from typing import Optional, Union, Literal, Any
+from typing import Optional, Union, Literal, Any, Annotated
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, AfterValidator
 import yaml
 
 from kubernetes import client, config
@@ -85,12 +85,47 @@ def _get_batch_v1_api_client() -> client.BatchV1Api:
             raise K8sConfigError(f"Unexpected error: {e}") from e
 
 
+def _to_whole_seconds(td: datetime.timedelta) -> datetime.timedelta:
+    """Truncate a duration to whole seconds, flooring at zero.
+
+    Both adjustments keep the value inside the grammar our own JSON Schema
+    declares for it (see :data:`Duration`).
+
+    Truncation: every age here is ``now() - <k8s timestamp>``, and Kubernetes
+    timestamps are whole-second, so the sub-second part of an age is nothing but
+    the microseconds of the ``now()`` that happened to compute it - noise, and
+    identical across every row of a single response. This matches the rule
+    ``MockState``'s replay clock already follows for the same reason.
+
+    Flooring: a cluster whose clock is ahead of ours yields a small negative age,
+    which pydantic renders as ``-PT5S``. A duration has no sign in this grammar,
+    so clamp it; at this granularity "just created" is the honest reading anyway.
+    """
+    return datetime.timedelta(seconds=max(int(td.total_seconds()), 0))
+
+
+#: A ``timedelta`` field on a response model.
+#:
+#: Pydantic's default JSON Schema for ``timedelta`` is
+#: ``{"type": "string", "format": "duration"}``, but its default *serialization*
+#: emits fractional seconds (``"P2DT5M27.978616S"``) whenever the value carries
+#: microseconds. JSON Schema's ``duration`` format references RFC 3339 Appendix A,
+#: whose grammar admits only integer components - so pydantic's own schema and its
+#: own serializer disagree, and an MCP client that validates structured output
+#: against the declared schema (ajv does; Python's ``jsonschema`` skips ``duration``
+#: unless the optional ``isoduration`` extra is installed) rejects the tool call
+#: outright, on every row, before the caller sees any data.
+#:
+#: Normalizing the value rather than the schema keeps ``format: "duration"``
+#: accurate and keeps direct Python callers' fields real ``timedelta`` objects.
+Duration = Annotated[datetime.timedelta, AfterValidator(_to_whole_seconds)]
+
 
 class NamespaceSummary(BaseModel):
     """Summary information about a namespace, like returned by `kubectl get namespace`"""
     name: str
     status: str
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_namespaces() -> list[NamespaceSummary]:
@@ -142,7 +177,7 @@ class NodeSummary(BaseModel):
     name: str
     status: str
     roles: list[str]
-    age: datetime.timedelta
+    age: Duration
     version: str
     internal_ip: Optional[str] = None
     external_ip: Optional[str] = None
@@ -347,8 +382,8 @@ class PodSummary(BaseModel):
     total_containers: int
     ready_containers: int
     restarts: int
-    last_restart: Optional[datetime.timedelta]
-    age: datetime.timedelta
+    last_restart: Optional[Duration]
+    age: Duration
     ip: Optional[str] = None
     node: Optional[str] = None
 
@@ -501,7 +536,7 @@ def _format_timedelta(td: Optional[datetime.timedelta]) -> str:
 
 class EventSummary(BaseModel):
     """This is the representation of a Kubernetes Event"""
-    last_seen: Optional[datetime.timedelta]  # Time since event occurred
+    last_seen: Optional[Duration]  # Time since event occurred
     type: str
     reason: str
     object: str
@@ -942,7 +977,7 @@ class DeploymentSummary(BaseModel):
     ready_replicas: int
     up_to_date_relicas: int
     available_replicas: int
-    age: datetime.timedelta
+    age: Duration
 
 def get_deployment_summaries(namespace: Optional[str] = None) -> list[DeploymentSummary]:
     """
@@ -1047,7 +1082,7 @@ class ReplicaSetSummary(BaseModel):
     current_replicas: int
     ready_replicas: int
     images: list[str]
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_replicaset_summaries(namespace: Optional[str] = None,
@@ -1227,7 +1262,7 @@ class ServiceSummary(BaseModel):
     cluster_ip: Optional[str] = None
     external_ip: Optional[str] = None
     ports: list[PortInfo]
-    age: datetime.timedelta
+    age: Duration
     selector: dict[str, str] = Field(default_factory=dict)
     labels: dict[str, str] = Field(default_factory=dict)
     annotations: dict[str, str] = Field(default_factory=dict)
@@ -1378,7 +1413,7 @@ class ConfigMapSummary(BaseModel):
     namespace: str
     key_count: int
     data_size: int  # total bytes across all values (data + binary_data)
-    age: datetime.timedelta
+    age: Duration
 
 
 def _configmap_key_count_and_size(config_map) -> tuple[int, int]:
@@ -1548,7 +1583,7 @@ class StatefulSetSummary(BaseModel):
     current_replicas: int
     update_strategy: str
     service_name: Optional[str] = None
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_statefulset_summaries(namespace: Optional[str] = None) -> list[StatefulSetSummary]:
@@ -1679,9 +1714,9 @@ class CronJobSummary(BaseModel):
     schedule: str
     suspend: bool
     active: int
-    last_schedule_time: Optional[datetime.timedelta] = None
-    last_successful_time: Optional[datetime.timedelta] = None
-    age: datetime.timedelta
+    last_schedule_time: Optional[Duration] = None
+    last_successful_time: Optional[Duration] = None
+    age: Duration
     containers: list[ContainerTemplateSummary] = Field(default_factory=list)
 
 
@@ -1791,10 +1826,10 @@ class JobSummary(BaseModel):
     active: int
     succeeded: int
     failed: int
-    start_time: Optional[datetime.timedelta] = None
-    completion_time: Optional[datetime.timedelta] = None
+    start_time: Optional[Duration] = None
+    completion_time: Optional[Duration] = None
     conditions: list[str] = Field(default_factory=list)
-    age: datetime.timedelta
+    age: Duration
     containers: list[ContainerTemplateSummary] = Field(default_factory=list)
 
 
@@ -2041,7 +2076,7 @@ class PVCSummary(BaseModel):
     access_modes: list[str] = Field(default_factory=list)
     storage_class: Optional[str] = None
     mounted_by: list[str] = Field(default_factory=list)
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_pvc_summaries(namespace: Optional[str] = None) -> list[PVCSummary]:

{k8stools-2.0.2 → k8stools-2.0.3}/src/k8stools/mock_state.py

@@ -76,9 +76,18 @@ class CaptureFormatError(Exception):
 # ---------------------------------------------------------------------------
 
 def _annotation_contains(annotation: Any, target: type) -> bool:
-    """True if ``target`` appears anywhere in ``annotation`` (unwrapping Optional/Union)."""
+    """True if ``target`` appears anywhere in ``annotation``.
+
+    Unwraps ``Optional``/``Union`` and ``Annotated``. The latter matters because
+    ``k8s_tools.Duration`` is an annotated ``timedelta``: pydantic strips the
+    metadata from a bare field's ``annotation`` but keeps it inside an
+    ``Optional[...]``, so without this an optional duration would silently encode
+    under its plain name instead of ``<field>_seconds`` and fail to round-trip.
+    """
     if annotation is target:
         return True
+    if hasattr(annotation, "__metadata__"):  # Annotated[X, ...] -> X
+        return _annotation_contains(typing.get_args(annotation)[0], target)
     origin = typing.get_origin(annotation)
     if origin is Union or origin is types.UnionType:
         return any(_annotation_contains(arg, target) for arg in typing.get_args(annotation))

{k8stools-2.0.2 → k8stools-2.0.3}/src/k8stools/redaction.py

@@ -29,7 +29,9 @@ Two independent signals trigger a redaction:
 
 1. **Value shape** — the string looks like a credential regardless of where it
    sits: AWS access keys (``AKIA...``), bearer/JWT tokens (``eyJ...``), or PEM
-   private-key blocks.
+   private-key blocks. A self-contained token is replaced where it sits, leaving
+   the rest of the surrounding text readable; a PEM header stands for a secret
+   that continues past the match, so that value goes in full.
 2. **Key / field name** — the enclosing map key, model field, or env-var name
    contains one of ``key``, ``secret``, ``token``, ``password``, ``passwd``,
    ``credential``, ``cred`` **as a whole word**. Names are split on separators and
@@ -48,6 +50,14 @@ Two independent signals trigger a redaction:
    nothing. The exemption does not apply to env-var names, where a variable a user
    named ``KEY`` plausibly does hold one.
 
+A string value that is itself a JSON object or array — config-as-JSON under a
+single ConfigMap key is a common pattern — is parsed and redacted entry by entry
+rather than treated as one opaque blob, then re-serialized (which normalizes its
+whitespace). Both rules apply inside, so an incidental token match no longer
+blacks out a whole config file and a ``{"password": ...}`` buried in one no longer
+escapes the name rule. Inside such a blob the ``key`` exemption is lifted: those
+names are the author's, not Kubernetes schema.
+
 Expect occasional false positives on high-entropy-but-non-secret values. The
 visible marker and the opt-out make that tolerable. This is a defense-in-depth
 aid, not a guarantee — callers that need strong guarantees should still scrub on
@@ -60,10 +70,11 @@ redaction layer) get raw, un-redacted return values and can call
 
 import copy
 import functools
+import json
 import logging
 import os
 import re
-from typing import Any
+from typing import Any, Optional
 
 from pydantic import BaseModel
 
@@ -127,17 +138,91 @@ def _field_name_is_sensitive(name: str) -> bool:
         return False
     return _name_is_sensitive(name)
 
-#: Value-shape patterns — a string value matching any of these is redacted
-#: regardless of the key it lives under.
-_VALUE_SHAPE_RES = (
+#: Value-shape patterns whose match *is* the whole secret. Because the match is
+#: self-contained, only the matched span needs to go — the surrounding text is
+#: ordinary config and stays readable.
+_TOKEN_SHAPE_RES = (
     re.compile(r"\bAKIA[0-9A-Z]{16}\b"),                              # AWS access key id
     re.compile(r"\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+"),  # JWT / bearer token
+)
+
+#: Value-shape patterns that merely *mark* a secret whose sensitive part lies
+#: outside the match. A PEM header is the whole of the match but none of the
+#: secret - the key material is the base64 body that follows - so a value matching
+#: one of these is replaced in full. Substituting only the matched span here would
+#: black out the `-----BEGIN RSA PRIVATE KEY-----` line and publish the key.
+_CONTAINMENT_SHAPE_RES = (
     re.compile(r"-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----"),       # PEM private key block
 )
 
 
 def _value_is_secret_shaped(s: str) -> bool:
-    return any(rx.search(s) for rx in _VALUE_SHAPE_RES)
+    """Whether ``s`` matches any value-shape pattern, anywhere in the string."""
+    return any(
+        rx.search(s) for rx in (*_TOKEN_SHAPE_RES, *_CONTAINMENT_SHAPE_RES)
+    )
+
+
+def _redact_json_string(s: str) -> Optional[tuple[str, int]]:
+    """Redact inside a string that is itself a JSON document.
+
+    Storing config-as-JSON under a single ConfigMap key is a common pattern, and
+    it defeats a redactor that treats every string as one opaque value in *both*
+    directions: one incidental token match blacks out an entire config file, while
+    a real ``{"password": "..."}`` inside the blob is invisible to the key-name
+    rule and passes through verbatim. Parsing, recursing, and re-serializing fixes
+    both — a match redacts its own entry and nothing else.
+
+    Returns ``None`` when ``s`` is not a JSON object/array, or when recursion found
+    nothing, so the caller falls through and the original text is left byte-for-byte
+    intact. Re-serialization otherwise normalizes whitespace, which is why it only
+    happens when there is actually something to hide.
+    """
+    stripped = s.strip()
+    # Cheap gate: only objects and arrays are worth parsing. It also keeps bare
+    # scalars ("5", "true") from round-tripping through json.dumps.
+    if not stripped or stripped[0] not in "{[":
+        return None
+    try:
+        parsed = json.loads(stripped)
+    except (ValueError, RecursionError):
+        return None
+    if not isinstance(parsed, (dict, list)):
+        return None
+    # The `key` exemption applies in here too. Lifting it looked right - these are
+    # the author's field names, not Kubernetes schema - but measured against a real
+    # cluster it added 12 redactions, all of them `tags[].key: "instance"` in a
+    # Grafana dashboard ConfigMap, and no secrets. Structural `key` fields dominate
+    # inside config documents exactly as they do in the API. A credential-shaped
+    # value under a `key` field is still caught by the value-shape rules.
+    redacted, count = _redact(parsed)
+    if not count:
+        return None
+    return json.dumps(redacted, indent=2 if "\n" in s else None), count
+
+
+def _redact_string(value: str, key_is_sensitive: bool) -> tuple[str, int]:
+    """Redact a single string value. See :func:`_redact` for the parameters."""
+    if value == REDACTED:
+        return value, 0
+    if key_is_sensitive:
+        return REDACTED, 1
+
+    # Before treating the string as opaque text, see whether it is structured. A
+    # PEM block nested inside a JSON blob is handled by this recursion too: it
+    # arrives back here as a leaf and hits the containment rule below.
+    nested = _redact_json_string(value)
+    if nested is not None:
+        return nested
+
+    if any(rx.search(value) for rx in _CONTAINMENT_SHAPE_RES):
+        return REDACTED, 1
+
+    count = 0
+    for rx in _TOKEN_SHAPE_RES:
+        value, n = rx.subn(REDACTED, value)
+        count += n
+    return value, count
 
 
 def _redact(value: Any, key_is_sensitive: bool = False) -> tuple[Any, int]:
@@ -147,11 +232,7 @@ def _redact(value: Any, key_is_sensitive: bool = False) -> tuple[Any, int]:
     strings are immutable so the parent assigns the replacement.
     """
     if isinstance(value, str):
-        if value == REDACTED:
-            return value, 0
-        if key_is_sensitive or _value_is_secret_shaped(value):
-            return REDACTED, 1
-        return value, 0
+        return _redact_string(value, key_is_sensitive)
 
     if isinstance(value, BaseModel):
         count = 0

{k8stools-2.0.2 → k8stools-2.0.3}/tests/test_capture.py

@@ -288,10 +288,14 @@ def test_a_containers_name_cannot_redact_its_own_logs(monkeypatch):
     assert pod["previous_logs"]["valkey-cart"] == log
 
     # A secret-shaped value inside a log is still caught, as on the live server.
+    # Only the token's own span goes: a log line is mostly diagnostics, and the
+    # surrounding text is the part an agent is reading the log for.
     monkeypatch.setattr(k8s_tools, "get_logs_for_pod_and_container",
                         lambda *a, **kw: f"token={_FakeCluster.JWT}")
     state = capture_state(redact=True)
-    assert state["pods"][0]["logs"]["valkey-cart"] == "[REDACTED]"
+    captured_log = state["pods"][0]["logs"]["valkey-cart"]
+    assert _FakeCluster.JWT not in captured_log
+    assert captured_log == "token=[REDACTED]"
 
 
 def test_pod_labels_are_not_subject_to_the_key_name_heuristic(monkeypatch):

k8stools-2.0.3/tests/test_duration_format.py

@@ -0,0 +1,182 @@
+"""Tests that `timedelta` fields serialize to values their own schema accepts.
+
+Pydantic describes a `timedelta` field as `{"type": "string", "format": "duration"}`
+but serializes one carrying microseconds as `"P2DT5M27.978616S"`. JSON Schema's
+`duration` format references RFC 3339 Appendix A, whose grammar admits only whole
+numbers - so the default schema and the default serializer contradict each other,
+and an MCP client that validates structured output against the declared schema
+(ajv does) rejects the call outright, on every row, before the caller sees data.
+
+Every age here is `now() - <k8s timestamp>`; Kubernetes timestamps are whole-second,
+so the fractional part is always just the microseconds of that `now()` - which is
+why this reproduced on essentially every row of every list tool against a live
+cluster, while the largely whole-second mock fixture mostly hid it.
+
+`k8s_tools.Duration` normalizes the value so the declared format stays truthful.
+"""
+
+import datetime
+import inspect
+import re
+import typing
+
+import pytest
+from pydantic import BaseModel
+
+from k8stools import k8s_tools, mock_tools
+
+
+#: RFC 3339 Appendix A `duration`, the grammar JSON Schema's `format: "duration"`
+#: points at. Transcribed from ajv-formats, which is what the reporting client used.
+#: Note there is no decimal point anywhere in it, and no sign.
+RFC3339_DURATION_RE = re.compile(
+    r"^P(?!$)((\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?|(\d+W)?)$"
+)
+
+#: A duration with a sub-second component, as every live-cluster age has.
+FRACTIONAL = datetime.timedelta(days=2, minutes=5, seconds=27, microseconds=978616)
+
+
+def _duration_fields(model: type[BaseModel]) -> list[str]:
+    """Field names whose *serialization* schema declares `format: "duration"`.
+
+    Read off the generated schema rather than the annotation, so the test asserts
+    against exactly what an MCP client is handed and told to validate against.
+    """
+    schema = model.model_json_schema(mode="serialization")
+    names = []
+    for name, prop in schema.get("properties", {}).items():
+        branches = [prop, *prop.get("anyOf", [])]
+        if any(b.get("format") == "duration" for b in branches):
+            names.append(name)
+    return names
+
+
+def _models_with_durations() -> list[type[BaseModel]]:
+    return [
+        obj for obj in vars(k8s_tools).values()
+        if inspect.isclass(obj) and issubclass(obj, BaseModel)
+        and obj is not BaseModel and _duration_fields(obj)
+    ]
+
+
+def _accepts_none(annotation) -> bool:
+    return type(None) in typing.get_args(annotation)
+
+
+def _placeholder(annotation):
+    """A minimal value satisfying `annotation`, for the fields we aren't testing."""
+    if _accepts_none(annotation):
+        return None
+    origin = typing.get_origin(annotation) or annotation
+    return {str: "x", int: 0, bool: False, float: 0.0, list: [], dict: {}}.get(origin)
+
+
+def _build(model: type[BaseModel], value, overrides=None) -> BaseModel:
+    """Instantiate `model`, putting `value` in every duration field.
+
+    `overrides` replaces individual fields afterwards, for the cases where one
+    duration field needs a different value than the rest.
+    """
+    durations = _duration_fields(model)
+    kwargs = {}
+    for name, field in model.model_fields.items():
+        if name in durations:
+            kwargs[name] = value
+        elif field.is_required():
+            kwargs[name] = _placeholder(field.annotation)
+    kwargs.update(overrides or {})
+    return model(**kwargs)
+
+
+# --- the normalization itself -----------------------------------------------
+
+@pytest.mark.parametrize("given,expected_seconds", [
+    (datetime.timedelta(seconds=27, microseconds=978616), 27),
+    (datetime.timedelta(microseconds=1), 0),
+    (datetime.timedelta(0), 0),
+    (datetime.timedelta(days=8), 8 * 86400),
+    # A cluster clock ahead of ours yields a negative age, which pydantic renders
+    # as "-PT5S" - no more valid under this grammar than a fractional one.
+    (datetime.timedelta(seconds=-5), 0),
+    (datetime.timedelta(days=-2), 0),
+])
+def test_durations_are_truncated_to_whole_nonnegative_seconds(given, expected_seconds):
+    assert k8s_tools._to_whole_seconds(given) == datetime.timedelta(seconds=expected_seconds)
+
+
+def test_field_keeps_a_real_timedelta_for_direct_python_callers():
+    """Normalizing the value, not the type: `.age` is still a timedelta."""
+    ns = k8s_tools.NamespaceSummary(name="d", status="Active", age=FRACTIONAL)
+    assert isinstance(ns.age, datetime.timedelta)
+    assert ns.age == datetime.timedelta(days=2, minutes=5, seconds=27)
+
+
+def test_the_declared_schema_still_says_duration():
+    """The fix must not paper over the problem by dropping the format annotation."""
+    prop = k8s_tools.NamespaceSummary.model_json_schema()["properties"]["age"]
+    assert prop == {"title": "Age", "type": "string", "format": "duration"}
+
+
+# --- every model, against its own declared schema ---------------------------
+
+def test_there_are_duration_fields_to_check():
+    """Guard against the sweeps below silently degrading to no-ops."""
+    models = _models_with_durations()
+    assert len(models) >= 10
+    assert k8s_tools.PodSummary in models
+
+
+@pytest.mark.parametrize("model", _models_with_durations(), ids=lambda m: m.__name__)
+def test_fractional_input_serializes_within_the_declared_format(model):
+    dumped = _build(model, FRACTIONAL).model_dump(mode="json")
+    for name in _duration_fields(model):
+        assert RFC3339_DURATION_RE.match(dumped[name]), \
+            f"{model.__name__}.{name} = {dumped[name]!r} violates format: duration"
+
+
+@pytest.mark.parametrize("model", _models_with_durations(), ids=lambda m: m.__name__)
+def test_optional_duration_fields_still_accept_none(model):
+    """Normalization must not turn an absent duration into PT0S."""
+    optional = [n for n in _duration_fields(model)
+                if _accepts_none(model.model_fields[n].annotation)]
+    if not optional:
+        pytest.skip(f"{model.__name__} has no optional duration field")
+    dumped = _build(model, FRACTIONAL, {n: None for n in optional}).model_dump(mode="json")
+    for name in optional:
+        assert dumped[name] is None
+
+
+# --- end to end, over the actual tool surface -------------------------------
+
+@pytest.mark.parametrize("tool", mock_tools.TOOLS, ids=lambda f: f.__name__)
+def test_every_tool_emits_conformant_durations(tool):
+    """The end-to-end shape of the bug report: call the tool, validate every
+    duration in its structured output against the format its schema declares."""
+    mock_tools.load_mock_state()
+    params = inspect.signature(tool).parameters
+    if any(p.default is inspect.Parameter.empty for p in params.values()):
+        pytest.skip(f"{tool.__name__} needs arguments")
+    result = tool()
+
+    items = result if isinstance(result, list) else [result]
+    for item in items:
+        if not isinstance(item, BaseModel):
+            continue
+        dumped = item.model_dump(mode="json")
+        for name in _duration_fields(type(item)):
+            if dumped[name] is None:
+                continue
+            assert RFC3339_DURATION_RE.match(dumped[name]), \
+                f"{tool.__name__} -> {type(item).__name__}.{name} = " \
+                f"{dumped[name]!r} violates format: duration"
+
+
+def test_mock_namespaces_were_the_reproducing_case():
+    """`get_namespaces` is the no-argument reproducer from the report, and the one
+    place the mock fixture did carry fractional seconds (`P1Y55DT1H37M32.49238S`)."""
+    mock_tools.load_mock_state()
+    ages = [ns.model_dump(mode="json")["age"] for ns in mock_tools.get_namespaces()]
+    assert ages, "fixture should have namespaces"
+    for age in ages:
+        assert RFC3339_DURATION_RE.match(age), f"{age!r} violates format: duration"

{k8stools-2.0.2 → k8stools-2.0.3}/tests/test_redaction.py

@@ -246,3 +246,125 @@ def test_value_shape_still_wins_regardless_of_name():
     assert out["key"] == REDACTED
     assert out["hockey"] == REDACTED
     assert count == 2
+
+
+# --- granularity: a match should not black out unrelated text ----------------
+#
+# Reported against 2.0.2: a ConfigMap holding config-as-JSON under one key came
+# back as `{"warm-runtimes.json": "[REDACTED]"}` because one substring inside the
+# blob matched a value-shape pattern. The whole file - warm-pool sizing, nothing
+# secret - became unreadable. The same opacity cut the other way too: secrets
+# named inside such a blob were invisible to the key-name rule entirely.
+
+_JWT = "eyJhbGciOiJIUzI1Ni.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w"
+_PEM = ("-----BEGIN RSA PRIVATE KEY-----\n"
+        "MIIEowIBAAKCAQEAsecretkeymaterial123456\n"
+        "-----END RSA PRIVATE KEY-----")
+
+
+def test_a_token_inside_a_plain_string_redacts_only_its_own_span():
+    out, count = redact_object({"note": f"use {_JWT} to authenticate"})
+    assert out["note"] == f"use {REDACTED} to authenticate"
+    assert count == 1
+
+
+def test_a_pem_block_is_still_redacted_in_full():
+    """The PEM pattern matches only the header; the key material is what follows.
+    Substituting just the matched span would black out the BEGIN line and publish
+    the key, so a value containing a PEM header goes in its entirety."""
+    out, count = redact_object({"blob": f"leading text\n{_PEM}\ntrailing text"})
+    assert out["blob"] == REDACTED
+    assert "MIIEowIBAAKCAQEAsecretkeymaterial123456" not in str(out)
+    assert count == 1
+
+
+def test_json_configmap_value_keeps_everything_but_the_match():
+    """The reported case: one incidental token match must not hide the config."""
+    import json
+    blob = json.dumps({"target_count": 5, "runtimes": ["v1", "v2"],
+                       "bootstrap": _JWT}, indent=2)
+    out, count = redact_object({
+        "name": "warm-runtimes-config", "namespace": "openhands-cloud-c3",
+        "data": {"warm-runtimes.json": blob}, "binary_data_keys": []})
+    redacted = json.loads(out["data"]["warm-runtimes.json"])
+    assert redacted["target_count"] == 5          # the number they needed
+    assert redacted["runtimes"] == ["v1", "v2"]
+    assert redacted["bootstrap"] == REDACTED
+    assert count == 1
+
+
+def test_secrets_named_inside_a_json_blob_are_found():
+    """The under-redaction half: before this, the key-name rule could not see
+    into a JSON string, so these passed through verbatim."""
+    import json
+    blob = json.dumps({"db": {"password": "hunter2", "api_token": "abc"},
+                       "host": "db.internal"})
+    out, count = redact_object({"data": {"app.json": blob}})
+    redacted = json.loads(out["data"]["app.json"])
+    assert redacted["db"]["password"] == REDACTED
+    assert redacted["db"]["api_token"] == REDACTED
+    assert redacted["host"] == "db.internal"
+    assert count == 2
+
+
+def test_a_pem_nested_in_a_json_blob_goes_whole_but_takes_nothing_else():
+    import json
+    blob = json.dumps({"cert": "public-cert-data", "priv": _PEM, "port": 443})
+    out, count = redact_object({"data": {"tls.json": blob}})
+    redacted = json.loads(out["data"]["tls.json"])
+    assert redacted["priv"] == REDACTED
+    assert redacted["cert"] == "public-cert-data"
+    assert redacted["port"] == 443
+    assert count == 1
+
+
+def test_the_key_exemption_holds_inside_a_json_blob_too():
+    """Lifting the exemption in here looked right - these are the author's field
+    names, not Kubernetes schema - but measured against a real 38-pod cluster it
+    added 12 redactions, every one of them `tags[].key: "instance"` in a Grafana
+    dashboard ConfigMap, and not one secret. Structural `key` fields dominate
+    inside config documents just as they do in the API."""
+    import json
+    blob = json.dumps({"targets": [{"tags": [{"key": "instance", "value": "db-1"}]}]})
+    out, count = redact_object({"data": {"dash.json": blob}})
+    assert out["data"]["dash.json"] == blob   # untouched, not even re-serialized
+    assert count == 0
+
+
+def test_a_credential_shaped_value_under_key_is_still_caught_inside_a_blob():
+    """What keeps the exemption affordable: the value-shape rules do not care
+    what the field is called."""
+    import json
+    blob = json.dumps({"key": "AKIAIOSFODNN7EXAMPLE"})
+    out, count = redact_object({"data": {"cfg.json": blob}})
+    assert json.loads(out["data"]["cfg.json"])["key"] == REDACTED
+    assert count == 1
+
+
+def test_a_clean_json_value_is_left_byte_for_byte_alone():
+    """No match means no re-serialization, so formatting is never churned."""
+    original = '{\n    "count": 5,\n    "name": "pool"\n}'
+    out, count = redact_object({"data": {"cfg.json": original}})
+    assert out["data"]["cfg.json"] == original
+    assert count == 0
+
+
+@pytest.mark.parametrize("value", [
+    "not json at all", "{broken json", "", "   ",
+    "5", "true", "null", '"just a string"',
+])
+def test_non_container_json_values_are_untouched(value):
+    """Bare scalars must not round-trip through the JSON path."""
+    out, count = redact_object({"data": {"k": value}})
+    assert out["data"]["k"] == value
+    assert count == 0
+
+
+def test_a_json_array_blob_is_also_recursed():
+    import json
+    blob = json.dumps([{"name": "a", "token": "s3kr1t"}, {"name": "b", "port": 80}])
+    out, count = redact_object({"data": {"list.json": blob}})
+    redacted = json.loads(out["data"]["list.json"])
+    assert redacted[0]["token"] == REDACTED
+    assert redacted[1]["port"] == 80
+    assert count == 1

k8stools-2.0.3/time-bug-report.md

@@ -0,0 +1,159 @@
+# Bug report: `datetime.timedelta` fields produce values that fail strict `format: "duration"` JSON-Schema validation
+
+## Summary
+
+Every k8stools MCP tool whose Pydantic response model includes a `datetime.timedelta`
+field (`age`, `last_seen`) emits a value shape that is rejected by MCP clients that do
+strict JSON-Schema `format: "duration"` validation of structured tool output. When this
+happens, the tool call fails outright with an MCP protocol error — the client never sees
+any data, even though the underlying tool executed successfully and the payload is
+"reasonable" ISO 8601.
+
+This is not tied to a particular cluster or tool argument — it reproduces on `get_namespaces()`
+(no arguments) and on every list-summary tool tested.
+
+## Environment
+
+- `k8stools` version: **2.0.2** (installed via `uv`/PyPI, unmodified)
+- Invocation: `k8s-mcp-server --transport=streamable-http` (no `--mock`, no `--state-file` —
+  live cluster)
+- Python: 3.12.11
+- `mcp` SDK: whatever version `k8stools==2.0.2` pulls in via `uv.lock` (server uses
+  `mcp.server.mcpserver.MCPServer` / `Tool.from_function(fn, structured_output=True)`)
+- Client: an MCP client that validates tool call results against the tool's declared
+  `outputSchema` (structured content validation), rejecting non-conformant responses before
+  the caller ever sees the data.
+
+## Steps to reproduce
+
+1. Start the server: `k8s-mcp-server --transport=streamable-http`
+2. Call the `get_namespaces` tool (or `get_pod_summaries`, `get_events`, etc.) via an MCP
+   client that validates structured output against the tool's JSON output schema.
+3. Observe the call fail with a schema-validation error instead of returning data.
+
+## Actual error (verbatim, trimmed)
+
+```
+MCP error -32602: Structured content does not match the tool's output schema:
+data/result/0/age must match format "duration",
+data/result/1/age must match format "duration",
+...
+```
+
+and, for `Optional[timedelta]` fields:
+
+```
+data/result/0/last_seen must match format "duration",
+data/result/0/last_seen must be null,
+data/result/0/last_seen must match a schema in anyOf,
+...
+```
+
+Every element in the result array fails identically — this is not a per-record data quality
+issue, it's a structural mismatch between every timedelta value and the schema that describes it.
+
+## Root cause
+
+`k8s_tools.py` declares timing fields as plain `datetime.timedelta` on `BaseModel` subclasses,
+e.g.:
+
+```464:467:k8stools/k8s_tools.py (site-packages copy)
+class PodSummary(BaseModel):
+    """A summary of a pod's status like returned by `kubectl get pods -o wide`"""
+    ...
+    last_restart: Optional[datetime.timedelta]
+    age: datetime.timedelta
+```
+
+```89:93:k8stools/k8s_tools.py (site-packages copy)
+class NamespaceSummary(BaseModel):
+    """Summary information about a namespace, like returned by `kubectl get namespace`"""
+    name: str
+    status: str
+    age: datetime.timedelta
+```
+
+```504:509:k8stools/k8s_tools.py (site-packages copy)
+class EventSummary(BaseModel):
+    """This is the representation of a Kubernetes Event"""
+    last_seen: Optional[datetime.timedelta]  # Time since event occurred
+    type: str
+    reason: str
+    object: str
+    message: str
+```
+
+Pydantic v2's default JSON Schema generation for `datetime.timedelta` emits
+`{"type": "string", "format": "duration"}`, and its default *value* serialization for a
+`timedelta` produces an ISO 8601 duration string that **includes fractional (sub-second)
+seconds when the timedelta has microsecond precision**, e.g. the values actually observed
+over the wire:
+
+```
+"P2DT5M27.978616S"
+"PT10H56M59.978616S"
+"PT50M41.978616S"
+```
+
+These are computed as `now() - <k8s object's creationTimestamp / lastTimestamp>`. Since
+Kubernetes' own timestamps are whole-second (no sub-second component), the fractional part
+of every one of these values is just `now()`'s microseconds — which is why it's identical
+across every row in a single response (all computed from one `now()` call). That's expected
+and not itself a bug; the bug is that this fractional value is legal ISO 8601 but is **not**
+legal per the stricter grammar that JSON Schema's `format: "duration"` keyword references
+(RFC 3339 Appendix A), which most conformant/strict format validators implement. That grammar
+requires each duration component to be a plain (integer) digit sequence — it does not permit a
+decimal point anywhere, including in the seconds component. A validator that enforces this
+strictly will reject `"P2DT5M27.978616S"` even though it is a well-formed, human-readable ISO
+8601 duration.
+
+In short: **pydantic's own default schema (`format: "duration"`) and pydantic's own default
+serialization (fractional-second ISO 8601 strings) are mutually inconsistent** under any
+validator that takes `format: "duration"` seriously. Any MCP client that validates structured
+output strictly against the declared schema will intermittently or consistently break on
+every tool that surfaces an `age` or `last_seen` field — i.e., essentially all of the
+list/summary tools (`get_namespaces`, `get_node_summaries`, `get_pod_summaries`, `get_events`,
+`get_pod_events`, `get_deployment_summaries`, `get_replicaset_summaries`,
+`get_statefulset_summaries`, `get_cronjob_summaries`, `get_job_summaries`, `get_pvc_summaries`,
+`get_service_summaries`, `get_configmap_summaries`).
+
+## Why this seemed to "come and go" in our testing
+
+We saw calls to these same tools **succeed** with these exact fractional-second value shapes
+earlier in the same day, then start failing after simply restarting the MCP server process
+(no code/version change on the server side — same `k8stools==2.0.2`, same venv, same
+`k8s-mcp-server` binary, confirmed via `pip`/`uv.lock`/site-packages timestamps). That strongly
+suggests the validation strictness is a property of the **client's** connection/session
+(e.g., whether it negotiates or enables structured-output validation on a given connection),
+not of the server. That's a plausible explanation for the inconsistent symptom, but it doesn't
+change the underlying defect: the server is emitting values that don't conform to its own
+declared schema, and **any** strictly-validating client — now or in the future — will hit this
+100% of the time on 100% of rows.
+
+## Suggested fixes (any one of these resolves it)
+
+1. **Truncate to whole seconds before serialization.** Drop microseconds from every
+   `timedelta` before it's placed on a response model (e.g. `age.total_seconds()` rounded, or
+   reconstruct a `timedelta(seconds=int(age.total_seconds()))`). Minute-granularity age/last-seen
+   data doesn't need microsecond precision anyway, and this keeps the `format: "duration"`
+   schema annotation truthful.
+2. **Stop declaring `format: "duration"`** on these fields (e.g. represent `age`/`last_seen` as
+   a plain `str` computed via the existing `_format_timedelta()` helper already used for CLI
+   output, rather than a native `timedelta`). This sidesteps the whole format-conformance
+   question and gives every consumer a human-readable string like `"53m46s"` instead.
+3. **Provide a custom serializer** (`@field_serializer` in Pydantic v2) for these fields that
+   emits a strictly RFC 3339 Appendix A–conformant duration string (no fractional component —
+   round to the nearest second), while leaving the field type as `timedelta` for typing
+   purposes.
+
+Option 1 or 3 preserve the current "real" `timedelta`/duration semantics; option 2 is the
+simplest and most robust against any future client strictness, at the cost of losing a
+machine-parseable duration type in the schema.
+
+## Impact
+
+Total loss of function for every affected tool when called through a strictly-validating MCP
+client — the call fails outright with no data, rather than degrading gracefully. This blocked
+a live production-incident investigation (watching pod/event state during a load test) because
+every relevant tool (`get_pod_summaries`, `get_events`) was unusable after a routine server
+restart, with no code change on either side.

{k8stools-2.0.2 → k8stools-2.0.3}/uv.lock

@@ -544,7 +544,7 @@ wheels = [
 
 [[package]]
 name = "k8stools"
-version = "2.0.2"
+version = "2.0.3"
 source = { editable = "." }
 dependencies = [
     { name = "kubernetes" },