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.

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.

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.

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.

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.

Last updated 2 months ago