Skip to content

Commit b62ab52

Browse files
ADubhlaoichADubhlaoich
authored
feat: Update NIM Security Monitoring front matter and reference links (#298)
This commit updates the Security Monitoring subsection of the NAP WAF documentation within NGINX Instance Manager to have contemporary frontmatter formatting, including a fixed url parameter for the index. The previous URL parameter was causing some odd behaviour, with duplicate deployments of folders.
1 parent e9b849a commit b62ab52

File tree

6 files changed

+153
-106
lines changed

6 files changed

+153
-106
lines changed

‎content/nim/nginx-app-protect/security-monitoring/_index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
22
title: Security Monitoring
3-
weight: 10000
4-
url: /nginx-instance-manager/monitoring/security-monitoring/
3+
weight: 500
4+
url: /nginx-instance-manager/nginx-app-protect/security-monitoring/
55
---

‎content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md

Lines changed: 129 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -11,66 +11,92 @@ docs: DOCS-1107
1111

1212
F5 NGINX Security Monitoring supports two main use cases:
1313

14-
- **Security Monitoring only**: Monitor data from NGINX App Protect WAF instances. You can view security dashboards to identify threats and adjust policies. WAF configurations are managed outside NGINX Instance Manager.
15-
- **Security Monitoring and Instance Manager**: Monitor security data and manage WAF configurations and policies in one place. Push pre-compiled updates to individual instances or groups.
14+
- **Security Monitoring only**: Use only the Security Monitoring module to monitor data from NGINX App Protect WAF instances. You will be able to review the security dashboards to assess potential threats and identify opportunities to fine-tune your policies. Your NGINX App Protect WAF configurations are managed outside of the NGINX Instance Manager context.
15+
- **Security Monitoring and Instance Manager**: Use the Security Monitoring module with the NGINX Instance Manager. In addition to monitoring your application security, you will be able to manage your NGINX App Protect WAF configurations and security policies in a single location and push pre-compiled updates to an instance or instance group.
1616

1717
---
1818

1919
## Before you begin
2020

21-
Complete these steps before starting:
21+
Complete the following prerequisites before proceeding with the steps in this guide.
2222

23-
1. If you’re new to NGINX App Protect WAF, follow these guides:
23+
1. If you are new to NGINX App Protect WAF, follow the instructions in the installation and configuration guides to get up and running:
2424

25-
- [Install NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) on each data plane instance. Ensure connectivity to the NGINX Instance Manager host.
26-
- [Configure NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration-overview) as needed for each instance.
25+
- [Install NGINX App Protect WAF]({{< ref "/nap-waf/v4/admin-guide/install.md" >}}) on one or more data plane instances. Each data plane instance must have connectivity to the NGINX Instance Manager host.
26+
- [Configure NGINX App Protect WAF]({{< ref "/nap-waf/v4//configuration-guide/configuration.md#policy-configuration-overview" >}}) according to your needs on each of the data plane instance.
2727

28-
2. Review NGINX App Protect WAF dependencies:
28+
1. Review the dependencies with NGINX App Protect WAF and NGINX Plus.
2929

3030
{{< include "nim/tech-specs/security-data-plane-dependencies.md" >}}
3131

32-
3. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**.
32+
1. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**.
33+
1. [Upload your license]({{< relref "/nim/admin-guide/license/add-license.md" >}}).
3334

3435
---
3536

3637
## Install NGINX Agent
3738

38-
NGINX Agent collects metrics, manages configurations, and sends events. Install and configure it on each WAF data plane host.
39+
NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instance that provides:
3940

40-
1. Connect to the host via SSH.
41-
2. Install the NGINX Agent package from the NGINX Instance Manager host:
41+
- Remote management of NGINX configurations
42+
- Collection and reporting of real-time NGINX performance and operating system metrics
43+
- Notifications of NGINX events
44+
45+
Repeat the steps in this section on each NGINX App Protect WAF data plane host to install and configure NGINX Agent for use with Security Monitoring. **These settings apply to both of the Security Monitoring use cases.**
46+
47+
1. Use SSH to connect to the data plane host.
48+
1. Install the NGINX Agent package from the NGINX Instance Manager host.
4249

4350
{{< include "agent/installation/install-agent-api.md" >}}
4451

45-
3. Edit `/etc/nginx-agent/nginx-agent.conf` to enable `nap_monitoring`. Add this configuration:
52+
1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to add the `nap_monitoring` configuration.
4653

47-
```yaml
54+
```yaml
4855
dataplane:
4956
status:
57+
# poll interval for data plane status - the frequency the NGINX Agent will query the data plane for changes
5058
poll_interval: 30s
59+
# report interval for data plane status - the maximum duration to wait before syncing data plane information if no updates have been observed
5160
report_interval: 24h
5261
events:
62+
# report data plane events back to the management plane
5363
enable: true
5464
metrics:
65+
# specify the size of a buffer to build before sending metrics
5566
bulk_size: 20
67+
# specify metrics poll interval
5668
report_interval: 1m
5769
collection_interval: 15s
5870
mode: aggregated
71+
72+
# OSS NGINX default config path
73+
# path to aux file dirs can also be added
5974
config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect"
75+
76+
# Enable reporting NGINX App Protect details to the management plane.
6077
extensions:
61-
- nginx-app-protect
62-
- nap-monitoring
78+
- nginx-app-protect
79+
- nap-monitoring
80+
81+
# Enable reporting NGINX App Protect details to the control plane.
6382
nginx_app_protect:
83+
# Report interval for NGINX App Protect details - the frequency the NGINX Agent checks NGINX App Protect for changes.
6484
report_interval: 15s
85+
# Enable precompiled publication from the NGINX Instance Manager (true) or perform compilation on the data plane host (false).
6586
precompiled_publication: true
87+
88+
# NGINX App Protect Monitoring config
6689
nap_monitoring:
90+
# Buffer size for collector. Will contain log lines and parsed log lines
6791
collector_buffer_size: 50000
92+
# Buffer size for processor. Will contain log lines and parsed log lines
6893
processor_buffer_size: 50000
94+
# Syslog server IP address the collector will be listening to
6995
syslog_ip: "127.0.0.1"
96+
# Syslog server port the collector will be listening to
7097
syslog_port: 514
71-
```
7298

73-
4. If `location /api` isn’t configured in `nginx.conf`, add this directive:
99+
1. If `location /api` isn’t configured in `nginx.conf`, add this directive:
74100

75101
```nginx
76102
server {
@@ -82,111 +108,137 @@ NGINX Agent collects metrics, manages configurations, and sends events. Install
82108
}
83109
```
84110

85-
Restart NGINX:
111+
After adding the directive, restart NGINX to apply the changes:
86112

87-
```bash
113+
```shell
88114
sudo systemctl restart nginx
89115
```
90116

91-
5. **Important:** The `syslog:server=<syslog_ip>:<syslog_port>` must match the `syslog_ip` and `syslog_port` values in the NGINX Agent configuration file. The dashboards won’t display data if these settings don’t match.
92-
93-
- For NGINX App Protect Version 5, networking changes prevent using `127.0.0.1` as a syslog server address. Instead, use the `docker0` interface address (typically `192.0.10.1`) or the IP address of the data plane host.
117+
{{<important>}}You can change the values of `syslog_ip` and `syslog_port` to meet your needs.
118+
You must use the same values when configuring logging for the Security Monitoring module. If the `syslog:<server><port>` configuration does not match these settings, the monitoring dashboards will not display any data. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{</important>}}
94119

