elder

README

Elder

*

*Limited AGPL v3 with preamble for fair use - Personal and Internal Use Only

███████╗██╗     ██████╗ ███████╗██████╗
██╔════╝██║     ██╔══██╗██╔════╝██╔══██╗
█████╗  ██║     ██║  ██║█████╗  ██████╔╝
██╔══╝  ██║     ██║  ██║██╔══╝  ██╔══██╗
███████╗███████╗██████╔╝███████╗██║  ██║
╚══════╝╚══════╝╚═════╝ ╚══════╝╚═╝  ╚═╝

Resource, Entity, Element & Relationship Tracking System

Enterprise-grade infrastructure dependency tracking and visualization

Elder is a comprehensive resource, entity, element, and relationship tracking system designed for modern infrastructure management. Track dependencies, visualize relationships, and maintain control across complex organizational structures.

✅ MariaDB Galera Cluster Compatible - Full support for multi-master replication and high-availability deployments

🌐 Website | 📚 Documentation | 💬 Discussions

Overview

Elder provides visibility into your infrastructure and organizational relationships through:

Resource Types (Dedicated Models)

Resources have dedicated database models with specialized schemas for better data modeling:

• Identity: Users, service accounts, API keys with multi-provider sync (Okta, LDAP, AWS, GCP)
• Software: Track applications, libraries, and tools with SBOM integration
• Services: Microservices with endpoints, health checks, and on-call rotations
• Network: VPCs, subnets, firewalls, load balancers with topology mapping
• IPAM: IP address management with prefixes, addresses, and VLANs
• Data Stores: S3, GCS, Azure Blob, NAS, SAN, databases with compliance metadata (PII, PHI, PCI)

Entity Types (Generic Tracking)

Entities use a flexible schema for infrastructure components:

Category	Sub-types
Network	Subnet, Firewall, Proxy, Router, Switch, Hub, Tunnel, Route Table, VRRF, VXLAN, VLAN, Namespace
Compute	Server, Serverless, Laptop, Mobile, Desktop, Kubernetes Node, VM, K8s Cluster, Function Run
Storage	Hard Disk, NVMe, SSD, Virtual Disk, External Drive, Database, Caching, Queue System
Datacenter	Public VPC, Private VPC, Physical, Closet
Security	Vulnerability, Architectural, Config, Compliance, Code, Regulatory

Elements (Supporting Items)

• Issues: Problem/task tracking attached to any resource or entity
• Labels: Categorization and tagging system
• Metadata Fields: Custom properties for extensibility
• Dependencies: Relationship mapping between items
• Comments: Collaboration and audit trail
• Milestones: Timeline tracking tied to projects and goals
• On-Call Rotations: Schedule duty rotations with automatic participant cycling
• License Policies: License key and feature entitlement management

Core Capabilities

• Dependency Mapping: Visualize relationships between entities
• Organizational Hierarchy: Manage Company → Department → Team structures
• Unified IAM: Manage identities across AWS, Azure, GCP, Okta, LDAP with group management
• SSO Integration: SAML 2.0, OpenID Connect (OIDC), and SCIM 2.0 provisioning
• Secrets Management: Integrate with Vault, AWS Secrets Manager, GCP Secret Manager
• Network Topology: Track VPCs, subnets, peering, VPN connections
• Project Sync: Bi-directional sync with GitHub, GitLab, Jira, Trello, OpenProject
• Enterprise Features: Audit logging, RBAC, MFA, SSO, multi-tenant, license management
• Backups: S3/cloud backup jobs with scheduling and point-in-time restore
• Webhooks: Event-driven notifications for entity and issue lifecycle events
• SBOM Dashboard: Software Bill of Materials inventory with vulnerability tracking
• Multi-Tenancy: Tenant isolation and management for enterprise deployments
• Global Search: Full-text search across all resource types and entities
• Audit Logging: Comprehensive action logging with admin filtering
• Network Topology Map: Interactive visualization of infrastructure relationships

Screenshots

Login & Dashboard

Login

Dashboard

Asset Management

Organizations	Entities
Software	Services
Data Stores (v3.0.0)	Dependencies

Project Tracking

Projects

Issues

Security & Identity

Identity Center	Secrets Management
API Keys	Certificates

Discovery & Profile

Discovery

Profile

Key Features

Core Capabilities

• ✅ Dual Data Model: 6 Resource types (dedicated schemas) + 5 Entity categories (flexible schema)
• ✅ Multi-Entity Support: 5 entity categories with 40+ sub-types
• ✅ Hierarchical Organizations: Unlimited depth organizational structures
• ✅ Dependency Graphs: Visualize complex entity relationships
• ✅ Full RBAC: Role-based permissions with org-scoped access
• ✅ Multi-Auth: Local, SAML, OAuth2, OIDC, and LDAP authentication
• ✅ RESTful & gRPC APIs: Complete API coverage
• ✅ Audit Logging: Comprehensive audit trail for compliance
• ✅ MariaDB Galera: Full support for multi-master MySQL clustering

