Skip to content

Commit 00108a5

Browse files
mouraddmeirimouraddmeiri
authored
chore: add policy types
1 parent 9caf64d commit 00108a5

File tree

1 file changed

+312
-1
lines changed

1 file changed

+312
-1
lines changed

‎content/waf/policies/lifecycle-management.md‎

Lines changed: 312 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -844,6 +844,317 @@ Downloading security updates may take several minutes, and the version of securi
844844

845845
If _APSignatures_ is not created or the specified versions are not available, it will default to the version stored in the compiler Docker image.
846846

847+
## Policy Types and References
848+
849+
NGINX App Protect WAF with Policy Lifecycle Management supports multiple ways to define and reference security policies through APPolicy Custom Resources. This flexibility allows you to choose the most appropriate approach based on your deployment architecture, policy management workflow, and operational requirements.
850+
851+
## Policy Definition Types
852+
853+
Policy Lifecycle Management supports three distinct approaches for defining WAF policies:
854+
855+
### 1. [Inline Policy Definition](#inline-policy-definition)
856+
Define the complete policy configuration directly within the Custom Resource specification.
857+
858+
### 2. [JSON Policy Reference](#json-policy-reference)
859+
Reference a JSON policy file stored in the shared persistent volume.
860+
861+
### 3. [Precompiled Bundle Reference](#precompiled-bundle-reference)
862+
Reference a precompiled policy bundle (.tgz file) stored in the shared persistent volume.
863+
864+
## Inline Policy Definition
865+
866+
### Description
867+
868+
Inline policy definition allows you to specify the complete WAF policy configuration directly within the APPolicy Custom Resource. This approach provides full declarative management through Kubernetes manifests and is ideal for version-controlled policy configurations.
869+
870+
### Example Configuration
871+
872+
Create a file named `inline-policy.yaml`:
873+
874+
```yaml
875+
apiVersion: appprotect.f5.com/v1
876+
kind: APPolicy
877+
metadata:
878+
name: dataguard-blocking-inline
879+
namespace: <namespace>
880+
spec:
881+
policy:
882+
name: dataguard_blocking_inline
883+
template:
884+
name: POLICY_TEMPLATE_NGINX_BASE
885+
applicationLanguage: utf-8
886+
enforcementMode: blocking
887+
blocking-settings:
888+
violations:
889+
- name: VIOL_DATA_GUARD
890+
alarm: true
891+
block: true
892+
- name: VIOL_ATTACK_SIGNATURE
893+
alarm: true
894+
block: true
895+
data-guard:
896+
enabled: true
897+
maskData: true
898+
creditCardNumbers: true
899+
usSocialSecurityNumbers: true
900+
enforcementMode: ignore-urls-in-list
901+
enforcementUrls: []
902+
```
903+
904+
Apply the policy:
905+
```bash
906+
kubectl apply -f inline-policy.yaml
907+
```
908+
909+
## JSON Policy Reference
910+
911+
### Description
912+
913+
JSON policy reference allows you to store your policy configuration as a separate JSON file in the shared persistent volume and reference it from the APPolicy Custom Resource. This approach separates policy content from Kubernetes resource management while maintaining compilation automation.
914+
915+
### Prerequisites
916+
917+
- Policy JSON file must be stored in the shared persistent volume
918+
- File must be accessible at the specified path within the container
919+
- Proper file permissions (readable by the Policy Controller)
920+
921+
### File Change Tracking
922+
923+
The Policy Controller can automatically monitor policy files for changes and trigger recompilation when modifications are detected. This feature is controlled through the `externalReferenceDetails.tracking` configuration:
924+
925+
- **`tracking.enabled`**: Enable/disable automatic file monitoring (default: true)
926+
- **`tracking.intervalInSeconds`**: Polling interval for file changes (default: 5 seconds)
927+
928+
### Example Configuration
929+
930+
**Step 1: Create the policy JSON file**
931+
932+
First, create your policy JSON file and place it in the shared volume. For example, create `/mnt/nap5_bundles_pv_data/dg_policy.json`:
933+
934+
```json
935+
{
936+
"name": "dataguard_blocking_json",
937+
"template": {
938+
"name": "POLICY_TEMPLATE_NGINX_BASE"
939+
},
940+
"applicationLanguage": "utf-8",
941+
"enforcementMode": "blocking",
942+
"blocking-settings": {
943+
"violations": [
944+
{
945+
"name": "VIOL_DATA_GUARD",
946+
"alarm": true,
947+
"block": true
948+
},
949+
{
950+
"name": "VIOL_ATTACK_SIGNATURE",
951+
"alarm": true,
952+
"block": true
953+
}
954+
]
955+
},
956+
"data-guard": {
957+
"enabled": true,
958+
"maskData": true,
959+
"creditCardNumbers": true,
960+
"usSocialSecurityNumbers": true,
961+
"enforcementMode": "ignore-urls-in-list",
962+
"enforcementUrls": []
963+
},
964+
"signature-settings": {
965+
"signatureStaging": false
966+
}
967+
}
968+
```
969+
970+
**Step 2: Create the APPolicy Custom Resource**
971+
972+
Create a file named `json-policy.yaml`:
973+
974+
```yaml
975+
apiVersion: appprotect.f5.com/v1
976+
kind: APPolicy
977+
metadata:
978+
name: dataguard-blocking-ref
979+
namespace: <namespace>
980+
spec:
981+
policy:
982+
$ref: /etc/app_protect/bundles/dg_policy.json
983+
externalReferenceDetails:
984+
tracking:
985+
enabled: true
986+
intervalInSeconds: 10
987+
```
988+
989+
**Step 3: Apply the Custom Resource**
990+
991+
```bash
992+
kubectl apply -f json-policy.yaml
993+
```
994+
995+
### File Path Considerations
996+
997+
- **Container Path**: The `$ref` path must be the path as seen from within the Policy Controller container
998+
- **Shared Volume**: The file must be in the shared persistent volume mounted to both Policy Controller and NGINX containers
999+
- **Default Mount Path**: The shared volume is typically mounted at `/etc/app_protect/bundles`
1000+
- **Absolute Paths**: Always use absolute paths in the `$ref` field
1001+
1002+
### Updating Policy Files
1003+
1004+
Once the APPolicy Custom Resource has been applied, updating your policy is simple - you only need to modify the JSON file:
1005+
1006+
**To update your policy:**
1007+
1. Edit the JSON file directly (e.g., `/mnt/nap5_bundles_pv_data/dg_policy.json`)
1008+
2. Save your changes
1009+
3. The Policy Controller automatically handles the rest
1010+
1011+
**What happens automatically:**
1012+
1. **Automatic Detection**: If tracking is enabled, file changes are detected automatically
1013+
2. **Recompilation Trigger**: Policy Controller triggers automatic recompilation
1014+
3. **Status Updates**: Custom Resource status reflects the new compilation state
1015+
4. **Bundle Replacement**: New policy bundle replaces the previous version
1016+
1017+
{{< call-out "note" >}}
1018+
**No CR Reapplication Needed**: You do NOT need to reapply the APPolicy Custom Resource when updating the JSON file. Simply edit the file and the Policy Controller will detect the changes and recompile automatically.
1019+
{{< /call-out >}}
1020+
1021+
## Precompiled Bundle Reference
1022+
1023+
### Description
1024+
1025+
Precompiled bundle reference allows you to use policy bundles that have been pre-compiled using external WAF compiler tools. This approach is useful for policies compiled outside of the Kubernetes environment or when integrating with external policy management systems.
1026+
1027+
### Prerequisites
1028+
1029+
- Precompiled bundle (.tgz) file must be stored in the shared persistent volume
1030+
- Bundle must be compatible with the current WAF Enforcer version
1031+
- Proper file permissions (readable by the Policy Controller)
1032+
1033+
### Bundle Validation
1034+
1035+
The Policy Controller performs validation of precompiled bundles using `apcompile --dump` to ensure:
1036+
1037+
- **Bundle Integrity**: Verification that the bundle is properly formed
1038+
- **Version Compatibility**: Confirmation that the bundle works with current enforcer
1039+
- **Content Validation**: Basic checks on policy structure and syntax
1040+
1041+
### Example Configuration
1042+
1043+
**Step 1: Prepare the precompiled bundle**
1044+
1045+
Ensure your precompiled policy bundle is available in the shared volume. For example, place `policy2.tgz` in `/mnt/nap5_bundles_pv_data/`.
1046+
1047+
**Step 2: Create the APPolicy Custom Resource**
1048+
1049+
Create a file named `precompiled-bundle-policy.yaml`:
1050+
1051+
```yaml
1052+
apiVersion: appprotect.f5.com/v1
1053+
kind: APPolicy
1054+
metadata:
1055+
name: dataguard-tgz
1056+
namespace: <namespace>
1057+
spec:
1058+
policy:
1059+
$ref: /etc/app_protect/bundles/policy2.tgz
1060+
externalReferenceDetails:
1061+
tracking:
1062+
enabled: true
1063+
intervalInSeconds: 10
1064+
```
1065+
1066+
**Step 3: Apply the Custom Resource**
1067+
1068+
```bash
1069+
kubectl apply -f precompiled-bundle-policy.yaml
1070+
```
1071+
1072+
### Bundle Management
1073+
1074+
When using precompiled bundles:
1075+
1076+
1. **Validation Phase**: Policy Controller validates the bundle structure
1077+
2. **Deployment**: Bundle is made available to NGINX containers
1078+
3. **Change Detection**: If tracking is enabled, bundle file changes trigger updates
1079+
4. **Status Reporting**: Custom Resource status shows bundle deployment state
1080+
1081+
### Updating Precompiled Bundles
1082+
1083+
Once the APPolicy Custom Resource has been applied, updating your policy bundle is straightforward:
1084+
1085+
**To update your bundle:**
1086+
1. Replace the existing bundle file with your new bundle (keeping the same filename)
1087+
2. For example, replace `/mnt/nap5_bundles_pv_data/policy2.tgz` with your updated bundle
1088+
3. The Policy Controller automatically handles the rest
1089+
1090+
**What happens automatically:**
1091+
1. **Change Detection**: If tracking is enabled, the Policy Controller detects the file modification
1092+
2. **Revalidation**: The new bundle is validated using `apcompile --dump`
1093+
3. **Deployment**: If validation passes, the new bundle is deployed
1094+
4. **Status Updates**: Custom Resource status reflects the new validation and deployment state
1095+
1096+
{{< call-out "note" >}}
1097+
**No CR Reapplication Needed**: You do NOT need to reapply the APPolicy Custom Resource when updating the bundle file. Simply replace the bundle file with the same name and the Policy Controller will detect the changes and revalidate automatically.
1098+
{{< /call-out >}}
1099+
1100+
## Policy Status Monitoring
1101+
1102+
Regardless of the policy type used, you can monitor the status of your policies using standard Kubernetes commands:
1103+
1104+
### Check Policy Status
1105+
1106+
```bash
1107+
kubectl get appolicy -n <namespace>
1108+
kubectl describe appolicy <policy-name> -n <namespace>
1109+
kubectl get appolicy <policy-name> -n <namespace> -o yaml
1110+
```
1111+
1112+
### Status Fields
1113+
1114+
All policy types provide similar status information:
1115+
1116+
- **`status.bundle.state`**: Policy compilation/validation state (`ready`, `processing`, `error`)
1117+
- **`status.bundle.location`**: Path to the deployed policy bundle
1118+
- **`status.bundle.compilerVersion`**: Version of the compiler used
1119+
- **`status.bundle.signatures`**: Signature package timestamps
1120+
- **`status.processing.isCompiled`**: Compilation success indicator
1121+
- **`status.processing.datetime`**: Last processing timestamp
1122+
1123+
### Example Status Output
1124+
1125+
```yaml
1126+
status:
1127+
bundle:
1128+
compilerVersion: 11.553.0
1129+
location: /etc/app_protect/bundles/dataguard-blocking-ref-policy/dataguard-blocking-ref_policy20250925101234.tgz
1130+
signatures:
1131+
attackSignatures: "2025-09-20T08:36:25Z"
1132+
botSignatures: "2025-09-20T10:50:19Z"
1133+
threatCampaigns: "2025-09-18T07:28:43Z"
1134+
state: ready
1135+
processing:
1136+
datetime: "2025-09-25T10:12:45Z"
1137+
isCompiled: true
1138+
```
1139+
1140+
## Troubleshooting
1141+
1142+
### Common Issues
1143+
1144+
**Policy File Not Found**
1145+
- Verify the file exists in the shared persistent volume
1146+
- Check the file path in the `$ref` field
1147+
- Ensure proper file permissions
1148+
1149+
**Compilation Failures**
1150+
- Check Policy Controller logs for detailed error messages
1151+
- Validate policy JSON syntax
1152+
- Ensure policy structure matches WAF requirements
1153+
1154+
**File Change Not Detected**
1155+
- Verify tracking is enabled in `externalReferenceDetails.tracking.enabled`
1156+
- Check the polling interval setting
1157+
- Ensure the file modification time changes when updated
8471158

8481159
## Testing policy lifecycle management
8491160

@@ -1095,4 +1406,4 @@ For more information relevant to this type of deployment, see the [Disconnected
10951406

10961407
- Verify the persistent volume is properly mounted
10971408
- Check storage permissions (Should be 101:101)
1098-
- Confirm PVC is bound to the correct PV
1409+
- Confirm PVC is bound to the correct PV

0 commit comments

Comments
 (0)