feat(observability): add structured target context metadata for runtime block events

[Akshu121796]

Summary
This PR improves runtime observability by attaching structured contextual metadata (target_context) to emitted security audit events generated from blocked runtime actions.
The implementation uses the newly exposed ContextVal field from the eBPF ringbuffer layer and formats contextual runtime targets into human-readable values for downstream SIEM/debugging workflows.

Changes Made

• Added contextual target metadata support for emitted audit events
• Parsed blocked IPv4 network targets into dotted-quad format for:
  • connect_denied
  • exfil_blocked
• Added inode-style contextual formatting for:
  • open_inode
  • mirage_trap
• Attached formatted values through structured target_context metadata emission

Benefits

• Improved runtime observability
• Better SIEM/debugging visibility
• Easier investigation of blocked runtime actions
• Cleaner contextual tracing for enforcement decisions

Note: I was able to validate the formatter integration flow and structured event emission logic from the code path itself, but I could not fully reproduce the kernel/eBPF runtime environment locally on Windows for end-to-end runtime verification.

Fixes #74

[Akshu121796]

Hi @nevinshine
I’ve completed the Go-side contextual parsing and structured metadata emission changes using the new ContextVal field exposed from the kernel ringbuffer layer and have raised the PR for review.

The implementation now:

• formats blocked IPv4 network targets into readable dotted-quad strings,
• adds inode-style contextual formatting for inode/file-related events,
• and emits the formatted value through structured target_context metadata for improved observability and SIEM tracing workflows.

Please review when possible.
If no changes, add required labels(ggsoc: approved)..

Thank you for your understanding!!

[nevinshine]

Hi @Akshu121796,

Thanks for getting this done so quickly! The logic looks great overall and successfully hooks up the target_context to our NDJSON alerts. I just noticed one bug and one small missing piece we should fix before merging:

IP Address Byte Order: You're currently using binary.BigEndian.PutUint32 to parse the IP address. While network byte order is indeed big-endian, the eBPF kernel code actually reads the raw network-byte-order memory into a host CPU register (which is little-endian) before sending it over the ring buffer. Because of this, using BigEndian in Go will actually reverse the IP address (e.g., 192.168.1.100 would end up logging as 100.1.168.192). Could you switch this to use binary.LittleEndian.PutUint32(ip, uint32(event.ContextVal))?

ptrace_denied Support: You correctly handled the network and inode contexts, but there's one more blocked action in our eBPF code that passes contextual data. When an agent tries to ptrace a tainted process, we deny it and pass the target child's PID as the context. Could you add a quick case for this as well? Something like:

else if event.DescStr == "ptrace_denied" {
    targetContext = fmt.Sprintf("pid:%d", event.ContextVal)

Let me know once you've pushed these updates and I'll be happy to approve and merge it. Thanks again for your work on this!

[Akshu121796]

Hello! @nevinshine
Thank you for the detailed review and especially for clarifying the endianness behavior between the kernel ringbuffer and userspace parsing layer that explanation makes perfect sense now.

I’ll update the IP parsing to use binary.LittleEndian.PutUint32(...) and also add the missing ptrace_denied contextual PID formatting support, then push the changes to this PR shortly.

Thanks again for the guidance!

[Akshu121796]

Hi @nevinshine
Thanks again for the clarification regarding the ringbuffer endianness behavior.

I’ve now updated the implementation to:

• switch IPv4 parsing to binary.LittleEndian.PutUint32(...) for correct userspace IP reconstruction,
• and added contextual PID formatting support for ptrace_denied events as well.

The updates have been pushed to this PR for review.
Please review when possible.
If no changes, add required labels(ggsoc: approved).

Thankyou! Looking out to more contibutions.

[nevinshine]

Thank you for taking the time to read through the explanation on the ringbuffer endianness and for implementing the LittleEndian fix so cleanly. It can be really tricky dealing with low-level kernel-to-userspace memory translation, and you handled it perfectly. Also, great job getting the ptrace_denied context hooked up!

It is incredibly refreshing to work with a contributor who takes technical feedback seriously, understands it, and applies it directly to the code. This is exactly the kind of high-quality engineering contribution we are looking for in this project <3

I am approving and merging this now. Outstanding work, @Akshu121796! :)

[Akshu121796]

@nevinshine Thankyou for your feedback and support!!
Without splitting the work it would have been more difficult.

Looking out for more contribution, Loved the repo!!⭐