{"id":30746768,"url":"https://github.com/madhuakula/spotter","last_synced_at":"2025-09-04T04:28:21.901Z","repository":{"id":308782846,"uuid":"1029339299","full_name":"madhuakula/spotter","owner":"madhuakula","description":"Spotter is a comprehensive Kubernetes security scanner that uses CEL-based rules to identify security vulnerabilities, misconfigurations, and compliance violations across your Kubernetes clusters, manifests, and CI/CD pipelines.","archived":false,"fork":false,"pushed_at":"2025-08-23T09:38:52.000Z","size":753,"stargazers_count":26,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T15:04:56.023Z","etag":null,"topics":["cloud","cloud-security","kubernetes","policy","security"],"latest_commit_sha":null,"homepage":"https://spotter.run","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madhuakula.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-30T22:33:12.000Z","updated_at":"2025-08-28T02:48:14.000Z","dependencies_parsed_at":"2025-08-07T22:26:43.882Z","dependency_job_id":null,"html_url":"https://github.com/madhuakula/spotter","commit_stats":null,"previous_names":["madhuakula/spotter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/madhuakula/spotter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madhuakula%2Fspotter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madhuakula%2Fspotter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madhuakula%2Fspotter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madhuakula%2Fspotter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madhuakula","download_url":"https://codeload.github.com/madhuakula/spotter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madhuakula%2Fspotter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273550458,"owners_count":25125505,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud","cloud-security","kubernetes","policy","security"],"created_at":"2025-09-04T04:28:17.371Z","updated_at":"2025-09-04T04:28:21.889Z","avatar_url":"https://github.com/madhuakula.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\u003ca href=\"https://spotter.run\" rel=\"spotter.run\"\u003e\u003cimg src=\"img/spotter-horizontal.svg\" alt=\"Spotter Logo\" width=\"350\"\u003e\u003c/a\u003e\u003c/p\u003e\n  \u003cp align=\"center\"\u003e⚡️Universal Kubernetes Security Engine\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/madhuakula/spotter)](https://goreportcard.com/report/github.com/madhuakula/spotter)\n[![License](https://img.shields.io/github/license/madhuakula/spotter)](https://github.com/madhuakula/spotter/blob/main/LICENSE)\n[![Release](https://img.shields.io/github/v/release/madhuakula/spotter)](https://github.com/madhuakula/spotter/releases)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/madhuakula/spotter)\n\n\u003c/div\u003e\n\n**Spotter** is a comprehensive Kubernetes security scanner that helps identify security misconfigurations, vulnerabilities, and compliance issues in your Kubernetes clusters and manifests. Built with extensibility and performance in mind, Spotter uses the Common Expression Language (CEL) for flexible rule definitions and supports multiple output formats including SARIF for seamless CI/CD integration.\n\n## 📋 Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Architecture](#-architecture)\n- [Features](#-features)\n- [Configuration](#-configuration)\n- [Security Categories](#-security-categories)\n- [Rule Development](#-rule-development)\n- [Contributing](#-contributing)\n- [Documentation](#-documentation)\n\n## 🚀 Quick Start\n\n### Installation\n\n#### Using Go Install\n```bash\ngo install github.com/madhuakula/spotter@latest\n```\n\n#### Using Docker\n```bash\ndocker pull ghcr.io/madhuakula/spotter:latest\n```\n\n#### Download Binary\nDownload the latest release from [GitHub Releases](https://github.com/madhuakula/spotter/releases).\n\n### Basic Usage\n\n#### Scan Kubernetes Manifests\n```bash\n# Scan a single manifest file\nspotter scan manifests --path deployment.yaml\n\n# Scan a directory of manifests\nspotter scan manifests --path ./k8s-manifests/\n\n# Scan with custom rules\nspotter scan manifests --path ./manifests/ --rules-path ./custom-rules/\n\n# Scan using custom rules\nspotter scan manifests ./manifests --rules-path ./rules\n\n# Output in JSON format\nspotter scan manifests --path ./manifests/ --output json\n```\n\n#### Scan Live Kubernetes Cluster\n```bash\n# Scan current cluster context\nspotter scan cluster\n\n# Scan specific namespace\nspotter scan cluster --namespace production\n\n# Scan with specific kubeconfig\nspotter scan cluster --kubeconfig ~/.kube/config\n\n# Scan cluster using only custom rules\nspotter scan cluster --rules-path ./rules\n```\n\n#### Rule Management\n```bash\n# List available rules\nspotter rules list\n\n# Validate custom rules\nspotter rules validate --path ./custom-rules/\n\n# Show rule details\nspotter rules show --id SPOTTER-WORKLOAD-SECURITY-101\n```\n\n## 📖 Documentation\n\n### User Guides\n- [Installation Guide](docs/installation.md) - Detailed installation instructions\n- [User Guide](docs/user-guide.md) - Comprehensive usage documentation\n- [Configuration Guide](docs/configuration.md) - Configuration options and examples\n- [Rules Guide](docs/rules.md) - Understanding and creating security rules\n\n## 🏗️ Architecture\n\nSpotter follows a modular architecture designed for extensibility and performance:\n\n```\n  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n  │   CLI Layer     │    │   Config Layer  │    │  Output Layer   │\n  │                 │    │                 │    │                 │\n  │ • Commands      │    │ • YAML Config   │    │ • Table         │\n  │ • Flags         │    │ • Validation    │    │ • JSON          │\n  │ • Help          │    │ • Defaults      │    │ • SARIF         │\n  └─────────────────┘    └─────────────────┘    └─────────────────┘\n          │                       │                       │\n          └───────────────────────┼───────────────────────┘\n                                  │\n┌─────────────────────────────────┼─────────────────────────────────┐\n│                        Core Engine                                │\n│                                                                   │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐ │\n│  │  Scanner    │  │    Rules    │  │   Reporter  │  │  Metrics  │ │\n│  │             │  │             │  │             │  │           │ │\n│  │ • Manifest  │  │ • Local     │  │ • Formatter │  │ • Timing  │ │\n│  │ • Cluster   │  │ • Custom    │  │ • Writer    │  │ • Counts  │ │\n│  │ • Workers   │  │ • CEL       │  │ • Streaming │  │ • Errors  │ │\n│  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘ │\n└───────────────────────────────────────────────────────────────────┘\n         │                       │                       │\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│  Data Sources   │    │   Rule Engine   │    │   Integrations  │\n│                 │    │                 │    │                 │\n│ • YAML Files    │    │ • CEL Evaluator │    │ • Kubernetes    │\n│ • Kubernetes    │    │ • Rule Matcher  │    │ • CI/CD         │\n│ • Directories   │    │ • Validation    │    │ • Monitoring    │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n## 🚀 Features\n\n### 🔒 Security Scanning\n- **Comprehensive Rule Set**: Access to security rules covering OWASP Kubernetes Top 10, CIS Kubernetes Benchmark, and NSA/CISA guidelines via the hub\n- **Custom Rules**: Define your own security rules using CEL expressions\n- **Multi-Resource Support**: Scan Pods, Deployments, Services, ConfigMaps, Secrets, and more\n- **Real-time Cluster Scanning**: Connect to live Kubernetes clusters for runtime security assessment\n\n### 🚀 Performance \u0026 Scalability\n- **Concurrent Processing**: Multi-threaded scanning for large clusters and manifest collections\n- **Memory Efficient**: Optimized for scanning large numbers of resources\n- **Configurable Workers**: Tune performance based on your environment\n\n### 📊 Flexible Output\n- **Multiple Formats**: Table, JSON, YAML, and SARIF output formats\n- **CI/CD Integration**: SARIF support for GitHub Security tab and other security platforms\n- **Detailed Reports**: Comprehensive violation details with remediation guidance\n- **Severity Levels**: CRITICAL, HIGH, MEDIUM, and LOW classifications\n\n### 🔧 Developer Experience\n- **CLI Interface**: Intuitive command-line interface with comprehensive help\n- **Configuration Files**: YAML-based configuration for consistent scanning\n- **Extensible Architecture**: Plugin-based design for custom scanners and reporters\n- **Rich Documentation**: Comprehensive guides for users and contributors\n\n### Key Components\n\n- **Scanner**: Handles resource discovery and processing\n- **Rule Engine**: Evaluates CEL expressions against Kubernetes resources\n- **Reporter**: Formats and outputs scan results\n- **Config Manager**: Manages configuration and rule loading\n- **Metrics**: Collects performance and usage statistics\n\n## 🔧 Configuration\n\nSpotter can be configured using YAML files, environment variables, or command-line (higher priority) flags:\n\n```yaml\n# spotter.yaml\n# Global Configuration\nlog-level: info\nverbose: true\nno-color: false\ntimeout: 5m\noutput: table\noutput-file: \"\"\nkubeconfig: \"\"\n\n# Common scan options (applies to all scan types)\ninclude-rules: []\nexclude-rules: []\ncategories: []\nparallelism: 4\nmin-severity: \"\"\nmax-violations: 0\nquiet: false\nsummary-only: false\n\n# Scan-specific configurations\nscan:\n  # Cluster scanning configuration\n  cluster:\n    namespace: []\n    exclude-namespaces: []\n    exclude-system-namespaces: false\n    resource-types: []\n    include-cluster-resources: true\n    context: \"\"\n\n  # Manifest scanning configuration  \n  manifests:\n    recursive: true\n    file-extensions: [\".yaml\", \".yml\", \".json\"]\n    include-paths: []\n    follow-symlinks: false\n    exclude-system-namespaces: false\n    include-cluster-resources: true\n\n  # Helm chart scanning configuration\n  helm:\n    values: []\n    set: []\n    set-string: []\n    release-name: \"test-release\"\n    namespace: \"default\"\n    include-dependencies: true\n    validate-schema: true\n    kube-version: \"\"\n    chart-repo: \"\"\n    chart-version: \"\"\n    update-dependencies: false\n    exclude-system-namespaces: false\n    include-cluster-resources: true\n    skip-tests: false\n    skip-crds: false\n\n# External rules configuration\nrules-path: []\n```\n\n### Using Configuration Files\n\n```bash\n# Use a specific config file\nspotter scan manifests ./manifests --config spotter.yaml\n\n# Override config values with flags\nspotter scan cluster --config production.yaml --min-severity high --parallelism 8\n```\n\n## 🛡️ Security Rules\n\nSpotter provides access to comprehensive security rules via the hub and supports custom rule creation:\n\n### Available Rule Categories\n\n- Workload Security\n- Access Control\n- Network \u0026 Traffic Security\n- Secrets \u0026 Data Protection\n- Configuration \u0026 Resource Hygiene\n- Supply Chain \u0026 Image Security\n- CI/CD \u0026 GitOps Security\n- Runtime Threat Detection\n- Audit, Logging \u0026 Compliance\n- Platform \u0026 Infrastructure Security\n\n### Custom Rule Example\n\n```yaml\napiVersion: rules.spotter.dev/v1alpha1\nkind: SpotterRule\nmetadata:\n  name: unique-name\n  labels:\n    category: \"Workload Security\"\n    severity: high\n\nspec:\n  id: SPOTTER-\u003cCATEGORY\u003e-\u003cNNN\u003e\n  name: \"Readable Rule Name\"\n  version: \"1.0.0\"\n  description: \"Human readable explanation of what this rule checks\"\n\n  severity:\n    level: \"HIGH\"                  # LOW | MEDIUM | HIGH | CRITICAL\n    score: 8.7                     # 0.0 - 10.0, like CVSS\n\n  category: \"Workload Security\"   # See SecurityCategory constants for all available categories\n  subcategory: \"Privilege Escalation\"\n  cwe: \"CWE-269\"                   # Optional CWE or MITRE ref\n\n  regulatoryStandards:\n    - name: \"CIS Kubernetes 5.2.5\"\n      reference: \"https://cisecurity.org/...\"\n    - name: \"NIST SP 800-53 AC-6\"\n      reference: \"https://csrc.nist.gov/...\"\n\n  match:\n    resources:\n      kubernetes:\n        apiGroups:\n          - \"\"\n          - apps\n        versions:\n          - v1\n        kinds:\n          - Pod\n          - Deployment\n          - StatefulSet\n          - Job\n        namespaces:\n          include: [\"*\"]\n          exclude: [\"kube-system\", \"kube-public\"]\n        labels:\n          include:\n            environment: [\"production\", \"staging\"]\n          exclude:\n            security.spotter.dev/ignore: [\"true\"]\n\n  cel: |\n    object.kind in [\"Pod\", \"Deployment\", \"StatefulSet\", \"Job\"] \u0026\u0026\n    (\n      (object.kind == \"Pod\" \u0026\u0026\n       has(object.spec.containers) \u0026\u0026\n       object.spec.containers.exists(container,\n         has(container.securityContext) \u0026\u0026\n         container.securityContext.allowPrivilegeEscalation == true\n       )) ||\n      (has(object.spec.template.spec.containers) \u0026\u0026\n       object.spec.template.spec.containers.exists(container,\n         has(container.securityContext) \u0026\u0026\n         container.securityContext.allowPrivilegeEscalation == true\n       ))\n    )\n\n  remediation:\n    manual: |\n      Update securityContext to disable allowPrivilegeEscalation...\n\n  references:\n    - title: \"Kubernetes Security Context\"\n      url: \"https://kubernetes.io/docs/tasks/configure-pod-container/security-context/\"\n\n  metadata:\n    author: \"Spotter Security Team\"\n    created: \"2024-01-01\"\n```\n\n### CI/CD Integration\n\n#### GitHub Actions\n\n```yaml\nname: Security Scan\non: [push, pull_request]\n\njobs:\n  security-scan:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    \n    - name: Run Spotter Security Scan\n      run: |\n        docker run --rm \\\n          -v ${{ github.workspace }}:/workspace \\\n          ghcr.io/madhuakula/spotter:latest \\\n          scan manifests --path /workspace/k8s --output sarif \u003e results.sarif\n    \n    - name: Upload SARIF results\n      uses: github/codeql-action/upload-sarif@v2\n      with:\n        sarif_file: results.sarif\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/madhuakula/spotter.git\ncd spotter\n\n# Install dependencies\ngo mod download\n\n# Run tests\nmake test\n\n# Build binary\nmake build\n\n# Run linting\nmake lint\n```\n\n## 📝 License\n\nSpotter is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- [Common Expression Language (CEL)](https://github.com/google/cel-go) for flexible rule expressions\n- [Kubernetes](https://kubernetes.io/) community for the amazing platform\n- All contributors and users who make Spotter better\n\n## 📞 Support\n\n- 📖 [Documentation](docs/)\n- 🐛 [Issue Tracker](https://github.com/madhuakula/spotter/issues)\n- 💬 [Discussions](https://github.com/madhuakula/spotter/discussions)\n\n---\n\n**Made with ❤️ by the Spotter community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadhuakula%2Fspotter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadhuakula%2Fspotter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadhuakula%2Fspotter/lists"}