Skip to content

feat(events): introduce dns_request_kernel event #4867

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlonZivony wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(events): introduce dns_request_kernel event #4867

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions .github/workflows/pr.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ env:
SET_FS_PWD
SUSPICIOUS_SYSCALL_SOURCE
STACK_PIVOT
DNS_REQUEST_KERNEL
jobs:
#
# DOC VERIFICATION
Expand Down
141 changes: 141 additions & 0 deletions docs/docs/events/builtin/man/network/dns_request_kernel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# dns_request_kernel(1)

## NAME

dns_request_kernel - Kernel-level DNS request capture event

## DESCRIPTION

The **dns_request_kernel** event shows DNS queries captured at the kernel level. Check [net_packet_dns.md](net_packet_dns.md) for more information on DNS. This event provides a **simple, reliable, and efficient** alternative to network packet-based DNS monitoring. Unlike the complex network event infrastructure that relies on packet capture and filtering, this event uses a direct kernel hook on the `udp_sendmsg` function, making it more reliable and performant.

DNS queries come in various types, each serving a specific purpose in the domain name resolution process or in retrieving information from DNS servers:

- **Standard Query (A or AAAA)**: Requests IPv4 (A) or IPv6 (AAAA) address associated with a given domain name
- **Inverse Query (PTR)**: Provides an IP address and asks for the associated domain name (PTR record)
- **Mail Exchange Query (MX)**: Retrieves mail exchange servers responsible for receiving email for a specific domain
- **Name Server Query (NS)**: Discovers the authoritative name servers for a domain
- **Start of Authority Query (SOA)**: Retrieves SOA record containing essential information about the domain
- **Service Query (SRV)**: Locates services associated with a specific domain (SIP, XMPP, LDAP)
- **Text Query (TXT)**: Retrieves text-based information associated with a domain
- **Canonical Name Query (CNAME)**: Finds the canonical (true) name of an alias domain
- **Pointer Query (PTR) for IPv6**: Similar to PTR queries for IPv4, but for IPv6 addresses
- **Wildcard Query**: Uses '*' character to match multiple subdomains or hostnames within a domain

**Key Features:**
- **Kernel-level monitoring**: Captures DNS requests at the kernel level by hooking the `udp_sendmsg` function
- **Port-based filtering**: Only captures UDP packets destined for port 53 (DNS)
- **Multiple data formats**: Supports both iovec and ubuf message formats
- **DNS parsing**: Automatically parses DNS messages to extract hostname and query type information
- **Process context**: Provides full process context including process name, PID, and other metadata

**Advantages:**
- **Reliability**: Direct kernel hooking provides more consistent event generation compared to network packet capture
- **Performance**: Efficient kernel-level monitoring without network packet processing overhead
- **Simplicity**: Straightforward implementation without complex network infrastructure dependencies
- **Early detection**: Captures DNS requests before they leave the system
- **Process attribution**: Provides clear process context for each DNS request
- **Kernel-level accuracy**: Not affected by network-level filtering or NAT

**Limitations:**
- **UDP only**: Only captures UDP-based DNS requests (not TCP DNS)
- **Single iovec node**: Currently supports only the first iovec node in multi-node vectors
- **Kernel version dependency**: Requires specific kernel features for iov_iter handling

## EVENT SETS

This event is included in the following event sets:

- **network_events**: Network-related events

## DATA FIELDS

**hostname** (*string*)
: The domain name being queried (e.g., "google.com")

**query_type** (*string*)
: The type of DNS query (e.g., "A", "AAAA", "MX", "TXT")

## DEPENDENCIES

**Kernel Hooks:**

- udp_sendmsg: KProbe hook on the `udp_sendmsg` kernel function to capture UDP packets being sent to port 53. This function is called whenever a process attempts to send a UDP packet, making it an ideal interception point for DNS requests.

The hook performs several key operations:
1. **Port filtering**: Checks if the destination port is 53 (DNS)
2. **Message format detection**: Determines whether the message uses iovec or ubuf format
3. **Data extraction**: Captures the DNS payload from the appropriate message format
4. **Process context**: Records the calling process information

## USE CASES

- **High-performance environments**: When you need efficient DNS monitoring without network packet processing overhead

