Merge branch 'main' into main

nginx · Jun 9, 2023 · 25a2bd6 · 25a2bd6
2 parents d462602 + 2b9f2a7
commit 25a2bd6
Show file tree

Hide file tree

Showing 2,565 changed files with 339,880 additions and 26,242 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -5,6 +5,10 @@ on:
     branches:
     - 'main'
     - 'release-*'
+    paths-ignore:
+    - "**.md"
+    - "docs/**"
+    - "hugo/**"
   pull_request:
     types:
     - opened

diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,7 @@
 build/
 **/build/
+build/certs/nginx-repo.key
+build/certs/nginx-repo.crt
 bin/
 whitesource/
 .vscode/

diff --git a/Makefile b/Makefile
@@ -23,8 +23,8 @@ DATE = $(shell date +%F_%H-%M-%S)
 # | suse             | sles12sp5, sle15              |                                                                |
 # | freebsd          |                               | Not supported                                                  |
 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
-OS_RELEASE  ?= ubuntu
-OS_VERSION  ?= 22.04
+OS_RELEASE  ?= debian
+OS_VERSION  ?= bullseye-slim
 BASE_IMAGE  = "${CONTAINER_REGISTRY}/${OS_RELEASE}:${OS_VERSION}"
 IMAGE_TAG   = "agent_${OS_RELEASE}_${OS_VERSION}"
 
@@ -83,7 +83,7 @@ show-env: $(addprefix show-var-, $(SHOW_ENV_VARS)) ## Show environment
 all: clean build run ## Compile and run code.
 
 clean: ## Remove build directory
-	rm -rf ./build
+	if [ -d "./build" ]; then find ./build -mindepth 1 ! -path '${CERTS_DIR}/nginx-repo.crt' ! -path '${CERTS_DIR}/nginx-repo.key' -delete; fi
 
 run: ## Run code
 	go run -ldflags=${LDFLAGS} main.go
@@ -105,7 +105,7 @@ deps: ## Update dependencies in vendor folders
 	go work sync
 
 no-local-changes:
-	git diff --quiet || { echo "Depenency changes detected. Please commit these before pushing." >&2; exit 1; }
+	git diff --quiet || { echo "Dependency changes detected. Please commit these before pushing." >&2; exit 1; }
 
 lint: ## Run linter
 	GOWORK=off go vet ./...
@@ -252,8 +252,8 @@ image: ## Build agent container image for NGINX Plus, need nginx-repo.crt and ng
 	@echo Building image with $(CONTAINER_CLITOOL); \
 	$(CONTAINER_BUILDENV) $(CONTAINER_CLITOOL) build -t ${IMAGE_TAG} . \
 		--no-cache -f ./scripts/docker/nginx-plus/${OS_RELEASE}/Dockerfile \
-		--secret id=nginx-crt,src=build/nginx-repo.crt \
-		--secret id=nginx-key,src=build/nginx-repo.key \
+		--secret id=nginx-crt,src=${CERTS_DIR}/nginx-repo.crt \
+		--secret id=nginx-key,src=${CERTS_DIR}/nginx-repo.key \
 		--build-arg BASE_IMAGE=${BASE_IMAGE} \
 		--build-arg PACKAGES_REPO=${PACKAGES_REPO} \
 		--build-arg OS_RELEASE=${OS_RELEASE} \

diff --git a/README.md b/README.md
@@ -64,8 +64,8 @@ NGINX Agent allows a gRPC connected control system to register a listener for a
 
 | Event                            | Description                                  |
 | -------------------------------- | -------------------------------------------- |
-| AGENT_START_MESSAGE              | NGINX Agent process started                        |
-| AGENT_STOP_MESSAGE               | NGINX Agent process stopped                        |
+| AGENT_START_MESSAGE              | NGINX Agent process started                  |
+| AGENT_STOP_MESSAGE               | NGINX Agent process stopped                  |
 | NGINX_FOUND_MESSAGE              | NGINX master process detected on system      |
 | NGINX_STOP_MESSAGE               | NGINX master process stopped                 |
 | NGINX_RELOAD_SUCCESS_MESSAGE     | NGINX master process reloaded successfully   |
@@ -131,7 +131,7 @@ Follow steps in the [Installation](#installation) section to download, install,
 Using your preferred method, clone the NGINX Agent repository into your development directory. See [Cloning a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for additional help.
 
 ## Installing Go
-NGINX Agent and the Mock Control Plane are written in Go. Go 1.19 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/). 
+NGINX Agent and the Mock Control Plane are written in Go. Go 1.19.9 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/). 
 
 ## Starting the gRPC Mock Control Plane
 Start the mock control plane by running the following command from the `agent` source code root directory:

diff --git a/docs/proto/events.md b/docs/proto/events.md
@@ -43,13 +43,13 @@ Represents an activity event
 <a name="f5-nginx-agent-sdk-events-ContextData"></a>
 
 ### ContextData
