Troubleshooting Guide

1. Connection & Communication Issues

Symptom: Jibril agents are not appearing in the Garnet Platform dashboard, or their status is offline.

Check API Key: Ensure the GARNET_API_TOKEN (or the equivalent API key used by the Jibril agent) is correct and has not been revoked. Regenerate and update if necessary.
Network Connectivity to Platform: Verify that the host/environment where the Jibril agent is running has outbound network connectivity to the Garnet Platform's ingestion endpoints (usually HTTPS on TCP/443).
Firewall/Network Policies: If you're in a restricted network environment (e.g., corporate networks, cloud VPCs with strict egress rules), ensure outbound traffic to the Garnet Platform domains is allowed.
Proxy Configuration: If your environment uses an HTTP proxy for external connectivity, ensure the agent is configured to use it.

For diagnostics, check:

Agent Logs: Check the logs of the Jibril agent itself. These are invaluable for diagnosing issues.
- GitHub Actions: Look at the output of the Garnet Scan step in your workflow logs.
- Kubernetes: Use kubectl logs <jibril-pod-name> -n <namespace>.
- Standalone Docker/Binary: Check stdout/stderr or the configured log file for Jibril.
Network Diagnostics: Standard tools like curl, ping, telnet, nslookup to test connectivity to platform endpoints.
Platform Status: Check if there are any ongoing incidents or maintenance announced for the Garnet Platform itself.

2. eBPF & Permission Issues

Symptom: Agent is online but not reporting events, or reporting errors related to eBPF or capabilities.

Privileges: Jibril requires elevated privileges to load and use eBPF programs and monitor system activity.
- Docker/Kubernetes: Ensure the container has necessary capabilities like CAP_SYS_ADMIN, CAP_BPF, CAP_PERFMON (kernel 5.8+ for perfmon), CAP_SYSLOG (for some logging configurations). Security contexts should be properly configured.
- Standalone Binary: Typically needs to run as root or with sudo.
Kernel Version Compatibility: Ensure your Linux kernel version is compatible with the eBPF features Jibril uses. Generally, kernel 4.14+ is a minimum, with 5.x+ being better. Older or custom kernels may have issues.
SELinux/AppArmor: If enabled, security profiles (like SELinux policies or AppArmor profiles) might be preventing Jibril from accessing necessary resources or performing certain actions. Check audit logs.
Secure Boot / Kernel Lockdown: In some highly secure environments, kernel lockdown modes or Secure Boot configurations might restrict eBPF usage. This is less common but possible.
Resource Limits: Ensure the Jibril agent has sufficient CPU and memory resources. While it's low-overhead, extremely constrained environments could still cause issues.

3. Detection Issues

Symptom: You expect a certain malicious activity to be detected/blocked, but it isn't.

Policy Configuration (Platform): Verify in the Garnet Platform that the relevant detection rules or policies are enabled for the target environment/agent.
Agent Version: Ensure the Jibril agent is up-to-date. New detections and capabilities are added in newer versions.
Scope of Detection: Understand what a specific detection rule is designed to catch. It might not cover the exact scenario you are testing.
Activity Obscured: The malicious activity might be obscured (e.g., encrypted, running in a way that evades current detection logic).
False Negative: While Garnet aims for high accuracy, no detection system is perfect. If you believe you've found a false negative (a missed detection of genuine malicious activity), report it to Garnet support.

4. False Positives

Symptom: Receiving too many alerts for benign or expected activity.

Tuning Detections: In the Garnet Platform, see if you can tune the sensitivity of specific detection rules or create allow-lists/suppression rules for known benign activity that matches a detection pattern.
Review Activity: Understand why the activity is being flagged. It might be non-standard but legitimate in your context.
Provide Feedback: If a core Garnet detection rule is consistently causing false positives in a common scenario, provide feedback to Garnet support.

5. Performance Issues

Symptom: System performance degradation after deploying Jibril.

Verify Overhead: Jibril is designed for low overhead. If you suspect it, use standard system monitoring tools (top, htop, vmstat) to check its resource consumption (CPU, memory).
Misconfiguration or Bugs: In rare cases, a misconfiguration or a bug in a specific Jibril version or eBPF program could lead to higher overhead. Check agent logs.
Kernel Issues: Very occasionally, interactions with specific kernel versions or other eBPF programs could lead to unexpected behavior. This is rare.
Contact Support: If you observe significant, unexplained performance impact, gather data and contact Garnet support.

Last updated 16 days ago

