diff --git a/README.md b/README.md index 539f09d..ec0d4fe 100644 --- a/README.md +++ b/README.md @@ -15,45 +15,44 @@ This tool is ideal for managing NGINX in **modern, dynamic infrastructures** suc ### ➡️ Why Use the NGINX Declarative API? -- ✅ **Declarative Simplicity:** Express configurations as a single, high-level JSON object. -- ✅ **Automation-First Design:** Integrate configurations into CI/CD pipelines with minimal effort. -- ✅ **Error Reduction:** Built-in validation for accurate and optimized configurations. -- ✅ **Dynamic Updates:** Handle frequent configuration changes in highly dynamic environments. -- ✅ **Seamless Scalability:** Simplifies managing NGINX setups in high-scale distributed architectures. -- ✅ **Web UI:** A built-in web interface provides a visual way to manage and interact with the API, no command line required. +* ✅ **Declarative Simplicity**: Express configurations as a single, high-level JSON object. +* ✅ **Automation-First Design**: Integrate configurations into CI/CD pipelines with minimal effort. +* ✅ **Error Reduction**: Built-in validation for accurate and optimized configurations. +* ✅ **Dynamic Updates**: Handle frequent configuration changes in highly dynamic environments. +* ✅ **Seamless Scalability**: Simplifies managing NGINX setups in high-scale distributed architectures. -GitOps integration is supported: the source of truth is checked for updates (F5 WAF for NGINX policies, TLS certificates, keys and chains/bundles, Swagger/OpenAPI definitions, snippets) and NGINX configurations are automatically kept in sync. +GitOps integration is supported: source of truth is checked for updates (F5 WAF for NGINX policies, TLS certificates, keys and chains/bundles, Swagger/OpenAPI definitions, snippets) and NGINX configurations are automatically kept in sync. ### 📝 Use Cases -- Integration with F5 NGINX Instance Manager (instance group) and F5 NGINX One Console (config sync group) -- F5 WAF for NGINX DevSecOps integration -- API Gateway deployments with automated Swagger / OpenAPI schema import -- API Developer portals zero-touch deployment (redocly and backstage supported) -- API Visibility (moesif supported) -- GitOps integration with source of truth support for - - F5 WAF for NGINX policies - - TLS certificates, keys and chains/bundles - - mTLS certificates - - `http` snippets, upstreams, servers, locations - - `stream` snippets, upstreams, servers - - Swagger / OpenAPI schemas - - NGINX Javascript +* Integration with F5 NGINX Instance Manager (instance group) and F5 NGINX One Console (config sync group) +* F5 WAF for NGINX DevSecOps integration +* API Gateway deployments with automated Swagger / OpenAPI schema import +* API Developer portals zero-touch deployment (redocly and backstage supported) +* API Visibility (moesif supported) +* GitOps integration with source of truth support for + + F5 WAF for NGINX policies + + TLS certificates, keys and chains/bundles + + mTLS certificates + + `http` snippets, upstreams, servers, locations + + `stream` snippets, upstreams, servers + + Swagger / OpenAPI schemas + + NGINX Javascript A **blog article** to automate NGINX API Gateway management from OpenAPI schemas is available [here](https://www.f5.com/company/blog/nginx/from-openapi-to-nginx-as-an-api-gateway-using-a-declarative-api) ## 🚀 Supported releases -- [F5 NGINX Instance Manager 2.20+](https://docs.nginx.com/nginx-instance-manager/) -- [F5 NGINX One Console](https://docs.nginx.com/nginx-one/) -- [F5 NGINX Plus R33+](https://docs.nginx.com/nginx/) -- [F5 WAF for NGINX](https://docs.nginx.com/waf/) +* [F5 NGINX Instance Manager 2.20+](https://docs.nginx.com/nginx-instance-manager/) +* [F5 NGINX One Console](https://docs.nginx.com/nginx-one/) +* [F5 NGINX Plus R33+](https://docs.nginx.com/nginx/) +* [F5 WAF for NGINX](https://docs.nginx.com/waf/) -**Note**: F5 NGINX Plus R33 and above [require a valid license](https://docs.nginx.com/solutions/about-subscription-licenses/) and the `.output.license` section in the declarative JSON is required. See the [usage notes](/USAGE-v5.4.md) for further details. [Postman collection](/contrib/postman) examples are provided for NGINX Plus R33+. +**Note**: F5 NGINX Plus R33 and above [require a valid license](https://docs.nginx.com/solutions/about-subscription-licenses/) and the `.output.license` section in the declarative JSON is required. See the [usage notes](USAGE-v5.4.md) for further details. [Postman collection](contrib/postman) examples are provided for NGINX Plus R33+. ## 🛠️ Architecture -```mermaid +``` --- title: NGINX Declarative API architecture --- @@ -98,7 +97,7 @@ stateDiagram-v2 ## 🤖 GitOps Autosync Mode -```mermaid +``` sequenceDiagram title GitOps autosync operations @@ -148,7 +147,7 @@ end ## 🕒 Concurrent access and queuing mode -```mermaid +``` sequenceDiagram title Concurrent access and queueing mode @@ -199,49 +198,49 @@ end ## 🧩 Input formats -- [X] Declarative JSON +* Declarative JSON ## 🧾 Output formats -- [X] Output to [F5 NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) 2.20+ imperative REST API (instance group) -- [X] Output to [F5 NGINX One Console](https://docs.nginx.com/nginx-one-console/) REST API (config sync group) +* Output to [F5 NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) 2.20+ imperative REST API (instance group) +* Output to [F5 NGINX One Console](https://docs.nginx.com/nginx-one-console/) REST API (config sync group) ## 🌟 Supported features -See the [features list](/FEATURES.md) +See the [features list](FEATURES.md) ## 🔧 How to use Usage details and JSON schema are available here: -- [API v5.5](/USAGE-v5.5.md) - latest -- [API v5.4](/USAGE-v5.4.md) - stable +* [API v5.5](USAGE-v5.5.md) - latest +* [API v5.4](USAGE-v5.4.md) - stable -A sample Postman collection and usage instructions can be found [here](/contrib/postman) +A sample Postman collection and usage instructions can be found [here](contrib/postman) ## 🏃 How to run -NGINX Declarative API can be deployed on: - -- Linux virtual machine using [docker-compose](/contrib/docker-compose) -- Kubernetes using [manifests](/contrib/kubernetes) -- Kubernetes through [Helm chart](/contrib/helm/nginx-declarative-api) +NGINX Declarative API can be deployed on a Linux virtual machine using [docker-compose](contrib/docker-compose) or on [Kubernetes](contrib/kubernetes) ## 🐳 Building Docker images -Docker images can be built and run using the Docker compose [script](/contrib/docker-compose) provided +Docker images can be built and run using the Docker compose [script](contrib/docker-compose) provided ## 📖 REST API documentation When NGINX Declarative API is running, REST API documentation can be accessed at: -- Documentation and testing: `/docs` -- Redoc documentation: `/redoc` -- OpenAPI specification: `/openapi.json` +* Documentation and testing: `/docs` +* Redoc documentation: `/redoc` +* OpenAPI specification: `/openapi.json` + +## 🔒 Security + +To report a security vulnerability, please do **not** open a public GitHub issue. Instead, follow the responsible disclosure process outlined in [SECURITY.md](SECURITY.md). ## ⚖️ License -This repository is licensed under the Apache License, Version 2.0. You are free to use, modify, and distribute this codebase within the terms and conditions outlined in the license. For more details, please refer to the [LICENSE](/LICENSE.md) file. +This repository is licensed under the Apache License, Version 2.0. You are free to use, modify, and distribute this codebase within the terms and conditions outlined in the license. For more details, please refer to the [LICENSE](LICENSE.md) file. ## 🆘 Support @@ -249,8 +248,8 @@ For support, please open a GitHub issue. Note that the code in this repository i ## 💡 Contributing -See [Contributing](/CONTRIBUTING.md) +See [Contributing](CONTRIBUTING.md) ## 🤝 Code of Conduct -See the [Code of Conduct](/code_of_conduct.md) +See the [Code of Conduct](code_of_conduct.md) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b4a8f80 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,116 @@ +# Security Policy + +## Overview + +The NGINX Declarative API project takes security seriously. This document outlines how to report vulnerabilities, which releases receive security fixes, and what you can expect after submitting a report. + +> **Note:** This is a community-supported project maintained under the [f5devcentral](https://github.com/f5devcentral) organization. It is not an official F5 product and does not carry a commercial support SLA. However, security disclosures are treated with high priority. + +--- + +## Supported Versions + +Security fixes are applied to the **latest stable release** only. We strongly encourage all users to stay on the most recent version. + +| Version | Supported | +|---------|--------------------| +| 5.5.x | ✅ Yes (latest) | +| 5.4.x | ⚠️ Critical fixes only | +| < 5.4 | ❌ No | + +--- + +## Reporting a Vulnerability + +**Please do not open a public GitHub issue to report a security vulnerability.** + +If you believe you have found a security vulnerability in this project, please disclose it responsibly using one of the following channels: + +### Option 1 — GitHub Private Security Advisory (Preferred) + +Use GitHub's built-in private disclosure mechanism: + +1. Navigate to the [Security tab](https://github.com/f5devcentral/NGINX-Declarative-API/security) of this repository. +2. Click **"Report a vulnerability"**. +3. Fill in the details of the issue, including steps to reproduce, potential impact, and any suggested mitigations. + +This keeps the disclosure private until a fix is ready. + +### Option 2 — F5 Security Incident Response Team (SIRT) + +For vulnerabilities that may have broader impact on F5 or NGINX products used in conjunction with this project (e.g., NGINX Instance Manager, NGINX One Console, NGINX Plus, or F5 WAF for NGINX), please contact the F5 Security Incident Response Team directly: + +- **Web**: [https://www.f5.com/support/report-a-vulnerability](https://www.f5.com/support/report-a-vulnerability) +- **Email**: F5SIRT@f5.com (encrypted submissions accepted via the [F5 SIRT public PGP key](https://www.f5.com/support/report-a-vulnerability)) + +--- + +## What to Include in Your Report + +To help us triage and respond quickly, please include as much of the following as possible: + +- A clear description of the vulnerability and its potential impact +- The affected component(s) (e.g., API endpoint, GitOps sync logic, Docker image, configuration parser) +- Steps to reproduce the issue or a proof-of-concept (PoC) +- The version(s) of NGINX Declarative API affected +- Your suggested severity rating (e.g., CVSS score if applicable) +- Any proposed mitigations or patches + +--- + +## Scope + +This security policy covers the **NGINX Declarative API application code** in this repository, including: + +- The Python-based REST API service +- GitOps autosync and queue management logic +- Docker and Kubernetes deployment manifests (`contrib/`) +- Go templates used for NGINX configuration rendering (`templates/`) +- Configuration handling for NGINX Instance Manager and NGINX One Console integrations + +### Out of Scope + +The following are **not** in scope for this project's security policy and should be reported to their respective vendors: + +- [F5 NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) vulnerabilities → report to [F5 SIRT](https://www.f5.com/support/report-a-vulnerability) +- [F5 NGINX One Console](https://docs.nginx.com/nginx-one/) vulnerabilities → report to [F5 SIRT](https://www.f5.com/support/report-a-vulnerability) +- [F5 NGINX Plus](https://docs.nginx.com/nginx/) vulnerabilities → report to [F5 SIRT](https://www.f5.com/support/report-a-vulnerability) +- [F5 WAF for NGINX](https://docs.nginx.com/waf/) vulnerabilities → report to [F5 SIRT](https://www.f5.com/support/report-a-vulnerability) +- Third-party dependencies (Redis, Moesif, Redocly, Backstage) → report to respective maintainers + +--- + +## Security Best Practices for Deployers + +When deploying NGINX Declarative API, we recommend the following: + +- **Network exposure**: Do not expose the NGINX Declarative API directly to the public internet. Place it behind a network boundary or API gateway with appropriate access controls. +- **Authentication**: Ensure that access to the REST API is protected with strong authentication. The API has privileged access to your NGINX infrastructure. +- **TLS**: Always use TLS for communication between clients and the NGINX Declarative API service, as well as between the service and NGINX Instance Manager / NGINX One Console. +- **Secrets management**: Do not store credentials, API keys, or TLS private keys in plaintext configuration files or environment variables. Use a secrets manager appropriate to your environment (e.g., Kubernetes Secrets with encryption at rest, HashiCorp Vault). +- **Container images**: Always use official or internally verified Docker images. Regularly scan images for known CVEs using tools such as Trivy, Grype, or Docker Scout. +- **Source of Truth security**: When using GitOps autosync, ensure that your source-of-truth repository (containing WAF policies, TLS certificates, and NGINX snippets) has appropriate access controls and audit logging. +- **Least privilege**: Run the API service container with a non-root user and minimal Linux capabilities. +- **Keep dependencies updated**: Regularly update Python dependencies (`requirements.txt`) and base Docker images to pull in upstream security patches. + +--- + +## Disclosure Policy + +We follow a **coordinated disclosure** model. We ask that reporters: + +1. Give us reasonable time to investigate and patch before public disclosure. +2. Avoid exploiting the vulnerability beyond what is necessary to demonstrate the issue. +3. Do not access, modify, or delete data belonging to others. + +In return, we commit to: + +1. Acknowledging your report promptly. +2. Keeping you informed throughout the remediation process. +3. Crediting you in the release notes (unless you prefer to remain anonymous). + +--- + +## License + +This project is licensed under the [Apache License, Version 2.0](LICENSE.md). Security contributions and disclosures are welcomed under the same spirit of open collaboration. diff --git a/contrib/helm/nginx-declarative-api/.README.md.swp b/contrib/helm/nginx-declarative-api/.README.md.swp deleted file mode 100644 index 834c7ec..0000000 Binary files a/contrib/helm/nginx-declarative-api/.README.md.swp and /dev/null differ