- **Reliable monitoring**: When you require consistent event generation without dependency on network infrastructure

- **Security monitoring**: Detecting suspicious DNS queries or data exfiltration attempts with guaranteed process attribution

- **Network troubleshooting**: Understanding which processes are making DNS requests with kernel-level accuracy

- **Compliance**: Auditing DNS activity for regulatory requirements with reliable event capture

- **Performance analysis**: Identifying DNS-related performance issues without the overhead of packet capture

## RELATED EVENTS

- **net_packet_dns**: General DNS packet events (both requests and responses)

- **net_packet_dns_request**: Network packet-based DNS request monitoring (more complex, relies on network infrastructure)

- **net_packet_dns_response**: DNS response monitoring (network packet-based)

## EXAMPLE

```console
$ tracee --output json --events dns_request_kernel
```

The event captures DNS queries with detailed process context and DNS query information:

```json
{
"timestamp": 1696255905516744399,
"threadStartTime": 1695658999333342363,
"processorId": 4,
"processId": 1234,
"cgroupId": 2626,
"threadId": 1234,
"parentProcessId": 1,
"hostProcessId": 1234,
"hostThreadId": 1234,
"hostParentProcessId": 1,
"userId": 976,
"mountNamespace": 4026532555,
"pidNamespace": 4026531836,
"processName": "systemd-resolve",
"executable": {"path": ""},
"hostName": "example-host",
"containerId": "",
"container": {},
"kubernetes": {},
"eventId": "2008",
"eventName": "dns_request_kernel",
"matchedPolicies": [""],
"argsNum": 2,
"returnValue": 0,
"syscall": "write",
"stackAddresses": [0],
"contextFlags": {"containerStarted": false, "isCompat": false},
"threadEntityId": 131662446,
"processEntityId": 131662446,
"parentEntityId": 1975426032,
"args": [
{"name": "hostname", "type": "string", "value": "google.com"},
{"name": "query_type", "type": "string", "value": "A"}
]
}
```

Choose `dns_request_kernel` when you need reliable event generation without network infrastructure dependencies, better performance by avoiding packet capture overhead, simpler implementation with direct kernel hooking, and guaranteed process attribution at the kernel level.

