Merge pull request #175 from dulajdilshan/deployment-best-practices

Improve sections in `Deployment Best Practices` and address review comments in #169

Author: anupama-pathirage

en/docs/deploy/deployment-best-practices/network-level-security.md

@@ -1,6 +1,6 @@
 # Network Level Security
 
-### Establish a Failover Setup
+## Establish a failover setup
 
 Implement high availability (HA) and failover configurations to ensure continuous system operation and minimize downtime.
 
@@ -10,22 +10,20 @@ Implement high availability (HA) and failover configurations to ensure continuou
 
 Continuously monitor the health and performance of all nodes within the cluster. Track key metrics such as resource utilization, response time anomalies, and the volume of incoming network connections. Effective monitoring helps you determine when to add failover instances or adjust network routing to prevent service disruptions.
 
-### Maintain Network-Level Logging
+## Maintain network-level logging
 
 Enable and retain logs for all network components, including proxy servers, load balancers, and other critical infrastructure devices. Regularly review these logs to detect abnormal behavior, unauthorized access attempts, or configuration changes.
 
-### Audit Open Ports and Services
+## Audit open ports and services
 
 Conduct periodic network scans to identify open ports and active services. Ensure that only the ports necessary for your WSO2 products are accessible on both internal and external networks. Disable or monitor any additional open ports that are not explicitly required.
- 
-> Refer to **Default Product Ports** for the complete list of ports used by WSO2 products.
 
-### Enforce Device-Level Security
+## Enforce device-level security
 
 * Regularly inspect and validate the configuration and integrity of all network devices, including routers, switches, and firewalls. Verify routing tables, access control lists, and firewall rules for correctness and consistency.
 
 * Replace all default device credentials with strong, unique passwords before deploying devices in production.
 
-### Apply Firmware Updates
+## Apply firmware updates
 
 Keep network device firmware up to date to mitigate vulnerabilities and maintain optimal performance. Apply updates as recommended by the device vendor after validating them in a non-production environment.

en/docs/deploy/deployment-best-practices/os-level-security.md

@@ -1,38 +1,37 @@
 # OS level Security
 
-### Run WSO2 Processes with a Dedicated User
+## Run WSO2 processes with a dedicated user
 
 Use a dedicated OS-level user account to run WSO2 products. Assign only the minimum permissions necessary for running the product. Avoid using the root or administrator account, as these have full privileges by default and increase the risk of security breaches.
 
-### Minimize Installed Software
+## Minimize installed software
 Install only the software and packages required for your WSO2 product deployment. Unnecessary software can introduce vulnerabilities. Regularly review and monitor installed packages.
 
-Refer to the Installation Prerequisites for details on the minimum required software.
+Refer to the [system requirements](/references/system-requirements) for details on the minimum required software.
 
-### Enable the Firewall
+## Enable the firewall
 Enable and configure a host-level firewall (e.g., iptables) to protect inbound and outbound connections. Only open the ports that are required for product functionality.
 
-### Restrict Access to Clustering Ports
+## Restrict access to clustering ports
 
 Apply firewall rules to restrict access to TCP ports used for clustering (e.g., ports 4000, 4001, etc.) so that they are accessible only to other nodes within the WSO2 product cluster. Prevent access from unrecognized or external hosts.
 
-### Use Secure Shell (SSH)
+## Use secure shell (SSH)
 
 * Always use Secure Shell (SSH) for remote server access and command execution. Follow these best practices when configuring SSH:
 * Change the default SSH port to a non-standard, higher-numbered port.
 * Disable direct root or administrator logins.
 * Enable authentication via SSH keys instead of passwords.
 * Display a legal or security banner before authentication to warn unauthorized users.
 
-### Keep the System Up-to-Date
+## Keep the system up-to-date
 
-Regularly apply security patches and updates for all installed packages, including the Java runtime. Test updates in a staging environment before deploying them to production.
+Regularly apply security patches and updates for all installed packages. Test updates in a staging environment before deploying them to production.
 
-### Monitor User Activities
+## Monitor user activities
 
 Enable OS-level logging and review logs periodically to monitor user actions. Consider using a centralized logging or Security Information and Event Management (SIEM) solution for continuous monitoring.
 
-### Perform Regular Backups
+## Perform regular backups
 
 Back up all the critical files and data regularly, and store them securely.
-

en/docs/deploy/deployment-best-practices/overview.md

@@ -1,8 +1,25 @@
 # Best Practices for Production Deployment
 
-Following are the guidelines for hardening the security for production deployment.
+This section provides comprehensive security and operational best practices for deploying WSO2 Integrator: BI in production environments. Following these guidelines helps ensure your deployment is secure, resilient, and maintainable.
 