v3.2.3 Highlights (Latest)

• AWS IAM Identity Sync Fix (Issue #112): AuthProvider enum was missing AWS = "aws" and both auth_provider and identity_type SQLAlchemy columns were storing uppercase enum member names (LOCAL, HUMAN) instead of lowercase values (local, human) due to missing values_callable. Fix adds AWS provider, normalises all stored values via Alembic migration 014, and adds regression tests to prevent recurrence.
• Docker Desktop Alpha Support: Smoke-test script now auto-detects platform (Apple Silicon vs amd64) — no more forced --platform linux/amd64 QEMU emulation on M-series Macs.
• react-libs 1.3.4: Migrated from GitHub Packages to public npm; updated Playwright selectors for new sidebar DOM structure.

v3.2.2 Highlights

• K8s /tmp emptyDir Mounts: Added emptyDir volumes for /tmp in all pod specs — fixes write failures in read-only root filesystem containers.
• API 500 Fixes: Resolved 500 errors surfaced during alpha smoke tests.
• AWS Connector: Dedup, dependency linking, and IAM identity sync groundwork (prerequisite for #112).
• Cilium HTTPRoute: Wired Cilium Gateway API HTTPRoute for beta ingress migration.
• CI Pin Updates: Bumped CI dependency pins to v3.2.2.

License Tiers

Elder uses a fair-use licensing model with the Limited AGPL v3 license:

• Personal & Internal Use: Free for individual and internal organizational use
• Commercial Use: Requires a commercial license from Penguin Tech Inc
• Modifications: Must be shared under the same license terms (AGPL)
• SaaS Deployment: Requires commercial license if providing Elder as a service

For commercial licensing inquiries: sales@penguintech.io

Quick Start

Prerequisites

• Kubernetes (primary): MicroK8s, Docker Desktop K8s, or Podman Desktop K8s
• kubectl + helm v3: For K8s deployments
• Docker: For local image builds (alpha dev only)
• Python 3.13+: For local development without K8s
• Node.js 18+: For Web UI development

Note: Docker Compose is deprecated. All environments (alpha, beta, prod) deploy to Kubernetes.

Kubernetes Deployment (Recommended)

Elder supports deployment to Kubernetes clusters (MicroK8s, kind, k3s, or standard Kubernetes) using Helm.

Quick Local Deployment:

# Install to local Kubernetes cluster
cd infrastructure/helm/elder
helm dependency update
helm install elder . \
  --set config.secretKey="$(openssl rand -base64 32)" \
  --set postgresql.auth.password="$(openssl rand -base64 32)" \
  --set redis.auth.password="$(openssl rand -base64 32)"

# Wait for deployment
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=elder --timeout=5m

# Access via port-forward
kubectl port-forward svc/elder-api 8080:80
kubectl port-forward svc/elder-web 3000:80

GitHub Actions CI/CD:

Elder includes automated Kubernetes deployment via GitHub Actions. To set up:

# 1. Run the setup script on your cluster
./scripts/k8s/setup-github-serviceaccount.sh

# 2. Add the output secrets to GitHub:
#    - KUBE_CONFIG
#    - K8S_NAMESPACE
#    - SECRET_KEY
#    - POSTGRES_PASSWORD
#    - REDIS_PASSWORD

# 3. Push to main branch - automatic deployment!

Resources:

• 📖 Local Kubernetes Setup Guide
• 🔧 GitHub Actions Kubernetes Deployment
• ⚙️ Helm Chart Documentation

Configuration

Key environment variables:

# Database (PyDAL supports PostgreSQL, MySQL/MariaDB, SQLite, Oracle, MSSQL)
# PostgreSQL (recommended)
DATABASE_URL=postgresql://elder:password@localhost:5432/elder

# MariaDB Galera Cluster (high availability)
# DATABASE_URL=mysql://elder:password@galera-node1:3306/elder?wsrep_sync_wait=1

# Redis
REDIS_URL=redis://:password@localhost:6379/0

# Authentication
SAML_ENABLED=true
OIDC_ENABLED=true
OAUTH2_ENABLED=true
LDAP_ENABLED=true

# License (optional)
LICENSE_KEY=PENG-XXXX-XXXX-XXXX-XXXX-XXXX

# Admin User
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me
ADMIN_EMAIL=admin@example.com

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Client Layer                         │
│  React UI │ REST Clients │ gRPC Clients                 │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                   API Layer                             │
│  Flask REST │ gRPC Server │ WebSocket                   │
│  JWT Auth │ RBAC │ Rate Limiting                        │
└─────────────────────────────────────────────────────────┘
              │                        │
┌─────────────────────────┐  ┌────────────────────────────┐
│     Worker Service      │  │     Scanner Service        │
│  Cloud Discovery Exec   │  │  Network / Banner / SBOM   │
│  Connector State Sync   │  │  HTTP Screenshot Capture   │
│  Credential Refresh     │  │  Endpoint Parser           │
└─────────────────────────┘  └────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                   Data Layer                            │
│  PyDAL (PostgreSQL, MySQL/MariaDB Galera, SQLite)       │
│  Redis/Valkey (Cache, Sessions)                         │
└─────────────────────────────────────────────────────────┘

Technology Stack

• Backend: Flask (Python 3.13), PyDAL
• Worker: Python background service — cloud discovery, connector sync, credential refresh
• Scanner: Python scanner service — network, SBOM, HTTP screenshot, endpoint parser
• Frontend: React, TypeScript, Vite, Tailwind CSS, ReactFlow
• Database: PostgreSQL (recommended), MySQL/MariaDB Galera, SQLite
• Cache: Redis / Valkey
• APIs: REST (OpenAPI 3.0), gRPC
• Auth: JWT, SAML, OIDC, OAuth2, LDAP, SCIM 2.0
• Connectors: AWS, GCP, Kubernetes, Okta, LDAP, vCenter, FleetDM, iBoss
• Monitoring: Prometheus, Grafana
• Deployment: Kubernetes (Helm + Kustomize), MicroK8s local dev

Scanners & Integrations

Scanners

Elder includes built-in scanners for automated discovery and security analysis:

Scanner	Description
Network Scanner	Discover hosts, open ports, and network topology
Banner Scanner	Grab service banners for version identification
HTTP Screenshot	Capture screenshots of web services for visual inventory
SBOM Scanner	Software Bill of Materials generation and vulnerability detection

Connectors (Integrators)

Bi-directional sync with identity providers and infrastructure platforms:

Connector	Capabilities
AWS	EC2, VPC, IAM, S3, RDS discovery and sync
GCP	Compute Engine, VPC, IAM, Cloud Storage sync
Kubernetes	Clusters, namespaces, deployments, services
Okta	Users, groups, applications with write-back
LDAP/AD	Directory users and groups with bidirectional sync
Google Workspace	Users, groups, organizational units
vCenter	VMware VMs, hosts, clusters, datastores
FleetDM	Endpoint management and osquery integration
iBoss	Cloud security gateway policy sync
Authentik	Open-source identity provider integration

SBOM Parsers

Parse dependency files from multiple ecosystems for vulnerability tracking:

Parser	File Types
Python	requirements.txt, setup.py, pyproject.toml, Pipfile
Node.js	package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
Go	go.mod, go.sum
Rust	Cargo.toml, Cargo.lock
Java/Maven	pom.xml
Gradle	build.gradle, build.gradle.kts
.NET	csproj, fsproj, packages.config

Endpoint Parsers

Discover API endpoints from source code for service mapping:

• Flask (Python)
• FastAPI (Python)
• Django (Python)
• Express (Node.js)
• Go (net/http, Gin, Echo)

Documentation

Document	Description
API Reference	REST & gRPC API documentation
Database Schema	Database structure and PyDAL usage
Sync Documentation	Project management sync setup
Backup Configuration	S3 backup setup
Usage Guide	User guide and workflows
Contributing	Contribution guidelines
Release Notes	Version history

Development

# Development
make dev              # Start postgres and redis
make dev-api          # Start Flask API
make dev-all          # Start all services

# Testing
make test             # Run all tests
make lint             # Run linters
make format           # Format code

# Docker
make docker-build     # Build Docker image
make docker-scan      # Scan for vulnerabilities

Security

• ✅ Multi-factor authentication
• ✅ Fine-grained RBAC with org-scoped permissions
• ✅ TLS 1.3 enforcement
• ✅ Input validation with PyDAL validators
• ✅ SQL injection prevention
• ✅ Audit logging
• ✅ Container scanning with Trivy

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Elder is licensed under the Limited AGPL v3 with Fair Use Preamble. See LICENSE.md for details.

License Highlights:

• Personal & Internal Use: Free under AGPL-3.0
• Commercial Use: Requires commercial license
• SaaS Deployment: Requires commercial license if providing Elder as a service

Contributor Employer Exception (GPL-2.0 Grant)

Companies employing official contributors receive GPL-2.0 access to community features:

• Perpetual for Contributed Versions: GPL-2.0 rights to versions where the employee contributed remain valid permanently, even after the employee leaves the company
• Attribution Required: Employee must be credited in CONTRIBUTORS, AUTHORS, commit history, or release notes
• Future Versions: New versions released after employment ends require standard licensing
• Community Only: Enterprise features still require a commercial license

This exception rewards contributors by providing lasting fair use rights to their employers. See LICENSE.md for full terms.

Support

• Company Homepage: www.penguintech.io
• Documentation: docs.penguintech.io/elder
• Issues: GitHub Issues
• Email: support@penguintech.io

Default Login Credentials

For local development and testing, Elder creates a default admin user:

Field	Value
URL	http://localhost:3005
Email	admin@localhost.local
Password	admin123
Tenant	System (ID: 1)

Warning: Change the default password immediately in production environments by setting the ADMIN_PASSWORD environment variable before first startup.

---

Elder - Know Your Infrastructure, Understand Your Dependencies

© 2025-2026 Penguin Tech Inc. All rights reserved.