95-
6. Use the NGINX Agent installation script to add `nginx_app_protect` and `nap_monitoring` fields to the configuration. Follow these steps:
120+
{{<note>}}You can use the NGINX Agent installation script to add the fields for `nginx_app_protect` and `nap_monitoring`:
96121

97-
```bash
98-
# Download the installation script via API
99-
curl https://<NMS_FQDN>/install/nginx-agent > install.sh
122+
```shell
123+
# Download install script via API
124+
curl https://<NMS_FQDN>/install/nginx-agent > install.sh
100125
101-
# Use the --nap-monitoring flag to set the child fields for nap_monitoring.
102-
# The values will match the example configuration above.
103-
# Use -m | --nginx-app-protect-mode to set up NGINX App Protect management.
104-
# Example: Specify 'precompiled-publication' for precompiled policy publication,
105-
# which sets 'precompiled_publication' to 'true'. To set it to 'false', use 'none'.
126+
# Use the flag --nap-monitoring to set the child fields for the field 'nap_monitoring', the
127+
# child field values will be set to the values in the example configuration from above. Specify
128+
# the -m | --nginx-app-protect-mode flag to set up management of NGINX App Protect on the instance.
129+
# In the example below we specify 'precompiled-publication' for the flag value which will make the
130+
# config field 'precompiled_publication' set to 'true', if you would like to set the config field
131+
# 'precompiled_publication' to 'false' you can specify 'none' as the flag value.
132+
sudo sh ./install.sh --nap-monitoring true --nginx-app-protect-mode precompiled-publication
133+
```
106134

107-
sudo sh ./install.sh --nap-monitoring true --nginx-app-protect-mode precompiled-publication
108-
```
135+
Restart NGINX Agent:
109136

