{"id":37021131,"url":"https://github.com/nis2shield/nis2-spring-shield","last_synced_at":"2026-01-14T02:29:07.488Z","repository":{"id":331321842,"uuid":"1125402697","full_name":"nis2shield/nis2-spring-shield","owner":"nis2shield","description":"🛡️ The \"Security-First\" Spring Boot Starter for NIS2 Compliance. Provides forensic logging, active defense (Rate Limiting, Tor Blocking), and data integrity for Java enterprise applications.","archived":false,"fork":false,"pushed_at":"2026-01-04T10:30:57.000Z","size":74,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T06:36:12.605Z","etag":null,"topics":["active-defense","audit-logging","bucket4j","compliance","gdpr","java","nis2","security","spring-boot"],"latest_commit_sha":null,"homepage":"https://nis2shield.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nis2shield.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":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T17:01:08.000Z","updated_at":"2026-01-04T10:31:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nis2shield/nis2-spring-shield","commit_stats":null,"previous_names":["nis2shield/nis2-spring-shield"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/nis2shield/nis2-spring-shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nis2shield%2Fnis2-spring-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nis2shield%2Fnis2-spring-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nis2shield%2Fnis2-spring-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nis2shield%2Fnis2-spring-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nis2shield","download_url":"https://codeload.github.com/nis2shield/nis2-spring-shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nis2shield%2Fnis2-spring-shield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"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":["active-defense","audit-logging","bucket4j","compliance","gdpr","java","nis2","security","spring-boot"],"created_at":"2026-01-14T02:29:07.009Z","updated_at":"2026-01-14T02:29:07.474Z","avatar_url":"https://github.com/nis2shield.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NIS2 Spring Shield\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.nis2shield/nis2-spring-shield.svg)](https://central.sonatype.com/artifact/com.nis2shield/nis2-spring-shield)\n[![Java CI with Maven](https://github.com/nis2shield/nis2-spring-shield/actions/workflows/maven.yml/badge.svg)](https://github.com/nis2shield/nis2-spring-shield/actions/workflows/maven.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Java 21](https://img.shields.io/badge/Java-21-orange)](https://jdk.java.net/21/)\n\n**NIS2 Spring Shield** is a Spring Boot Starter designed to help Java enterprise applications comply with the **NIS2 Directive** requirements. It provides ready-to-use forensic logging, active defense mechanisms, and data integrity protection.\n\n### The \"Security-First\" Spring Boot Starter for NIS2 Compliance.\n\nCompanies subject to NIS2 Directive need **demonstrable compliance**. This starter provides:\n\n1.  **Forensic Logging**: JSON structured logs with HMAC-SHA256 integrity (Art. 21.2.h)\n2.  **PII Encryption**: AES-256 encryption for sensitive fields (GDPR-compliant)\n3.  **Active Defense**: Rate Limiting (Bucket4j) \u0026 Tor Blocking (Art. 21.2.e)\n4.  **Health Monitoring**: Spring Actuator integration for operations\n5.  **Multi-SIEM**: Presets for Splunk, Datadog, QRadar.\n\n\u003e **Part of the NIS2 Shield Ecosystem**: Use with [`@nis2shield/react-guard`](https://github.com/nis2shield/react-guard), [`@nis2shield/angular-guard`](https://github.com/nis2shield/angular-guard), or [`@nis2shield/vue-guard`](https://github.com/nis2shield/vue-guard) for client-side protection and [`nis2shield/infrastructure`](https://github.com/nis2shield/infrastructure) for a full-stack implementation.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        Frontend                              │\n│  @nis2shield/{react,angular,vue}-guard                      │\n│  ├── SessionWatchdog (idle detection)                       │\n│  ├── AuditBoundary (crash reports)                         │\n│  └── → POST /api/nis2/telemetry/                           │\n└─────────────────────────────────────────────────────────────┘\n                            │\n                            ▼\n┌─────────────────────────────────────────────────────────────┐\n│                  Backend (NIS2 Adapter)                      │\n│  Supported: Django, Express, Spring Boot, .NET            │\n│  ├── ForensicLogger (HMAC signed logs)                     │\n│  ├── RateLimiter, SessionGuard, TorBlocker                 │\n│  └── → SIEM (Elasticsearch, Splunk, QRadar, etc.)          │\n└─────────────────────────────────────────────────────────────┘\n                            │\n                            ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Infrastructure                            │\n│  nis2shield/infrastructure                                  │\n│  ├── Centralized Logging (ELK/Splunk)                       │\n│  └── Audited Deployment (Terraform/Helm)                    │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Features\n\n*   **Forensic Logging (Audit):**\n    *   Captures all HTTP requests and responses.\n    *   **NIS2-JSON-SCHEMA v1.0**: Standardized, machine-readable format compatible with SIEMs.\n    *   **Integrity Signing**: Logs are signed with HMAC-SHA256 to prevent tampering.\n    *   **PII Encryption**: Automatically encrypts sensitive fields (User ID, Email, IP) using AES-256.\n    *   **IP Anonymization**: Masks the last octet of IP addresses for GDPR compliance.\n\n*   **Active Defense:**\n    *   **Rate Limiting**: Sliding window algorithm (via Bucket4j) to prevent DoS/Brute Force.\n    *   **Tor Blocker**: Blocks requests from known Tor exit nodes (configurable).\n    *   **Malicious IP Blocking**: Structure ready for threat intelligence integration.\n\n*   **Health Monitoring:**\n    *   Exposes status via Spring Boot Actuator (`/actuator/health`).\n\n## Installation\n\nAdd the dependency to your `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.nis2shield\u003c/groupId\u003e\n    \u003cartifactId\u003enis2-spring-shield\u003c/artifactId\u003e\n    \u003cversion\u003e0.1.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nThat's it! No additional repository configuration required - the library is available on **Maven Central**.\n\n\n## Configuration\n\nConfigure the shield in your `application.yml`:\n\n```yaml\nnis2:\n  enabled: true\n  # Keys for security (Use environment variables in production!)\n  encryption-key: \"VGhpcyBJcyBBIFRlc3QgS2V5IEZvciBBRVMgMjU2IQ==\" # Base64 AES-256 Key\n  integrity-key: \"change-this-to-a-very-secret-hmac-key\"\n  \n  logging:\n    enabled: true\n    encrypt-pii: true     # Encrypt sensitive fields\n    anonymize-ip: true    # Mask IP (192.168.1.xxx)\n\n  active-defense:\n    rate-limit-enabled: true\n    rate-limit-capacity: 100        # Requests allowed\n    rate-limit-window-seconds: 60   # Per window (e.g., 1 minute)\n    block-tor-exit-nodes: true      # Block known Tor nodes\n```\n\n## Usage\n\nOnce added, the starter automatically configures:\n1.  **`Nis2AuditingFilter`**: Intercepts requests for logging.\n2.  **`ActiveDefenseFilter`**: Enforces security policies before the request reaches your controller.\n3.  **`Nis2HealthIndicator`**: Adds NIS2 status to Actuator.\n\n### Example Log Output\n\n```json\n{\n  \"log\": {\n    \"module\": \"NIS2-SHIELD-SPRING\",\n    \"timestamp\": \"2025-12-30T16:00:00Z\",\n    \"request\": {\n      \"method\": \"POST\",\n      \"path\": \"/api/v1/login\",\n      \"ip\": \"203.0.113.xxx\",   // Anonymized\n      \"user_agent\": \"Mozilla/5.0...\"\n    },\n    \"response\": {\n      \"status\": 200,\n      \"duration_ms\": 150\n    },\n    \"user_id\": \"[ENCRYPTED]...base64...\" // Encrypted PII\n  },\n  \"integrity_hash\": \"a1b2c3d4...\" // HMAC-SHA256 Signature\n}\n```\n\n\n## Actuator Endpoint\n\nCheck the status of the shield:\n\n```bash\ncurl http://localhost:8080/actuator/health\n```\n\nResponse:\n```json\n{\n  \"status\": \"UP\",\n  \"components\": {\n    \"nis2_shield\": {\n      \"status\": \"UP\",\n      \"details\": {\n        \"active\": \"Active\",\n        \"blocked_tor_ips\": 0\n      }\n    }\n  }\n}\n```\n\n## Compliance CLI (`check_nis2`)\n\nYou can audit your application configuration against NIS2 requirements directly from the command line:\n\n```bash\njava -jar your-app.jar --check-nis2\n```\n\n**Output Example:**\n\n```text\n[NIS2 SHIELD AUDIT REPORT]\nApplication: Spring Boot Application\nGenerated: 2025-12-31T12:00:00Z\n------------------------------------------------\n[PASS] NIS2 Shield Enabled (General)\n       NIS2 Shield middleware is active\n[PASS] Integrity Key (Art. 21.2.h)\n       HMAC signing key for log integrity (min 32 chars)\n[FAIL] Encryption Key (Art. 21.2.f)\n       AES encryption key for PII (16/24/32 chars for AES-128/192/256)\n...\n------------------------------------------------\nCOMPLIANCE SCORE: 85/100\n```\n\nAlso generates a detailed HTML report for auditors.\n\n## 📖 Recipes\n\n### Banking API with Strict Configuration\n\n```yaml\n# application.yml\nnis2:\n  enabled: true\n  encryption-key: ${NIS2_AES_KEY}  # Base64 AES-256\n  integrity-key: ${NIS2_HMAC_KEY}\n  \n  logging:\n    enabled: true\n    encrypt-pii: true\n    anonymize-ip: true\n  \n  active-defense:\n    rate-limit-enabled: true\n    rate-limit-capacity: 30      # Strict: 30 req/min for banking\n    rate-limit-window-seconds: 60\n    block-tor-exit-nodes: true\n```\n\n### E-commerce with Relaxed Rate Limits\n\n```yaml\nnis2:\n  enabled: true\n  logging:\n    enabled: true\n    anonymize-ip: true\n  active-defense:\n    rate-limit-enabled: true\n    rate-limit-capacity: 200\n    rate-limit-window-seconds: 60\n    block-tor-exit-nodes: false  # Allow Tor for privacy\n```\n\n### Microservice with Custom Compliance Runner\n\n```bash\n# Run compliance audit at startup\njava -jar your-app.jar --check-nis2\n```\n\n## Release Process\n\nAutomated releases are handled via GitHub Actions.\n\n1. **Create Tag**: Push a new tag (e.g., `v0.2.0`).\n2. **GitHub Release**: Create a release in the GitHub UI.\n3. **CI/CD**: The `publish.yml` workflow triggers automatically:\n    - Builds the project.\n    - Generates Javadoc and Source JARs.\n    - Signs artifacts with GPG (Secrets: `GPG_PRIVATE_KEY`, `GPG_PASSPHRASE`).\n    - Deploys to **Maven Central** (Secrets: `OSSRH_USERNAME`, `OSSRH_TOKEN`).\n    \n---\n\n## 🛡️ Security \u0026 Updates\n\n**Subscribe to our [Security Mailing List](https://buttondown.email/nis2shield)** to receive immediate alerts about:\n- Critical vulnerabilities (CVEs)\n- NIS2/DORA regulatory logic updates\n- Major breaking changes\n\nFor reporting vulnerabilities, see [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT License - See LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnis2shield%2Fnis2-spring-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnis2shield%2Fnis2-spring-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnis2shield%2Fnis2-spring-shield/lists"}