1. Connection & Communication Issues

Symptom: Jibril agents are not appearing in the Garnet Platform dashboard, or their status is offline.

Check API Key: Ensure the GARNET_API_TOKEN (or the equivalent API key used by the Jibril agent) is correct and has not been revoked. Regenerate and update if necessary.

Network Connectivity to Platform: Verify that the host/environment where the Jibril agent is running has outbound network connectivity to the Garnet Platform's ingestion endpoints (usually HTTPS on TCP/443).

Firewall/Network Policies: If you're in a restricted network environment (e.g., corporate networks, cloud VPCs with strict egress rules), ensure outbound traffic to the Garnet Platform domains is allowed.

Proxy Configuration: If your environment uses an HTTP proxy for external connectivity, ensure the agent is configured to use it.

For diagnostics, check:

Agent Logs: Check the logs of the Jibril agent itself. These are invaluable for diagnosing issues.

GitHub Actions: Look at the output of the Garnet Scan step in your workflow logs.
Kubernetes: Use kubectl logs <jibril-pod-name> -n <namespace>.
Standalone Docker/Binary: Check stdout/stderr or the configured log file for Jibril.

Network Diagnostics: Standard tools like curl, ping, telnet, nslookup to test connectivity to platform endpoints.

Platform Status: Check if there are any ongoing incidents or maintenance announced for the Garnet Platform itself.

2. eBPF & Permission Issues

Symptom: Agent is online but not reporting events, or reporting errors related to eBPF or capabilities.

Privileges: Jibril requires elevated privileges to load and use eBPF programs and monitor system activity.

Docker/Kubernetes: Ensure the container has necessary capabilities like CAP_SYS_ADMIN, CAP_BPF, CAP_PERFMON (kernel 5.8+ for perfmon), CAP_SYSLOG (for some logging configurations). Security contexts should be properly configured.
Standalone Binary: Typically needs to run as root or with sudo.

Kernel Version Compatibility: Ensure your Linux kernel version is compatible with the eBPF features Jibril uses. Generally, kernel 4.14+ is a minimum, with 5.x+ being better. Older or custom kernels may have issues.

SELinux/AppArmor: If enabled, security profiles (like SELinux policies or AppArmor profiles) might be preventing Jibril from accessing necessary resources or performing certain actions. Check audit logs.

Secure Boot / Kernel Lockdown: In some highly secure environments, kernel lockdown modes or Secure Boot configurations might restrict eBPF usage. This is less common but possible.

Resource Limits: Ensure the Jibril agent has sufficient CPU and memory resources. While it's low-overhead, extremely constrained environments could still cause issues.

3. Detection Issues

Symptom: You expect a certain malicious activity to be detected/blocked, but it isn't.

Policy Configuration (Platform): Verify in the Garnet Platform that the relevant detection rules or policies are enabled for the target environment/agent.

Agent Version: Ensure the Jibril agent is up-to-date. New detections and capabilities are added in newer versions.

Scope of Detection: Understand what a specific detection rule is designed to catch. It might not cover the exact scenario you are testing.

Activity Obscured: The malicious activity might be obscured (e.g., encrypted, running in a way that evades current detection logic).

False Negative: While Garnet aims for high accuracy, no detection system is perfect. If you believe you've found a false negative (a missed detection of genuine malicious activity), report it to Garnet support.

4. False Positives

Symptom: Receiving too many alerts for benign or expected activity.

Tuning Detections: In the Garnet Platform, see if you can tune the sensitivity of specific detection rules or create allow-lists/suppression rules for known benign activity that matches a detection pattern.

Review Activity: Understand why the activity is being flagged. It might be non-standard but legitimate in your context.

Provide Feedback: If a core Garnet detection rule is consistently causing false positives in a common scenario, provide feedback to Garnet support.

5. Performance Issues

Symptom: System performance degradation after deploying Jibril.

Verify Overhead: Jibril is designed for low overhead. If you suspect it, use standard system monitoring tools (top, htop, vmstat) to check its resource consumption (CPU, memory).

Misconfiguration or Bugs: In rare cases, a misconfiguration or a bug in a specific Jibril version or eBPF program could lead to higher overhead. Check agent logs.

Kernel Issues: Very occasionally, interactions with specific kernel versions or other eBPF programs could lead to unexpected behavior. This is rare.

Contact Support: If you observe significant, unexplained performance impact, gather data and contact Garnet support.

If you are unable to resolve an issue using this guide, please refer to the .