110-
{{<note>}}The `--nap-monitoring` flag adds fields under `nap_monitoring`. The `--nginx-app-protect-mode` flag sets up management of NGINX App Protect with the following options:
111-
- Use `precompiled-publication` to enable precompiled policy publication (`precompiled_publication: true`).
112-
- Use `none` if you don’t want to enable precompiled publication (`precompiled_publication: false`).{{</note>}}
137+
```shell
138+
sudo systemctl restart nginx-agent
139+
```
113140

114-
7. Restart the NGINX Agent:
141+
{{</ note >}}
115142

116-
```bash
117-
sudo systemctl restart nginx-agent
118-
```
119143

120144
---
121145

122146
## Create instances for Security Monitoring only
123147

124-
Use these steps if you’re only monitoring security data without managing configurations in NGINX Instance Manager.
148+
Complete the steps in this section if you are only using the Security Monitoring module to monitor your application security. In this use case, you are **not using Instance Manager** to manage your WAF security policies.
125149

126-
1. Connect to the data plane host via SSH.
127-
2. Create a log format file at `/etc/app_protect/conf/log_sm.json`:
150+
Repeat the steps below on each NGINX App Protect WAF data plane instance.
128151

129-
```json
152+
1. Use SSH to connect to the data plane host.
153+
154+
1. Create a new log format definition file with the name `/etc/app_protect/conf/log_sm.json` and the contents shown below.
155+
This defines the log format for the Security Monitoring module.
156+
157+
This configuration sets the maximum accepted request payload to 2048 bytes and the maximum message size to 5k. The latter setting truncates messages larger than 5k.
158+
2. Add character escaping for the used separator `,` to be escaped with its standard URL encoding `%2C`.
159+
160+
``` json
130161
{
131-
"filter": {
132-
"request_type": "illegal"
133-
},
134-
"content": {
135-
"format": "user-defined",
136-
"format_string": "%blocking_exception_reason%,%dest_port%,%ip_client%,%severity%,%uri%",
137-
"escaping_characters": [
138-
{
139-
"from": ",",
140-
"to": "%2C"
141-
}
142-
],
143-
"max_request_size": "2048",
144-
"max_message_size": "5k"
145-
}
162+
"filter": {
163+
"request_type": "illegal"
164+
},
165+
"content": {
166+
"format": "user-defined",
167+
"format_string": "%blocking_exception_reason%,%dest_port%,%ip_client%,%is_truncated_bool%,%method%,%policy_name%,%protocol%,%request_status%,%response_code%,%severity%,%sig_cves%,%sig_set_names%,%src_port%,%sub_violations%,%support_id%,%threat_campaign_names%,%violation_rating%,%vs_name%,%x_forwarded_for_header_value%,%outcome%,%outcome_reason%,%violations%,%violation_details%,%bot_signature_name%,%bot_category%,%bot_anomalies%,%enforced_bot_anomalies%,%client_class%,%client_application%,%client_application_version%,%transport_protocol%,%uri%,%request%",
168+
"escaping_characters": [
169+
{
170+
"from": ",",
171+
"to": "%2C"
172+
}
173+
],
174+
"max_request_size": "2048",
175+
"max_message_size": "5k",
176+
"list_delimiter": "::"
177+
}
146178
}
147179
```
148180

149-
3. In the NGINX configuration, add:
181+
1. Find the context in your NGINX configuration where NGINX App Protect WAF logging is enabled.
182+
In the same context, add the `app_protect_security_log` directive shown in the example below to configure attack data logging for use with the Security Monitoring dashboards.
150183

151184
```nginx
152-
app_protect_security_log_enable on;
153-
app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514;
185+
app_protect_security_log_enable on;
186+
app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514;
154187
```
155188

156-
4. Restart NGINX Agent and NGINX:
189+
{{<important>}}The `syslog:server=<syslog_ip>:<syslog_port>` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{</important>}}
190+
191+
1. Restart NGINX Agent and the NGINX web server.
157192

158193
```bash
159194
sudo systemctl restart nginx-agent
160195
sudo systemctl restart nginx
161196
```
162197

198+
You should now be able to view data from your NGINX App Protect instances in the NGINX Security Monitoring dashboards.
199+
163200
---
164201

165202
## Create instances for Security Monitoring with Instance Manager
166203

167-
Follow these steps to use Security Monitoring and Instance Manager together.
204+
Complete the steps in this section if you want to use the Security Monitoring module **and** Instance Manager. In this use case, you will use NGINX Instance Manager to monitor threats and to manage your NGINX App Protect WAF configurations and security policies.
205+
206+
Take the steps below to update your NGINX App Protect WAF configurations by using Instance Manager.
168207

169-
1. Log in to the NGINX Instance Manager interface.
170-
2. Navigate to **Modules** > **Instance Manager**.
171-
3. Select **Edit Config** for the desired instance or group.
172-
4. Add the following to the configuration file:
208+
1. Log in to the NGINX Instance Manager user interface and go to **Modules** > **Instance Manager**.
209+
1. Select **Instances** or **Instance Groups**, as appropriate.
210+
1. Select **Edit Config** from the **Actions** menu for the desired instance or instance group.
211+
1. Next, edit the desired configuration file. You will add directives that reference the security policies bundle and enable the NGINX App Protect WAF logs required by the Security Monitoring dashboards. An example configuration is provided below.
173212

174213
```nginx
175-
app_protect_enable on;
176-
app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz";
177-
app_protect_security_log_enable on;
178-
app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514;
214+
app_protect_enable on;
215+
app_protect_enable on;
216+
app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz";
217+
app_protect_security_log_enable on;
218+
app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514;
179219
```
180220

181-
5. **Important:** Add the `app_protect_policy_file` directive with a reference to a security policy. Use the `.tgz` file extension for precompiled publication or `.json` for non-precompiled configurations. Ensure the policy file exists at the specified location. If using custom policies, update them in NGINX Instance Manager.
221+
- Add the `app_protect_policy_file` directive with a reference to a security policy.
222+
223+
The policy reference must use the `.tgz` file extension when using Instance Manager to perform precompiled publication of NGINX App Protect WAF policies and log profiles. The file path referenced must exist on the NGINX Instance Manager host, but it's ok if the policy file doesn't exist yet. If your Instance is not configured for precompiled publication, then use the `.json` file extension for polcies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance.
224+
225+
If you are using custom security policies, at this stage, it's fine to use the default security policy shown in the example above. After completing the steps in this guide, refer to the instructions in [Set Up App Protect WAF Configuration Management]({{< relref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration.
226+
227+
- Add the `app_protect_security_log_enable on` and the `app_protect_security_log` directive to any NGINX context where NGINX App Protect WAF is enabled and you want to be able to review attack data.
228+
229+
The logging configuration must reference `"/etc/nms/secops_dashboard.tgz"`, as shown in the example.
230+
231+
If the `app_protect_security_log_enable` setting is already present, just add the `app_protect_security_log` beneath it in the same context.
232+
233+
{{<important>}}The `syslog:server=<syslog_ip>:<syslog_port>` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The Security Monitoring dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{</important>}}
182234

183-
6. Add the `app_protect_security_log_enable` and `app_protect_security_log` directives to log attack data. Ensure the configuration references the correct `syslog:server` values.
235+
1. Select **Publish** to immediately push the configuration file updates out to your NGINX instance or instance group.
184236

185-
7. Select **Publish** to push updates to instances.
237+
You should now be able to view data from your NGINX App Protect WAF instances in the Security Monitoring dashboard.
186238

187239
---
188240

189241
## See also
190242

191-
- [Add user access to Security Monitoring dashboards]({{< relref "/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}})
192-
- [Manage your app protect WAF configs]({{< relref "/nim/nginx-app-protect/setup-waf-config-management" >}})
243+
- [Add user access to Security Monitoring dashboards]({{< ref "/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}})
244+
- [Manage your app protect WAF configs]({{< relref "/nim/nginx-app-protect/setup-waf-config-management.md" >}})

‎content/nim/nginx-app-protect/security-monitoring/troubleshooting.md

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
---
2-
docs: DOCS-1226
3-
doctypes:
4-
- reference
5-
tags:
6-
- docs
72
title: Troubleshooting
3+
weight: 500
84
toc: true
9-
weight: 1000
5+
type: how-to
6+
product: NIM
7+
docs: DOCS-1226
8+
109
---
1110

1211
## Security event log backup with Security Monitoring

0 commit comments

Comments
 (0)