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.

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