Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 41 additions & 18 deletions packages/zscaler_zia/_dev/build/docs/README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,15 @@
# Zscaler ZIA

This integration is for Zscaler Internet Access logs. It can be used
to receive logs sent by NSS log server on respective TCP ports.
This integration is for Zscaler Internet Access logs. It can be used to receive logs sent by NSS feeds on TCP port or Cloud NSS on HTTP Endpoint input methods.

The log message is expected to be in JSON format. The data is mapped to
ECS fields where applicable and the remaining fields are written under
`zscaler_zia.<data-stream-name>.*`.
The log message is expected to be in JSON format. The data is mapped to ECS fields where applicable and the remaining fields are written under `zscaler_zia.<data-stream-name>.*`.

## Setup steps
## Steps for setting up NSS Feeds

1. Enable the integration with the TCP input.
2. Configure the Zscaler NSS Server and NSS Feeds to send logs to the Elastic Agent that is running this integration. See [_Add NSS Server_](https://help.zscaler.com/zia/adding-nss-servers) and [_Add NSS Feeds_](https://help.zscaler.com/zia/adding-nss-feeds). Use the IP address hostname of the Elastic Agent as the 'NSS Feed SIEM IP Address/FQDN', and use the listening port of the Elastic Agent as the 'SIEM TCP Port' on the _Add NSS Feed_ configuration screen. To configure Zscalar NSS Server and NSS Feeds follow the following steps.
2. Configure the Zscaler NSS Server and NSS Feeds to send logs to the Elastic Agent that is running this integration. See [_Add NSS Server_](https://help.zscaler.com/zia/adding-nss-servers) and [_Add NSS Feeds_](https://help.zscaler.com/zia/adding-nss-feeds). Use the IP address hostname of the Elastic Agent as the 'NSS Feed SIEM IP Address/FQDN', and use the listening port of the Elastic Agent as the 'SIEM TCP Port' on the _Add NSS Feed_ configuration screen. To configure Zscaler NSS Server and NSS Feeds follow the following steps.
- In the ZIA Admin Portal, add an NSS Server.
- Log in to the ZIA Admin Portal using your admin account. If you're unable to log in, contact Support.
- Log in to the ZIA Admin Portal using your admin account.
- Add an NSS server. Refer to Adding NSS Servers to set up an [_Add NSS Server_](https://help.zscaler.com/zia/adding-nss-servers) for Web and/or Firewall.
- Verify that the state of the NSS Server is healthy.
- In the ZIA Admin Portal, go to Administration > Nanolog Streaming Service > NSS Servers.
Expand All @@ -27,10 +24,32 @@ ECS fields where applicable and the remaining fields are written under
- **Firewall**: 9012
- **Tunnel**: 9013
- **Web**: 9014
- **Feed Output Type**: Select Custom paste the appropriate response format as follows:
![NSS feeds setup image](../img/nss_feeds.png?raw=true)

3. *Please make sure to use the given response formats.*
- **Feed Output Type**: Select Custom in Feed output type and paste the appropriate response format in Feed output format as follows:
![NSS Feeds setup image](../img/nss_feeds.png?raw=true)

## Steps for setting up Cloud NSS Feeds

1. Enable the integration with the HTTP Endpoint input.
2. Configure the Zscaler Cloud NSS Feeds to send logs to the Elastic Agent that is running this integration. Provide API URL to send logs to the Elastic Agent. To configure Zscaler Cloud NSS Feeds follow the following steps.
- In the ZIA Admin Portal, add a Cloud NSS Feed.
- Log in to the ZIA Admin Portal using your admin account.
- Add a Cloud NSS Feed. Refer to [_Add Cloud NSS Feed_](https://help.zscaler.com/zia/adding-cloud-nss-feeds).
- In the ZIA Admin Portal, go to Administration > Nanolog Streaming Service > Cloud NSS Feeds.
- Give Feed Name, change status to Enabled.
- Select NSS Type.
- Change SIEM Type to other.
- Add an API URL.
- Default ports:
- **DNS**: 9556
- **Firewall**: 9557
- **Tunnel**: 9558
- **Web**: 9559
- Select JSON as feed output type.
- Add appropriate HTTP headers.
![Cloud NSS Feeds setup image](../img/cloud_nss_feeds.png?raw=true)
3. Repeat step 2 for each log type.

**Please make sure to use the given response formats for NSS and Cloud NSS Feeds.**

## Compatibility

Expand All @@ -40,7 +59,7 @@ This package has been tested against `Zscaler Internet Access version 6.1`

### Alerts

Default port: _9010_
- Default port (NSS Feed): _9010_

Vendor documentation: https://help.zscaler.com/zia/about-alerts

Expand All @@ -56,7 +75,8 @@ Sample Response:

### DNS Log

Default port: _9011_
- Default port (NSS Feed): _9011_
- Default port (Cloud NSS Feed): _9556_

Vendor documentation: https://help.zscaler.com/zia/nss-feed-output-format-dns-logs

Expand All @@ -72,7 +92,8 @@ Sample Response:

### Firewall Log

Default port: _9012_
- Default port (NSS Feed): _9012_
- Default port (Cloud NSS Feed): _9557_

Vendor documentation: https://help.zscaler.com/zia/nss-feed-output-format-firewall-logs

Expand All @@ -88,7 +109,8 @@ Sample Response:

### Tunnel Log

Default port: _9013_
- Default port (NSS Feed): _9013_
- Default port (Cloud NSS Feed): _9558_

Vendor documentation: https://help.zscaler.com/zia/nss-feed-output-format-tunnel-logs

Expand Down Expand Up @@ -117,8 +139,9 @@ Sample Response:

### Web Log

Default port: _9014_
Add characters **"** and **\\** in **feed escape character** while configuring Web Log.
- Default port (NSS Feed): _9014_
- Default port (Cloud NSS Feed): _9559_
- Add characters **"** and **\\** in **feed escape character** while configuring Web Log.

![Escape feed setup image](../img/escape_feed.png?raw=true)
Vendor documentation: https://help.zscaler.com/zia/nss-feed-output-format-web-logs
Expand Down
46 changes: 41 additions & 5 deletions packages/zscaler_zia/_dev/deploy/docker/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -1,32 +1,68 @@
version: '2.3'
services:
zscaler-zia-alerts-tcp:
image: docker.elastic.co/observability/stream:v0.6.2
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
entrypoint: /bin/bash
command: -c "/stream log --start-signal=SIGHUP --delay=5s --addr elastic-agent:9010 -p=tcp /sample_logs/alerts.log"
zscaler-zia-dns-tcp:
image: docker.elastic.co/observability/stream:v0.6.2
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
entrypoint: /bin/bash
command: -c "/stream log --start-signal=SIGHUP --delay=5s --addr elastic-agent:9011 -p=tcp /sample_logs/dns.log"
zscaler-zia-firewall-tcp:
image: docker.elastic.co/observability/stream:v0.6.2
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
entrypoint: /bin/bash
command: -c "/stream log --start-signal=SIGHUP --delay=5s --addr elastic-agent:9012 -p=tcp /sample_logs/firewall.log"
zscaler-zia-tunnel-tcp:
image: docker.elastic.co/observability/stream:v0.6.2
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
entrypoint: /bin/bash
command: -c "/stream log --start-signal=SIGHUP --delay=5s --addr elastic-agent:9013 -p=tcp /sample_logs/tunnel.log"
zscaler-zia-web-tcp:
image: docker.elastic.co/observability/stream:v0.6.2
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
entrypoint: /bin/bash
command: -c "/stream log --start-signal=SIGHUP --delay=5s --addr elastic-agent:9014 -p=tcp /sample_logs/web.log"
zscaler-zia-dns-http-endpoint:
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
environment:
- STREAM_PROTOCOL=webhook
- STREAM_ADDR=http://elastic-agent:9556/
- STREAM_WEBHOOK_HEADER=Content-Type=application/ndjson
command: log --start-signal=SIGHUP --delay=5s /sample_logs/dns-http_endpoint.log
zscaler-zia-firewall-http-endpoint:
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
environment:
- STREAM_PROTOCOL=webhook
- STREAM_ADDR=http://elastic-agent:9557/
- STREAM_WEBHOOK_HEADER=Content-Type=application/ndjson
command: log --start-signal=SIGHUP --delay=5s /sample_logs/firewall-http_endpoint.log
zscaler-zia-tunnel-http-endpoint:
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
environment:
- STREAM_PROTOCOL=webhook
- STREAM_ADDR=http://elastic-agent:9558/
- STREAM_WEBHOOK_HEADER=Content-Type=application/ndjson
command: log --start-signal=SIGHUP --delay=5s /sample_logs/tunnel-http_endpoint.log
zscaler-zia-web-http-endpoint:
image: docker.elastic.co/observability/stream:v0.7.0
volumes:
- ./sample_logs:/sample_logs:ro
environment:
- STREAM_PROTOCOL=webhook
- STREAM_ADDR=http://elastic-agent:9559/
- STREAM_WEBHOOK_HEADER=Content-Type=application/ndjson
command: log --start-signal=SIGHUP --delay=5s /sample_logs/web-http_endpoint.log
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"sourcetype":"zscalernss-dns","input": {"type": "http_endpoint"}, "event":{"location":"Unknown","deviceowner":"NA","devicehostname":"NA","dns_req":"Unknown","resaction":"None","durationms":"34000","category":"Other","resrulelabel":"None","dns_reqtype":"NotFound","dns_resp":"NotFound","department":"Unknown","user":"Unknown","reqaction":"None","datetime":"Tue Dec 31 02:22:22 2021","srv_dip":"0.0.0.0","clt_sip":"0.0.0.0","reqrulelabel":"None","srv_dport":"0"}}
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{ "sourcetype" : "zscalernss-dns", "event" :{"datetime":"Fri Dec 17 07:27:54 2021","user":"some_user@example.com","department":"Unknown","location":"TestLoc%20DB","reqaction":"REQ_ALLOW","resaction":"Some Response Action","reqrulelabel":"Access%20Blocked","resrulelabel":"None","dns_reqtype":"Some type","dns_req":"example.com","dns_resp":"Some response string","srv_dport":"8080","durationms":"123456","clt_sip":"81.2.69.193","srv_dip":"81.2.69.144","category":"Professional Services","deviceowner":"Owner77","devicehostname":"Machine9000"}}
{ "sourcetype" : "zscalernss-dns", "event" :{"datetime":"Fri Dec 17 07:27:54 2021","user":"some_user@example.com","department":"Unknown","location":"TestLoc%20DB","reqaction":"REQ_ALLOW","resaction":"Some Response Action","reqrulelabel":"Access%20Blocked","resrulelabel":"None","dns_reqtype":"Some type","dns_req":"example.com","dns_resp":"Some response string","srv_dport":"8080","durationms":"123456","clt_sip":"89.160.20.112","srv_dip":"89.160.20.156","category":"Professional Services","deviceowner":"Owner77","devicehostname":"Machine9000"}}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"sourcetype":"zscalernss-fw", "event":{"durationms":"0","avgduration":"0","sdip":"0.0.0.0","aggregate":"No","department":"Unknown","nwapp":"NotAvailable","proto":"IP","datetime":"Tue Dec 31 02:22:22 2022","nwsvc":"None","dnat":"No","threatcat":"None","cdport":"120","duration":"0","ipcat":"Other","deviceowner":"NA","csip":"0.0.0.0","devicehostname":"NA","csport":"0","tunsport":"0","destcountry":"NA","rulelabel":"None","locationname":"Unknown","action":"OutOfRange","stateful":"Yes","outbytes":"0","inbytes":"0","ssport":"0","user":"Unknown","tuntype":"OutOfRange","numsessions":"1","ssip":"0.0.0.0","threatname":"None","ipsrulelabel":"None","tsip":"0.0.0.0","sdport":"0","cdip":"0.0.0.0"}}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"sourcetype":"zscalernss-tunnel", "event":{"location":"Unknown","sourceport":"0","rxbytes":"0","tunneltype":"GRE","dpdrec":"0","destinationip":"0.0.0.0","recordid":"7083020000000007968","datetime":"Tue Dec 31 08:08:08 2021","sourceip":"0.0.0.0","txbytes":"0","Recordtype":"Tunnel Samples","user":"Unknown"}}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{ "sourcetype" : "zscalernss-web", "event" :{"time":"2021-12-31 08:08:08","login":"test@example.com","proto":"HTTP_PROXY","eurl":"www.example.com","action":"Blocked","appname":"General Browsing","appclass":"General Browsing","reqsize":"600","respsize":"65","stime":"0","ctime":"0","urlclass":"Business Use","urlsupercat":"Information Technology","urlcat":"Web Search","malwarecat":"None","threatname":"None","riskscore":"0","dlpeng":"None","dlpdict":"None","location":"Test DB","dept":"Unknown","cip":"1.128.3.4","sip":"1.128.3.4","reqmethod":"CONNECT","respcode":"200","ua":"Windows Microsoft Windows 10 Pro ZTunnel/1.0","ereferer":"None","ruletype":"FwFilter","rulelabel":"Zscaler Proxy Traffic","contenttype":"Other","unscannabletype":"None","deviceowner":"administrator1","devicehostname":"TestMachine35"}}
11 changes: 8 additions & 3 deletions packages/zscaler_zia/changelog.yml
Original file line number Diff line number Diff line change
@@ -1,17 +1,22 @@
# newer versions go on top
- version: "2.0.0"
changes:
- description: Added input for Cloud NSS using HTTP Endpoint input type.
type: enhancement
link: https://github.com/elastic/integrations/pull/3111
- version: "0.2.0"
changes:
- description: Update ECS to 8.2
type: enhancement
link: https://github.com/elastic/integrations/pull/2781
- version: "0.1.3"
changes:
- description: Updated the image file reference in README file
- description: Updated the image file reference in README file.
type: enhancement
link: https://github.com/elastic/integrations/pull/3038
- version: "0.1.2"
changes:
- description: Add documentation for multi-fields
- description: Add documentation for multi-fields.
type: enhancement
link: https://github.com/elastic/integrations/pull/2916
- version: "0.1.1"
Expand All @@ -21,6 +26,6 @@
link: https://github.com/elastic/integrations/pull/2773
- version: "0.1.0"
changes:
- description: Initial draft of the package
- description: Initial draft of the package.
type: enhancement
link: https://github.com/elastic/integrations/pull/2459
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
<114>Dec 10 14:04:28 [175.16.199.1] ZscalerNSS: Zscaler cloud configuration connection to 175.16.199.1:443 lost and unavailable for the past 2325.00 minutes
<114>Dec 10 13:40:32 [81.2.69.193] ZscalerNSS: SIEM Feed connection "DNS Logs Feed" to 81.2.69.193:9012 lost and unavailable for the past 2440.00 minutes
<114>Dec 10 13:44:07 [81.2.69.193] Hey, that's a new type of alert. Isn't it?
<114>Dec 31 12:01:04 [175.16.199.1] ZscalerNSS: Zscaler cloud configuration connection to 175.16.199.1:443 lost and unavailable for the past 2325.00 minutes
<114>Dec 31 13:02:05 [81.2.69.193] ZscalerNSS: SIEM Feed connection "DNS Logs Feed" to 81.2.69.193:9012 lost and unavailable for the past 2440.00 minutes
<114>Dec 31 14:03:06 [81.2.69.193] Hey, that's a new type of alert. Isn't it?
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"expected": [
{
"@timestamp": "2022-12-10T14:04:28.000Z",
"@timestamp": "2022-12-31T12:01:04.000Z",
"destination": {
"address": "175.16.199.1",
"ip": "175.16.199.1",
Expand All @@ -11,7 +11,7 @@
"version": "8.2.0"
},
"event": {
"original": "\u003c114\u003eDec 10 14:04:28 [175.16.199.1] ZscalerNSS: Zscaler cloud configuration connection to 175.16.199.1:443 lost and unavailable for the past 2325.00 minutes"
"original": "\u003c114\u003eDec 31 12:01:04 [175.16.199.1] ZscalerNSS: Zscaler cloud configuration connection to 175.16.199.1:443 lost and unavailable for the past 2325.00 minutes"
},
"log": {
"syslog": {
Expand All @@ -34,7 +34,7 @@
}
},
{
"@timestamp": "2022-12-10T13:40:32.000Z",
"@timestamp": "2022-12-31T13:02:05.000Z",
"destination": {
"address": "81.2.69.193",
"ip": "81.2.69.193",
Expand All @@ -44,7 +44,7 @@
"version": "8.2.0"
},
"event": {
"original": "\u003c114\u003eDec 10 13:40:32 [81.2.69.193] ZscalerNSS: SIEM Feed connection \"DNS Logs Feed\" to 81.2.69.193:9012 lost and unavailable for the past 2440.00 minutes"
"original": "\u003c114\u003eDec 31 13:02:05 [81.2.69.193] ZscalerNSS: SIEM Feed connection \"DNS Logs Feed\" to 81.2.69.193:9012 lost and unavailable for the past 2440.00 minutes"
},
"log": {
"syslog": {
Expand All @@ -68,7 +68,7 @@
}
},
{
"@timestamp": "2022-12-10T13:44:07.000Z",
"@timestamp": "2022-12-31T14:03:06.000Z",
"destination": {
"address": "81.2.69.193",
"ip": "81.2.69.193"
Expand All @@ -77,7 +77,7 @@
"version": "8.2.0"
},
"event": {
"original": "\u003c114\u003eDec 10 13:44:07 [81.2.69.193] Hey, that's a new type of alert. Isn't it?"
"original": "\u003c114\u003eDec 31 14:03:06 [81.2.69.193] Hey, that's a new type of alert. Isn't it?"
},
"log": {
"syslog": {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
tcp:
host: "{{listen_address}}:{{listen_port}}"
tags:
{{#if preserve_original_event}}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@ processors:
target_field: destination.ip
type: ip
ignore_failure: true
- append:
- append:
field: related.ip
value: "{{{destination.ip}}}"
if: ctx?.destination?.ip != null
ignore_failure: true
- date:
- date:
field: _tmp.timestamp
target_field: '@timestamp'
ignore_failure: true
Expand All @@ -37,8 +37,8 @@ processors:
- MMM dd HH:mm:ss
- MMM d HH:mm:ss
- ISO8601
- remove:
field:
- remove:
field:
- _tmp
ignore_missing: true
- remove:
Expand Down
4 changes: 2 additions & 2 deletions packages/zscaler_zia/data_stream/alerts/manifest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ streams:
- input: tcp
template_path: tcp.yml.hbs
title: Zscaler Internet Access Alerts
description: Collect Zscaler Internet Access Alerts using tcp input
description: Collect Zscaler Internet Access Alerts using TCP Input.
vars:
- name: listen_port
type: integer
Expand All @@ -27,7 +27,7 @@ streams:
required: true
show_user: true
title: Preserve original event
description: Preserves a raw copy of the original event, added to the field `event.original`
description: Preserves a raw copy of the original event, added to the field `event.original`.
type: bool
multi: false
default: false
Expand Down
15 changes: 7 additions & 8 deletions packages/zscaler_zia/data_stream/alerts/sample_event.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
{
"@timestamp": "2022-12-10T13:40:32.000Z",
"agent": {
"ephemeral_id": "8c093fcf-fb2f-4baa-b794-40edb011194d",
"hostname": "docker-fleet-agent",
"id": "d03794ae-c5b7-46b2-8a63-42f00010ac23",
"ephemeral_id": "b7f77db9-92fe-4935-8387-b2cb545bcfc6",
"id": "638019f9-173e-4c24-9e28-64b128c92162",
"name": "docker-fleet-agent",
"type": "filebeat",
"version": "7.16.2"
"version": "8.1.2"
},
"data_stream": {
"dataset": "zscaler_zia.alerts",
Expand All @@ -22,21 +21,21 @@
"version": "8.2.0"
},
"elastic_agent": {
"id": "d03794ae-c5b7-46b2-8a63-42f00010ac23",
"id": "638019f9-173e-4c24-9e28-64b128c92162",
"snapshot": false,
"version": "7.16.2"
"version": "8.1.2"
},
"event": {
"agent_id_status": "verified",
"dataset": "zscaler_zia.alerts",
"ingested": "2022-02-04T06:31:25Z"
"ingested": "2022-04-13T17:21:34Z"
},
"input": {
"type": "tcp"
},
"log": {
"source": {
"address": "172.21.0.7:32902"
"address": "1.128.3.4:32902"
},
"syslog": {
"priority": 114
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"sourcetype":"zscalernss-dns","input": {"type": "http_endpoint"}, "event":{"location":"Unknown","deviceowner":"NA","devicehostname":"NA","dns_req":"Unknown","resaction":"None","durationms":"34000","category":"Other","resrulelabel":"None","dns_reqtype":"NotFound","dns_resp":"NotFound","department":"Unknown","user":"Unknown","reqaction":"None","datetime":"Tue Dec 31 02:22:22 2021","srv_dip":"0.0.0.0","clt_sip":"0.0.0.0","reqrulelabel":"None","srv_dport":"0"}}
Loading