Choose network packet events when you need DNS response monitoring (this event only captures requests), TCP-based DNS monitoring (this event only captures UDP), or network-level packet analysis and filtering.
1 change: 1 addition & 0 deletions docs/docs/events/builtin/network-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ activity in common protocols.
- [net_packet_dns](man/network/net_packet_dns.md)
- [net_packet_dns_request](man/network/net_packet_dns_request.md)
- [net_packet_dns_response](man/network/net_packet_dns_response.md)
- [dns_request_kernel](man/network/dns_request_kernel.md)
- [net_packet_http](man/network/net_packet_http.md)
- [net_packet_http_request](man/network/net_packet_http_request.md)
- [net_packet_http_response](man/network/net_packet_http_response.md)
Expand Down
187 changes: 187 additions & 0 deletions docs/man/dns_request_kernel.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
.\" Automatically generated by Pandoc 3.2
.\"
.TH "" "" "" "" ""
.SH dns_request_kernel(1)
.SS NAME
dns_request_kernel \- Kernel\-level DNS request capture event
.SS DESCRIPTION
The \f[B]dns_request_kernel\f[R] event shows DNS queries captured at the
kernel level.
Check net_packet_dns.md for more information on DNS.
This event provides a \f[B]simple, reliable, and efficient\f[R]
alternative to network packet\-based DNS monitoring.
Unlike the complex network event infrastructure that relies on packet
capture and filtering, this event uses a direct kernel hook on the
\f[CR]udp_sendmsg\f[R] function, making it more reliable and performant.
.PP
DNS queries come in various types, each serving a specific purpose in
the domain name resolution process or in retrieving information from DNS
servers:
.IP \[bu] 2
\f[B]Standard Query (A or AAAA)\f[R]: Requests IPv4 (A) or IPv6 (AAAA)
address associated with a given domain name
.IP \[bu] 2
\f[B]Inverse Query (PTR)\f[R]: Provides an IP address and asks for the
associated domain name (PTR record)
.IP \[bu] 2
\f[B]Mail Exchange Query (MX)\f[R]: Retrieves mail exchange servers
responsible for receiving email for a specific domain
.IP \[bu] 2
\f[B]Name Server Query (NS)\f[R]: Discovers the authoritative name
servers for a domain
.IP \[bu] 2
\f[B]Start of Authority Query (SOA)\f[R]: Retrieves SOA record
containing essential information about the domain
.IP \[bu] 2
\f[B]Service Query (SRV)\f[R]: Locates services associated with a
specific domain (SIP, XMPP, LDAP)
.IP \[bu] 2
\f[B]Text Query (TXT)\f[R]: Retrieves text\-based information associated
with a domain
.IP \[bu] 2
\f[B]Canonical Name Query (CNAME)\f[R]: Finds the canonical (true) name
of an alias domain
.IP \[bu] 2
\f[B]Pointer Query (PTR) for IPv6\f[R]: Similar to PTR queries for IPv4,
but for IPv6 addresses
.IP \[bu] 2
\f[B]Wildcard Query\f[R]: Uses \[cq]*\[cq] character to match multiple
subdomains or hostnames within a domain
.PP
\f[B]Key Features:\f[R] \- \f[B]Kernel\-level monitoring\f[R]: Captures
DNS requests at the kernel level by hooking the \f[CR]udp_sendmsg\f[R]
function \- \f[B]Port\-based filtering\f[R]: Only captures UDP packets
destined for port 53 (DNS) \- \f[B]Multiple data formats\f[R]: Supports
both iovec and ubuf message formats \- \f[B]DNS parsing\f[R]:
Automatically parses DNS messages to extract hostname and query type
information \- \f[B]Process context\f[R]: Provides full process context
including process name, PID, and other metadata
.PP
\f[B]Advantages:\f[R] \- \f[B]Reliability\f[R]: Direct kernel hooking
provides more consistent event generation compared to network packet
capture \- \f[B]Performance\f[R]: Efficient kernel\-level monitoring
without network packet processing overhead \- \f[B]Simplicity\f[R]:
Straightforward implementation without complex network infrastructure
dependencies \- \f[B]Early detection\f[R]: Captures DNS requests before
they leave the system \- \f[B]Process attribution\f[R]: Provides clear
process context for each DNS request \- \f[B]Kernel\-level
accuracy\f[R]: Not affected by network\-level filtering or NAT
.PP
\f[B]Limitations:\f[R] \- \f[B]UDP only\f[R]: Only captures UDP\-based
DNS requests (not TCP DNS) \- \f[B]Single iovec node\f[R]: Currently
supports only the first iovec node in multi\-node vectors \- \f[B]Kernel
version dependency\f[R]: Requires specific kernel features for iov_iter
handling
.SS EVENT SETS
This event is included in the following event sets:
.IP \[bu] 2
\f[B]network_events\f[R]: Network\-related events
.SS DATA FIELDS
.TP
\f[B]hostname\f[R] (\f[I]string\f[R])
The domain name being queried (e.g., \[lq]google.com\[rq])
.TP
\f[B]query_type\f[R] (\f[I]string\f[R])
The type of DNS query (e.g., \[lq]A\[rq], \[lq]AAAA\[rq], \[lq]MX\[rq],
\[lq]TXT\[rq])
.SS DEPENDENCIES
\f[B]Kernel Hooks:\f[R]
.IP \[bu] 2
udp_sendmsg: KProbe hook on the \f[CR]udp_sendmsg\f[R] kernel function
to capture UDP packets being sent to port 53.
This function is called whenever a process attempts to send a UDP
packet, making it an ideal interception point for DNS requests.
.PP
The hook performs several key operations: 1.
\f[B]Port filtering\f[R]: Checks if the destination port is 53 (DNS) 2.
\f[B]Message format detection\f[R]: Determines whether the message uses
iovec or ubuf format 3.
\f[B]Data extraction\f[R]: Captures the DNS payload from the appropriate
message format 4.
\f[B]Process context\f[R]: Records the calling process information
.SS USE CASES
.IP \[bu] 2
\f[B]High\-performance environments\f[R]: When you need efficient DNS
monitoring without network packet processing overhead
.IP \[bu] 2
\f[B]Reliable monitoring\f[R]: When you require consistent event
generation without dependency on network infrastructure
.IP \[bu] 2
\f[B]Security monitoring\f[R]: Detecting suspicious DNS queries or data
exfiltration attempts with guaranteed process attribution
.IP \[bu] 2
\f[B]Network troubleshooting\f[R]: Understanding which processes are
making DNS requests with kernel\-level accuracy
.IP \[bu] 2
\f[B]Compliance\f[R]: Auditing DNS activity for regulatory requirements
with reliable event capture
.IP \[bu] 2
\f[B]Performance analysis\f[R]: Identifying DNS\-related performance
issues without the overhead of packet capture
.SS RELATED EVENTS
.IP \[bu] 2
\f[B]net_packet_dns\f[R]: General DNS packet events (both requests and
responses)
.IP \[bu] 2
\f[B]net_packet_dns_request\f[R]: Network packet\-based DNS request
monitoring (more complex, relies on network infrastructure)
.IP \[bu] 2
\f[B]net_packet_dns_response\f[R]: DNS response monitoring (network
packet\-based)
.SS EXAMPLE
.IP
.EX
$ tracee \-\-output json \-\-events dns_request_kernel
.EE
.PP
The event captures DNS queries with detailed process context and DNS
query information:
.IP
.EX
{
\[dq]timestamp\[dq]: 1696255905516744399,
\[dq]threadStartTime\[dq]: 1695658999333342363,
\[dq]processorId\[dq]: 4,
\[dq]processId\[dq]: 1234,
\[dq]cgroupId\[dq]: 2626,
\[dq]threadId\[dq]: 1234,
\[dq]parentProcessId\[dq]: 1,
\[dq]hostProcessId\[dq]: 1234,
\[dq]hostThreadId\[dq]: 1234,
\[dq]hostParentProcessId\[dq]: 1,
\[dq]userId\[dq]: 976,
\[dq]mountNamespace\[dq]: 4026532555,
\[dq]pidNamespace\[dq]: 4026531836,
\[dq]processName\[dq]: \[dq]systemd\-resolve\[dq],
\[dq]executable\[dq]: {\[dq]path\[dq]: \[dq]\[dq]},
\[dq]hostName\[dq]: \[dq]example\-host\[dq],
\[dq]containerId\[dq]: \[dq]\[dq],
\[dq]container\[dq]: {},
\[dq]kubernetes\[dq]: {},
\[dq]eventId\[dq]: \[dq]2008\[dq],
\[dq]eventName\[dq]: \[dq]dns_request_kernel\[dq],
\[dq]matchedPolicies\[dq]: [\[dq]\[dq]],
\[dq]argsNum\[dq]: 2,
\[dq]returnValue\[dq]: 0,
\[dq]syscall\[dq]: \[dq]write\[dq],
\[dq]stackAddresses\[dq]: [0],
\[dq]contextFlags\[dq]: {\[dq]containerStarted\[dq]: \f[B]false\f[R], \[dq]isCompat\[dq]: \f[B]false\f[R]},
\[dq]threadEntityId\[dq]: 131662446,
\[dq]processEntityId\[dq]: 131662446,
\[dq]parentEntityId\[dq]: 1975426032,
\[dq]args\[dq]: [
{\[dq]name\[dq]: \[dq]hostname\[dq], \[dq]type\[dq]: \[dq]string\[dq], \[dq]value\[dq]: \[dq]google.com\[dq]},
{\[dq]name\[dq]: \[dq]query_type\[dq], \[dq]type\[dq]: \[dq]string\[dq], \[dq]value\[dq]: \[dq]A\[dq]}
]
}
.EE
.PP
Choose \f[CR]dns_request_kernel\f[R] when you need reliable event
generation without network infrastructure dependencies, better
performance by avoiding packet capture overhead, simpler implementation
with direct kernel hooking, and guaranteed process attribution at the
kernel level.
.PP
Choose network packet events when you need DNS response monitoring (this
event only captures requests), TCP\-based DNS monitoring (this event
only captures UDP), or network\-level packet analysis and filtering.
Loading