ipa-diagnose 0.1.0__tar.gz

ipa_diagnose-0.1.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 ipa-diagnose contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ipa_diagnose-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: ipa-diagnose
+Version: 0.1.0
+Summary: Evidence-grounded diagnostic and correlation engine for FreeIPA / Red Hat IdM administrators
+Author: ipa-diagnose contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/InfraGuard-Labs/ipa-diagnose
+Project-URL: Issues, https://github.com/InfraGuard-Labs/ipa-diagnose/issues
+Keywords: freeipa,ipa,identity-management,kerberos,ldap,diagnostics,sysadmin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<15,>=13.7
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.40; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1,>=0.34; extra == "anthropic"
+Provides-Extra: bedrock
+Requires-Dist: boto3<2,>=1.34; extra == "bedrock"
+Provides-Extra: ai
+Requires-Dist: ipa-diagnose[anthropic,bedrock,openai]; extra == "ai"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-cov<6,>=5; extra == "dev"
+Dynamic: license-file
+
+# ipa-diagnose
+
+**`ipa-healthcheck` tells you a check failed. `ipa-diagnose` tells you which
+failures are related, what's actually wrong, why you should believe that,
+what it affects, what to do first, whether that's safe, and how to confirm
+it's fixed.**
+
+It is a deterministic, evidence-grounded correlation engine that sits on top
+of `ipa-healthcheck` plus a handful of targeted, read-only collectors
+(`journalctl`, `getcert list`, `ipa-replica-manage`, `dig`, `klist`/`kvno`,
+read-only `ldapsearch`). AI (OpenAI, Anthropic, or AWS Bedrock) is entirely
+optional and only ever explains a diagnosis the deterministic engine already
+computed - it never decides the root cause, invents evidence, or invents a
+command to run.
+
+![Primary root-cause diagnosis](artifacts/screenshots/03_primary_root_cause.png)
+
+## Why this exists
+
+`ipa-healthcheck` is FreeIPA's own excellent diagnostic tool, and
+`ipa-diagnose` does not reimplement or replace it - it reads its JSON output.
+But by design, `ipa-healthcheck` only checks one host in isolation: it does
+not correlate two related failures into one story, does not read logs, does
+not explain impact, and does not recommend a next step (this is confirmed by
+reading its own source and documentation, not assumed - see
+[docs/research.md](docs/research.md)). An administrator staring at ten
+failing checks after a bad night still has to work out, by hand, which one
+is the actual problem and which nine are just symptoms.
+
+`ipa-diagnose` is the layer that does that correlation, deterministically,
+with every claim traceable back to real evidence:
+
+```text
+DETECT → COLLECT EVIDENCE → CORRELATE → DIAGNOSE → EXPLAIN → RECOMMEND → VERIFY
+```
+
+## Example
+
+Three independent-looking `ipa-healthcheck` failures - a DNS record check, a
+`named` service check, and a Kerberos KDC-discovery failure on a client -
+turn out to be one problem:
+
+![Correlated findings](artifacts/screenshots/04_correlated_findings.png)
+
+And when the evidence genuinely isn't enough to tell two causes apart,
+`ipa-diagnose` says so instead of guessing:
+
+![Unknown result](artifacts/screenshots/06_unknown_insufficient_evidence.png)
+
+See [artifacts/screenshots/index.md](artifacts/screenshots/index.md) for all
+19 captured scenarios (healthy, degraded, multiple independent problems,
+`--details`, CAUTION/HIGH-RISK actions, `verify`, all three AI providers,
+AI-failure fallback, the `ai-preview` redaction view, malformed input, and
+the real RPM install) - every one of them is real recorded output from the
+actual application, not a mockup.
+
+## Installation
+
+**Target experience** (once published to a COPR repository - see
+[packaging/rpm/README.md](packaging/rpm/README.md) for the one remaining
+manual publish step):
+
+```bash
+sudo dnf copr enable <maintainer>/ipa-diagnose
+sudo dnf install ipa-diagnose
+sudo ipa-diagnose
+```
+
+**Available today** (PyPI/pipx - works on any RHEL/CentOS/Fedora host with
+Python 3.9+, and is also the right path for development, testing, and early
+adoption):
+
+```bash
+pipx install ipa-diagnose
+sudo ipa-diagnose
+```
+
+**Building and testing the RPM yourself**, entirely in Docker, with zero
+host installs, is documented in
+[packaging/rpm/README.md](packaging/rpm/README.md) - it walks through
+building the RPM, running it through a full install/upgrade/uninstall
+lifecycle in a clean Fedora container, and building the `.src.rpm` COPR
+would build from.
+
+`ipa-diagnose` needs to run where `ipa-healthcheck` and the FreeIPA/389-DS
+tooling it shells out to already exist - i.e., on an actual IPA server or
+client, as root (or with `sudo`).
+
+## Quick start
+
+```bash
+sudo ipa-diagnose                 # diagnose (default)
+sudo ipa-diagnose --details       # full evidence, confidence, every action
+sudo ipa-diagnose --json          # machine-readable, for automation
+sudo ipa-diagnose verify          # did the problem actually clear?
+sudo ipa-diagnose ai-preview      # see exactly what would be sent to an AI provider
+sudo ipa-diagnose --no-ai         # never contact any AI provider (also the default)
+```
+
+Try it without a live FreeIPA host, against the same fixtures used in
+testing and screenshots:
+
+```bash
+docker compose run --rm dev ipa-diagnose --replay tests/fixtures/replication/peer-unreachable diagnose
+```
+
+## Architecture
+
+```text
+ipa-healthcheck JSON  +  targeted read-only evidence
+        │           (journalctl, getcert, ipa-replica-manage, dig, klist/kvno, ldapsearch)
+        ▼
+Evidence Normalizer  (every fact keeps its provenance: which command produced it)
+        ▼
+Privacy / Redaction  (secret detection + minimum-evidence-selection, before anything
+        │             could reach an AI provider - see docs/security-privacy.md)
+        ▼
+Diagnostic Engine  (5 versioned packs: replication, certificates, kerberos, dns,
+        │           directory-server - see docs/diagnostic-packs.md)
+        ▼
+Correlation + Prioritization  (deterministic - PRIMARY / RELATED SYMPTOM /
+        │                      SECONDARY INDEPENDENT / WARNING; UNKNOWN is a first-class outcome)
+        ▼
+Structured Diagnosis
+   ┌────────┴────────┐
+   ▼                 ▼
+Local Explanation   Optional AI (OpenAI | Anthropic | Bedrock) - explains only,
+   └────────┬────────┘          never decides (see docs/ai-configuration.md)
+            ▼
+           CLI
+            ▼
+        Verification  (`ipa-diagnose verify` re-collects evidence and re-diagnoses -
+                        never trusts a remediation command's exit code alone)
+```
+
+Full writeup, including the design rationale for each stage, is in
+[docs/architecture.md](docs/architecture.md).
+
+## Supported diagnoses (v1)
+
+Five diagnostic packs, chosen because they're where `ipa-healthcheck`'s own
+single-host, no-correlation, no-log-analysis design leaves the most value on
+the table (see [docs/research.md](docs/research.md) for the full gap
+analysis against `ipa-healthcheck`):
+
+| Pack | Covers | Ambiguity it explicitly refuses to guess through |
+|---|---|---|
+| **Replication** | Peer connectivity breaks, replication conflicts, stale RUVs, topology disconnection | Conflict entries mean replication *is* transmitting writes, not that it's broken - a documented trap this pack does not fall into |
+| **Certificates / CA** | Stuck certmonger renewals, expired certs, RA-agent/Dogtag desync, unreachable renewal master | `CA_UNREACHABLE` has 3+ unrelated root causes sharing one state name; only DIAGNOSES when the actual error text is specific enough |
+| **Kerberos** | Clock skew, keytab/KVNO mismatch, DNS-caused KDC discovery failure | "Preauthentication failed" is a generic bucket produced by all three causes - only a direct KVNO comparison counts as proof of a keytab problem |
+| **DNS** | `named`/bind-dyndb-ldap down, forward-zone/empty-zone collisions, broken SRV/autodiscovery records | A documented `ipa-healthcheck` false-positive (issue #270) means WARNING-only SRV findings are treated with extra skepticism, not trusted blindly |
+| **Directory Server / LDAP** | Disk exhaustion, ownership/SELinux mismatches, NSS/TLS DB format issues, missing indexes | An NSS DB format mismatch looks exactly like an expired certificate - this pack explicitly says so rather than misattributing it |
+
+Each pack's rules, sourcing, and confidence levels are documented in
+[docs/diagnostic-packs.md](docs/diagnostic-packs.md).
+
+## The evidence model
+
+Every `Finding` and `EvidenceItem` the engine reasons about carries a
+`Provenance` - the exact command that produced it. `--details` shows this;
+nothing is ever "the tool just knows this." Full model in
+[docs/architecture.md](docs/architecture.md#evidence-model).
+
+## Diagnostic packs, in one sentence each
+
+See [docs/diagnostic-packs.md](docs/diagnostic-packs.md) for the full
+evidence/confidence/action/verification breakdown per rule, with citations.
+
+## Security and privacy
+
+FreeIPA is identity infrastructure; `ipa-diagnose` treats all evidence as
+potentially sensitive. Before anything can reach an external AI provider, it
+passes through: normalization → minimum-evidence-selection (only what a
+diagnosis actually cites) → secret detection (field-name **and**
+pattern-based) → redaction → truncation. Run `ipa-diagnose ai-preview` to see
+the *exact* payload that would be sent, every time, with a redaction summary
+- the preview and the real call share the same code path, so it cannot lie
+to you. Full detail, including the adversarial tests (prompt injection,
+secret leakage, command injection, malformed input) in
+[docs/security-privacy.md](docs/security-privacy.md).
+
+## AI configuration (entirely optional)
+
+```bash
+export OPENAI_API_KEY=...       && sudo ipa-diagnose --ai-provider openai
+export ANTHROPIC_API_KEY=...    && sudo ipa-diagnose --ai-provider anthropic
+# Bedrock uses boto3's normal credential chain (IAM role, env vars, ~/.aws/)
+sudo ipa-diagnose --ai-provider bedrock
+```
+
+AI provider SDKs are optional extras - `pip install ipa-diagnose[openai]`,
+`[anthropic]`, `[bedrock]`, or `[ai]` for all three - so the base install has
+no AI-related dependencies at all, and `--no-ai` (the default) requires
+none of them. If a provider fails, times out, or returns something that
+looks like a fabricated command, `ipa-diagnose` silently falls back to the
+local, deterministic explanation - it never blocks or degrades the core
+diagnosis. Full detail in [docs/ai-configuration.md](docs/ai-configuration.md).
+
+## Verification
+
+```bash
+sudo ipa-diagnose verify
+```
+
+Re-collects evidence and re-runs the full diagnostic engine, then diffs the
+result against the last run - `RESOLVED`, `STILL_PRESENT`,
+`PARTIALLY_RESOLVED`, or `UNABLE_TO_VERIFY`. It never claims success just
+because a remediation command happened to exit `0` (a real, documented
+FreeIPA case - `ipa group-del` reporting "Insufficient access" while still
+deleting the group - is exactly the kind of false signal this avoids). Full
+detail in [docs/verification.md](docs/verification.md).
+
+Something not behaving as expected? See
+[docs/troubleshooting.md](docs/troubleshooting.md) first.
+
+## Development (Docker only)
+
+Nothing is installed on the host - everything runs inside the `ipa-diagnose`
+Docker Compose project:
+
+```bash
+docker compose build dev
+docker compose run --rm test          # full test suite
+docker compose run --rm dev bash      # interactive shell
+```
+
+99 tests: unit tests for the engine/correlation/redaction core, per-pack
+fixture tests (one directory per scenario under `tests/fixtures/`, each with
+an expected outcome in `meta.json`), and an adversarial suite covering false
+correlation, prompt injection, secret leakage, command injection, and
+malformed/oversized input. See [docs/limitations.md](docs/limitations.md)
+for what's fixture-validated vs. container-integration-tested vs. genuinely
+real-FreeIPA-validated - this project does not overclaim which is which.
+
+## Limitations
+
+- **Single-host by design**, same as `ipa-healthcheck` itself - some
+  questions (is every DNS server in the topology serving correct records?
+  has RUV fully converged across all masters?) genuinely need a multi-host
+  view this tool doesn't have. Where a rule's confidence is capped for this
+  reason, it says so in `--details`.
+- **v1 covers 5 diagnostic packs**, not every FreeIPA subsystem. See
+  [docs/limitations.md](docs/limitations.md) for the full list of what's
+  deliberately out of scope for now.
+- **Diagnosis-first, not auto-remediation.** `ipa-diagnose` never executes a
+  CAUTION or HIGH-RISK action automatically, and v1 has no "fix it for me"
+  mode. That is a deliberate scope decision, not a missing feature.
+
+## Contributing
+
+See [docs/contributing.md](docs/contributing.md) - in short: everything
+builds and tests in Docker, every new diagnostic rule needs a fixture with
+an expected outcome, and "I'm not sure" (`UNKNOWN_*`) is always an
+acceptable, often correct, answer for a rule to give.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).