How amine-lg/lineage works
1. What this repository is
- Lineage is a read-only OpenShift access explainer. Its core job is to turn cluster authorization objects into an explainable relationship graph: who can do what, where, and through which chain of bindings, groups, SCCs, and image relationships.
2. Top-level runtime shape
- The app has two primary entry paths: a local Python process (run.py, lineage/__main__.py, lineage/cli.py) and an in-cluster deployment built from Containerfile plus the deploy/openshift/ manifests.
- It supports three modes: mock data, local real-cluster access via the current oc login context, and in-cluster execution under a dedicated ServiceAccount.
3. Cluster access boundary
- lineage/cluster.py is the main boundary to the OpenShift API and auth checks. The README makes clear the app is intentionally read-only and relies on get, list, and oc auth can-i.
- This boundary is where the app reads cluster state such as Users, Identities, Groups, ServiceAccounts, RoleBindings, ClusterRoleBindings, SCCs, namespaces, workloads, ImageStreams, and images.
4. Core analysis engine
- lineage/engine/ is the analytical heart of the repo. Its modules are split by concern:
- _rbac for RBAC relationships,
- _scc for SecurityContextConstraints,
- _images for image pull/push and image-stream relationships,
- _ghosts, _resurrectable, and _identity_audit for stale, missing, or re-creatable references,
- _who_can and _classify for reachability and labeling,
- _constants for shared rules and thresholds.
- This layer converts raw cluster objects into derived findings and lineage paths.
5. Data and domain shaping
- lineage/data.py, lineage/classifier.py, and lineage/openshift/shapes.py define the repository’s domain vocabulary and normalization rules.
- These pieces help the engine treat OpenShift-specific objects consistently, especially for object identity, subject kinds, and the “live vs dormant vs resurrectable” distinctions used throughout the UI.
6. Derived findings and special cases
- The repository does more than show direct grants. It explicitly models:
- ghost bindings for missing users/groups/ServiceAccounts,
- latent/phantom/stranded/orphan identity states,
- resurrectable ServiceAccount and namespace-based SCC access,
- future SCC targets where RBAC grants reference an SCC name that does not yet exist.
- These are treated as review signals and are separated from ordinary live access.
7. UI architecture
- Presentation is split between server-side templates in lineage/templates/ and UI composition logic in lineage/ui/.
- lineage/ui/pages/ appears to organize page-level view models and page assembly for major screens such as home, identities, images, namespaces, permissions, SCCs, and subjects.
- lineage/ui/buckets.py, filters.py, and view_models.py provide grouping, display filtering, and shape conversion for the rendered pages.
8. Rendered pages and navigation
- The templates correspond closely to the app’s exploration model: home, setup, aggregated views, namespace detail, subject detail, role/clusterrole detail, SCC detail, who-can analysis, permission grants, images, and identity audit.
- Shared partials like _kind.html, _markers.html, _rule_cells.html, and _resurrectable_table.html indicate the UI is built from reusable classification and evidence blocks rather than ad hoc pages.
9. Static frontend assets
- lineage/static/lineage.js and lineage/static/style.css supply interactive behavior and styling, but the repo is not structured like a full SPA. The overall architecture is server-rendered with light client-side enhancement.
10. Data sources and operational assumptions
- The app assumes OpenShift-shaped inputs, not generic Kubernetes. The README and docs emphasize that v1 is intentionally OpenShift-focused.
- It also has an optional HTPasswd integration path, which affects identity completeness and degraded-visibility handling when the underlying user directory cannot be fully read.
11. Deployment and platform integration
- deploy/openshift/ contains the production path: namespace creation, RBAC, build config, optional HTPasswd RBAC, deployment, and route exposure.
- This means the system can be run as a cluster-native read-only service with explicit permissions rather than requiring a locally authenticated operator session.
12. Test and validation boundary
- tests/ covers the engine, page behavior, sorting, degraded visibility, mock dataset behavior, and OpenShift-specific edge cases such as ghost lineage, SCC target detection, and resurrectable grants.
- The test suite is part of the architecture: it verifies the correctness of derived lineage, not just HTTP rendering.
13. Key architectural flow
- In practice the flow is: OpenShift cluster state and auth context in → cluster adapter and data normalization → engine analysis/classification → page/view-model assembly → templates and static assets out.
- The repo’s main design goal is to keep the raw cluster read boundary separate from the analysis engine and from the presentation layer, so the explanations remain auditable and safe to run.
Main entry points: cluster.py Cluster API · main.py App core · __init__.py Page assembly · test_engine.py Test suite
Components 22
Runtime
Local entrypoints and the in-cluster delivery path.
- Run script · Local process launcher.
run.py - Module entry · Python package entrypoint.
lineage/__main__.py - CLI · Command-line interface and mode selection.
lineage/cli.py - App core · High-level application flow and setup.
lineage/main.py
Analysis
Cluster access, normalization, and lineage derivation.
- Cluster API · Read-only boundary to OpenShift auth and objects.
lineage/cluster.py - Domain data · Shared object vocabulary and identity shaping.
lineage/data.py - Classifier · Object classification and state interpretation.
lineage/classifier.py - Shape rules · OpenShift-specific shape and subject normalization.
lineage/openshift/shapes.py - RBAC graph · Role, binding, and subject relationship expansion.
lineage/engine/_rbac.py - SCC analysis · SecurityContextConstraints reachability and grants.
lineage/engine/_scc.py - Image links · Image pull, push, and ImageStream relationships.
lineage/engine/_images.py - Ghosts · Missing or stale subjects and bindings.
lineage/engine/_ghosts.py - Resurrectable · Latent access that can reappear from namespace or SA state.
lineage/engine/_resurrectable.py - Identity audit · Identity completeness and degraded-visibility checks.
lineage/engine/_identity_audit.py - Who-can · Reachability queries and permission discovery.
lineage/engine/_who_can.py - Labeling · Shared derived labels and classification helpers.
lineage/engine/_classify.py
Presentation
Page assembly, templates, and light client-side behavior.
- Page assembly · Page-level view models and screen assembly.
lineage/ui/pages/__init__.py - View models · Rendered display models and aggregation helpers.
lineage/ui/view_models.py - Templates · HTML templates for detail and overview pages.
lineage/templates/base.html - Frontend assets · Lightweight client-side behavior and styling.
lineage/static/lineage.js
Delivery
OpenShift manifests and validation coverage.
- OpenShift deploy · Namespace, RBAC, build, deployment, and route manifests.
deploy/openshift/30-deployment.yaml - Test suite · Behavioral coverage for engine, pages, and OpenShift edge cases.
tests/test_engine.py
Connections 30
- Run script → CLI: launches · Local script hands control to the CLI.
- Module entry → CLI: dispatches · Package entrypoint routes into the CLI.
- CLI → App core: starts · CLI selects mode and starts the application.
- App core → Cluster API: reads · Core app creates the read-only cluster boundary.
- App core → Domain data: normalizes · Core app uses shared domain shaping.
- App core → Classifier: labels · Core app relies on object classification.
- App core → Page assembly: assembles · Core app builds page-level outputs.
- Domain data → Shape rules: adapts · Domain vocabulary is aligned to OpenShift shapes.
- Classifier → Labeling: feeds · Classification helpers support derived labels.
- Cluster API → RBAC graph: supplies · Cluster objects feed RBAC expansion.
- Cluster API → SCC analysis: supplies · Cluster objects feed SCC analysis.
- Cluster API → Image links: supplies · Cluster objects feed image relationship analysis.
- Cluster API → Ghosts: supplies · Cluster state is checked for missing references.
- Cluster API → Resurrectable: supplies · Cluster state is checked for latent access paths.
- Cluster API → Identity audit: supplies · Cluster state is checked for identity completeness.
- Cluster API → Who-can: queries · Auth context and objects support reachability queries.
- RBAC graph → Who-can: powers · RBAC relationships underpin who-can analysis.
- SCC analysis → Resurrectable: contributes · SCC grants can become resurrectable access.
- Ghosts → Page assembly: signals · Derived ghost states are surfaced in UI views.
- Identity audit → Page assembly: signals · Identity audit findings feed dedicated pages.
- Image links → Page assembly: renders · Image relationships are presented in image views.
- Who-can → Page assembly: renders · Permission reachability drives permission pages.
- Page assembly → View models: uses · Pages are assembled from shared view models.
- View models → Templates: renders · View models are rendered by server templates.
- Templates → Frontend assets: enhanced by · Templates are lightly enhanced by static assets.
- OpenShift deploy → Cluster API: runs in · OpenShift manifests provide the in-cluster execution path.
- Test suite → App core: verifies · Tests cover orchestration and mode selection.
- Test suite → Cluster API: verifies · Tests cover read-boundary and visibility behavior.
- Test suite → RBAC graph: verifies · Tests cover derived authorization relationships.
- Test suite → Ghosts: verifies · Tests cover ghost and missing-reference logic.