-* [Runtime Security](/deploy/deployment-best-practices/runtime-security)
-* [OS level security](/deploy/deployment-best-practices/os-level-security)
-* [Network level security](/deploy/deployment-best-practices/network-level-security)
+## Runtime security
 
+Runtime security focuses on securing your BI application and the services it generates during execution, including application-level configurations, patches, secrets management, TLS/SSL protocols, and logging.
+
+[Learn more about runtime security →](/deploy/deployment-best-practices/runtime-security)
+
+## OS level security
+
+Operating system security addresses the hardening of the underlying operating system where BI is deployed, covering user accounts, firewalls, SSH configuration, system updates, and monitoring.
+
+[Learn more about OS level security →](/deploy/deployment-best-practices/os-level-security)
+
+## Network level security
+
+Network security covers the infrastructure and network-level protections for your BI deployment, including high availability, failover configurations, network logging, port auditing, and device security.
+
+[Learn more about network level security →](/deploy/deployment-best-practices/network-level-security)
+
+## Getting started
+
+Review each category above to understand the security considerations for your deployment. Implement these practices based on your specific environment, compliance requirements, and security policies. These guidelines are applicable to both cloud-native (containerized) and traditional VM-based deployments.

en/docs/deploy/deployment-best-practices/runtime-security.md

@@ -1,99 +1,97 @@
 # Runtime Security
 
-### 1. Apply Security Patches Regularly
+## Apply security patches regularly
 
-* **VSCode Plugin**: Always use the latest release for `WSO2 Integrator: BI` and `Ballerina` VSCode plugin.  
-* **Ballerina:** Use the latest patch release of the relevant Ballerina distribution version. 
+Keeping all software components up to date is a critical part of maintaining runtime security. Security patches often address newly discovered vulnerabilities that attackers can exploit if left unpatched.
 