-
+Represents the context data of each violation
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| Name | [string](#string) |  |  |
-| Value | [string](#string) |  |  |
+| Name | [string](#string) |  | The name within the context data |
+| Value | [string](#string) |  | The value within the context data |
 
 
 
@@ -117,45 +117,44 @@ Represents a security violation that is emitted by the agent
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| PolicyName | [string](#string) |  |  |
-| SupportID | [string](#string) |  |  |
-| Outcome | [string](#string) |  |  |
-| OutcomeReason | [string](#string) |  |  |
-| BlockingExceptionReason | [string](#string) |  |  |
-| Method | [string](#string) |  |  |
-| Protocol | [string](#string) |  |  |
-| XForwardedForHeaderValue | [string](#string) |  |  |
-| URI | [string](#string) |  |  |
-| Request | [string](#string) |  |  |
-| IsTruncated | [string](#string) |  |  |
-| RequestStatus | [string](#string) |  |  |
-| ResponseCode | [string](#string) |  |  |
-| ServerAddr | [string](#string) |  |  |
-| VSName | [string](#string) |  |  |
-| RemoteAddr | [string](#string) |  |  |
-| RemotePort | [string](#string) |  |  |
-| ServerPort | [string](#string) |  |  |
-| Violations | [string](#string) |  |  |
-| SubViolations | [string](#string) |  |  |
-| ViolationRating | [string](#string) |  |  |
-| SigSetNames | [string](#string) |  |  |
-| SigCVEs | [string](#string) |  |  |
-| ClientClass | [string](#string) |  |  |
-| ClientApplication | [string](#string) |  |  |
-| ClientApplicationVersion | [string](#string) |  |  |
-| Severity | [string](#string) |  |  |
-| ThreatCampaignNames | [string](#string) |  |  |
-| BotAnomalies | [string](#string) |  |  |
-| BotCategory | [string](#string) |  |  |
-| EnforcedBotAnomalies | [string](#string) |  |  |
-| BotSignatureName | [string](#string) |  |  |
-| ViolationContexts | [string](#string) |  |  |
-| ViolationsData | [ViolationData](#f5-nginx-agent-sdk-events-ViolationData) | repeated |  |
-| SystemID | [string](#string) |  |  |
-| InstanceTags | [string](#string) |  |  |
-| InstanceGroup | [string](#string) |  |  |
-| DisplayName | [string](#string) |  |  |
-| ParentHostname | [string](#string) |  |  |
+| PolicyName | [string](#string) |  | The name of the NGINX App Protect policy that triggered the security violation |
+| SupportID | [string](#string) |  | The unique NGINX App Protect support ID of the violation, used for tracking purposes |
+| Outcome | [string](#string) |  | The outcome that resulted for the security violation |
+| OutcomeReason | [string](#string) |  | The reason for the security violation resulting in the outcome |
+| BlockingExceptionReason | [string](#string) |  | The blocking exception reason when a configured violation was not blocked |
+| Method | [string](#string) |  | The HTTP Method of the request that triggered the security violation |
+| Protocol | [string](#string) |  | The HTTP Protocol of the request that triggered the security violation |
+| XForwardedForHeaderValue | [string](#string) |  | The HTTP xff_header_value of the request that triggered the security violation |
+| URI | [string](#string) |  | The URI of the request that triggered the security violation |
+| Request | [string](#string) |  | The full request that triggered the security violation, including the Method, URI and Request Body |
+| IsTruncated | [string](#string) |  | If the request is truncated or not |
+| RequestStatus | [string](#string) |  | The status of the request that triggered the security violation |
+| ResponseCode | [string](#string) |  | The HTTP response status to the request that triggered the security violation |
+| ServerAddr | [string](#string) |  | The server address of the instance that caught the security violation |
+| VSName | [string](#string) |  | The Virtual Server Name of the instance that caught the security violation |
+| RemoteAddr | [string](#string) |  | The targeted address by the request that triggered the security violation |
+| RemotePort | [string](#string) |  | The targeted port number by the request that triggered the security violation |
+| ServerPort | [string](#string) |  | The server port of the instance that caught the security violation |
+| Violations | [string](#string) |  | A comma-separated list of all the violations triggered by the request |
+| SubViolations | [string](#string) |  | A comma-separated list of all the sub-violations triggered by the request |
+| ViolationRating | [string](#string) |  | The rating of the triggered security violation |
+| SigSetNames | [string](#string) |  | A comma-separated list of all the signature names |
+| SigCVEs | [string](#string) |  | A comma-separated list of all the signature CVEs |
+| ClientClass | [string](#string) |  | The class of the client used to send the request that triggered the security violation |
+| ClientApplication | [string](#string) |  | The application used to send the request that triggered the security violation |
+| ClientApplicationVersion | [string](#string) |  | The version of the application used to send the request that triggered the security violation |
+| Severity | [string](#string) |  | The severity of the triggered security violation |
+| ThreatCampaignNames | [string](#string) |  | A comma-separated list of the threat campaign names |
+| BotAnomalies | [string](#string) |  | Anomalies of the bot that sent the request that triggered the security violation |
+| BotCategory | [string](#string) |  | Category of the bot that sent the request that triggered the security violation |
+| EnforcedBotAnomalies | [string](#string) |  | Enforced anomalies of the bot that sent the request that triggered the security violation |
+| BotSignatureName | [string](#string) |  | Signature name of the bot that sent the request that triggered the security violation |
+| ViolationsData | [ViolationData](#f5-nginx-agent-sdk-events-ViolationData) | repeated | A list of objects containing descriptive data about all the security violations |
+| SystemID | [string](#string) |  | SystemID of the instance where NGINX is running |
+| InstanceTags | [string](#string) |  | Instance tags where NGINX is running |
+| InstanceGroup | [string](#string) |  | Instance group where NGINX is running |
+| DisplayName | [string](#string) |  | Display name of the instance where NGINX is running |
+| ParentHostname | [string](#string) |  | The hostname where NGINX is running |
 
 
 
@@ -165,16 +164,16 @@ Represents a security violation that is emitted by the agent
 <a name="f5-nginx-agent-sdk-events-SignatureData"></a>
 
 ### SignatureData
-
+Represents signature data that&#39;s contained within each violation
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ID | [string](#string) |  |  |
-| BlockingMask | [string](#string) |  |  |
-| Buffer | [string](#string) |  |  |
-| Offset | [string](#string) |  |  |
-| Length | [string](#string) |  |  |
+| ID | [string](#string) |  | ID of the signature data |
+| BlockingMask | [string](#string) |  | The blocking mask of the signature data |
+| Buffer | [string](#string) |  | The buffer of the signature data |
+| Offset | [string](#string) |  | The offset of the signature data |
+| Length | [string](#string) |  | The length of the signature data |
 
 
 
@@ -184,15 +183,15 @@ Represents a security violation that is emitted by the agent
 <a name="f5-nginx-agent-sdk-events-ViolationData"></a>
 
 ### ViolationData
-
+Represents the violation data contained within a security violation event
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| Name | [string](#string) |  |  |
-| Context | [string](#string) |  |  |
-| ContextData | [ContextData](#f5-nginx-agent-sdk-events-ContextData) |  |  |
-| Signatures | [SignatureData](#f5-nginx-agent-sdk-events-SignatureData) | repeated |  |
+| Name | [string](#string) |  | The name of the violation |
+| Context | [string](#string) |  | The context of the violation |
+| ContextData | [ContextData](#f5-nginx-agent-sdk-events-ContextData) |  | The object representing the context data of the violation |
+| Signatures | [SignatureData](#f5-nginx-agent-sdk-events-SignatureData) | repeated | A list representing the signature data of the violation |
 
 
 

diff --git a/docs/proto/proto.md b/docs/proto/proto.md
@@ -12,6 +12,8 @@
     - [AgentDetails](#f5-nginx-agent-sdk-AgentDetails)
     - [AgentLogging](#f5-nginx-agent-sdk-AgentLogging)
     - [AgentMeta](#f5-nginx-agent-sdk-AgentMeta)
+    - [Backoff](#f5-nginx-agent-sdk-Backoff)
+    - [Server](#f5-nginx-agent-sdk-Server)
 
     - [AgentConnectStatus.StatusCode](#f5-nginx-agent-sdk-AgentConnectStatus-StatusCode)
     - [AgentLogging.Level](#f5-nginx-agent-sdk-AgentLogging-Level)
@@ -204,6 +206,7 @@ Represents agent details. This message is sent from the management server to the
 | extensions | [string](#string) | repeated | List of agent extensions that are enabled |
 | tags | [string](#string) | repeated | List of tags |
 | alias | [string](#string) |  | Alias name for the agent |
+| server | [Server](#f5-nginx-agent-sdk-Server) |  | Server setting for the agent |
 
 
 
@@ -251,6 +254,45 @@ Represents agent metadata
 
 
 
+
+<a name="f5-nginx-agent-sdk-Backoff"></a>
+
+### Backoff
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| initial_interval | [int64](#int64) |  | First backoff time interval in seconds |
+| randomization_factor | [double](#double) |  | Random value used to create range around next backoff interval |
+| multiplier | [double](#double) |  | Value to be multiplied with current backoff interval |
+| max_interval | [int64](#int64) |  | Max interval in seconds between two retries |
+| max_elapsed_time | [int64](#int64) |  | Elapsed time in seconds after which backoff stops. It never stops if max_elapsed_time == 0. |
+
+
+
+
+
+
+<a name="f5-nginx-agent-sdk-Server"></a>
+
+### Server
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| host | [string](#string) |  | Host name or IP of the host to connect to |
+| grpc_port | [int32](#int32) |  | Grpc port to connect to |
+| token | [string](#string) |  | Shared secrect between the server and client |
+| metrics | [string](#string) |  | Metrics server name |
+| command | [string](#string) |  | Command server name |
+| backoff | [Backoff](#f5-nginx-agent-sdk-Backoff) |  | Backoff settings for exponential retry and backoff |
+
+
+
+
+