-> Community users are encouraged to use the latest product versions to receive all resolved security issues.
+| Category | Guidelines |
+|-----------|-------------|
+| **WSO2 Integrator: BI** | Always use the latest stable release of [Visual Studio Code](https://code.visualstudio.com/).<br><br>Keep [WSO2 Integrator: BI](https://marketplace.visualstudio.com/items?itemName=WSO2.ballerina-integrator) and [Ballerina](https://marketplace.visualstudio.com/items?itemName=WSO2.ballerina) extensions updated to ensure compatibility with the latest security and functionality enhancements. |
+| **Ballerina Distribution** | Use the latest patch release of the relevant [Ballerina distribution](https://ballerina.io/downloads/) to ensure runtime and library-level vulnerabilities are fixed.<br><br>Follow Ballerina and WSO2 product release notifications to stay informed about new security advisories. |
+| **Operating System and Dependencies** | Regularly apply security updates to the host operating system, *container base images*, and *runtime dependencies* (e.g., database clients, third-party libraries).<br><br>If deploying via Docker, track and update base image versions (e.g., `ubuntu`, `alpine`, or `ballerina`) to the latest stable, patched releases.|
+| **Automation and CI/CD Integration** | Integrate automated patch verification and dependency vulnerability scanning into CI/CD pipelines.<br><br>Use dependency management tools (e.g., *Dependabot*, *Renovate*) to receive automated pull requests for new patches.<br><br>Maintain a rollback plan and a staging environment to safely test patches before deploying to production. |
+| **Community and Security Feeds** | Follow [WSO2 Security Docs](https://security.docs.wso2.com/en/latest/) for timely notifications of vulnerabilities and fixes. |
 
-> Subscribe to the official security mailing lists and follow WSO2/Ballerina release announcements.  
+## Use keystores and truststores correctly
 
-* **OS and Dependencies:** Keep the operating system, container base images, Java (JDK/JRE), and database clients updated with security patches.
-* **Automation:** Integrate patch checks into CI/CD pipelines and maintain a rollback plan for emergency patches.
-
-### 2. Use Keystores and Truststores Correctly
-
-* Configure BI and the generated Ballerina services to use **separate keystores** for service certificates and **truststores** for trusted CAs.  
+* Configure BI and the generated Ballerina services to use separate keystores for service certificates and truststores for trusted CAs.  
 * Use strong passwords and store them securely (e.g., as Kubernetes secrets or environment variables).  
-* Always replace default keystore files shipped with samples.
+* Always replace the default keystore files shipped with samples.
 
-### 3. Manage Secrets Securely
+## Manage secrets securely
 
 * Never hardcode passwords, tokens, or keys in source code, configuration files, or repositories.
-
 * Use platform-specific secret management systems such as:  
-  * **Kubernetes Secrets**  
-  * **HashiCorp Vault**  
-  * **AWS Secrets Manager** or similar cloud stores.  
-* Pass secrets into BI runtime via configuration values.
+    * Kubernetes Secrets
+    * HashiCorp Vault
+    * AWS Secrets Manager or similar cloud stores.
+* Pass secrets into the BI runtime via configuration values.
 
-### 4. Change Default Ports and Credentials
+## Change default ports and credentials
 
-* Change all **default listener ports** used by BI components and generated Ballerina services.  
+* Change all default listener ports used by BI components and generated Ballerina services.  
   Example: modify configurations or `Config.toml` to run on custom, non-standard ports.  
 * Disable unused ports and protocols to minimize the attack surface.  
 * Replace any default credentials used by admin or management consoles.
 
-### 5. Secure Communication with External Services
+## Secure communication with external services
 
 When BI connects to external systems such as user stores, databases, or other APIs:
 
-* Always enable **TLS/SSL** for data-in-transit protection.  
+* Always enable TLS/SSL for data-in-transit protection.  
 * Validate external service certificates using the truststore.  
 * Verify hostnames and certificate chains to avoid man-in-the-middle attacks.  
 * Restrict outbound network access to only approved endpoints.
 
----
-
-### 6. Use Least-Privilege Credentials for DBs and User Stores
+## Use least-privilege credentials for DBs and user stores
 
 * Never connect to databases, LDAP, or user stores using `root` or administrator credentials.  
 * Create dedicated application-level accounts with only the minimal privileges required:  
   * Read/write on specific schemas or tables.  
   * No administrative permissions (e.g., `DROP DATABASE`, `GRANT ALL`).  
 * Rotate credentials periodically and disable accounts no longer in use.
 
-### 7. Strengthen TLS Security
+## Strengthen TLS security
 
-* Enforce **TLS 1.2 or TLS 1.3** for all HTTPS and secure socket communications.  
+* Enforce TLS 1.2 or TLS 1.3 for all HTTPS and secure socket communications.  
 * Disable older or insecure protocol versions (e.g., TLS 1.0/1.1, SSLv3).  
-* Require strong cipher suites only (see below).
+* Require strong cipher suites only (Refer to [Use cipher suites](#use-cipher-suites)).
 
-### 8. Use Cipher Suites
+## Use cipher suites
 
-* Configure Ballerina to use secure cipher suites see [Ballerina Crypto](https://central.ballerina.io/ballerina/crypto/latest) for more details.
+* Configure Ballerina to use secure cipher suites. Refer to [Ballerina Crypto](https://central.ballerina.io/ballerina/crypto/latest) for more details.
 * Periodically review cipher configurations against current security standards (NIST, OWASP).
 
-### 9. Logging and Monitoring
+## Logging and monitoring
 
 * Comprehensive logs and telemetry, when correlated with access controls and alerting, enhance the ability to identify unauthorized usage or data exfiltration attempts in production environments.
 * Integrate with standardized observability tools (e.g., Prometheus, Jaeger, ELK Stack) so that you can unify your security-monitoring posture across BI deployment models.
 
 Follow the below guides to configure logging and observability.
+
 * [Configure Logging](https://ballerina.io/spec/log/#3-configure-logging)
-* [Observability in BI](https://bi.docs.wso2.com/observability-and-monitoring/overview/)
+* [Observability in BI](/observability-and-monitoring/overview)
 
-### 10. Prevent Log Forging
+## Prevent log forging
 
 * Sanitize all user-provided data before writing to logs.  
 * Configure the logging framework to escape newline and control characters.  
 * Use structured logging where possible to make parsing safer.  
 * Restrict log file write permissions to the BI runtime user only.
 
-### 11. Set Secure JVM Parameters
+## Set secure JVM parameters
 
 Since Ballerina runs on the JVM, tune the JVM for security and stability:
 
-* Use a **supported JDK version** with the latest security patches.  
+* Use a supported JDK version with the latest security patches.  
 * Limit heap size and enable garbage-collection logs for troubleshooting.  
 * Run BI under a non-root user with limited filesystem and network permissions.
 
-### 12. Additional Hardening Recommendations
+## Additional hardening recommendations
 
 * **Run as Non-Root:** Configure containers or services to run as a non-root OS user.  
 * **File Permissions:** Restrict access to configuration files, keystores, and logs (`chmod 600`).  
 * **Network Segmentation:** Place BI and databases on private networks/VPCs.  
 * **Audit and Compliance:** Periodically audit configurations and review access logs.  
 * **Backup and Recovery:** Encrypt and test backups regularly.  
-* **Validate the code with `scan tool`:** Use [Ballerina scan tool](https://bi.docs.wso2.com/developer-guides/tools/other-tools/scan-tool/) to identify potential issues such as code smells, bugs, and vulnerabilities.
+* **Validate the code with scan tool:** Use [Ballerina scan tool](https://bi.docs.wso2.com/developer-guides/tools/other-tools/scan-tool/) to identify potential issues such as code smells, bugs, and vulnerabilities.