StackSentinel

An autonomous edge-agent that uses Amazon Nova to detect failures and execute secure bash fixes in real-time, auto-healing your Linux server so you can stop debugging logs at 3 AM.

Comment

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for StackSentinel

💡 Inspiration

Between constantly tweaking and custom-ricing my own Ubuntu environments and diving deep into complex architecture for my coursework, I’ve experienced the frustration of broken dependencies and missing configuration files firsthand. For system administrators, this pain is magnified a thousand times over. Traditional monitoring tools only alert you after a critical service like Nginx or PostgreSQL has already crashed.

I wanted to move beyond reactive dashboards. Inspired by the rapid advancements in LLM reasoning, I asked myself: What if a server could diagnose its own raw logs and heal itself before a human even wakes up? That vision led to the creation of StackSentinel, an autonomous, edge-deployed digital sysadmin powered by Amazon Nova.

⚙️ How we built it

StackSentinel operates on a decoupled architecture designed for both extreme privilege and absolute safety.

  • The Brain: The core watchdog is written in Python. It constantly tails system logs (/var/log or our dummy targets) and intercepts CRITICAL or ERROR flags.
  • The LLM Integration: Upon detecting an anomaly, the agent passes the raw log context to Amazon Nova 2 Lite via the AWS Bedrock API. To handle potential API rate limits gracefully, the system is designed with an exponential backoff algorithm where the wait time $T$ for the $n$-th retry is calculated as $T_n = \min(T_{max}, T_{base} \cdot 2^n)$.
  • The Safety Net: Giving an AI root access is inherently dangerous. I built a local Python execution auditor that acts as a strict firewall. Before any LLM-generated bash command touches the kernel, it is parsed and checked against a blocklist of destructive actions (e.g., rm -rf).
  • The C2 Dashboard: I built a Flask-based Command and Control UI. Using Inter-Process Communication (IPC) via atomic JSON writes, the root-level watchdog securely streams telemetry to the user-level dashboard. Pyngrok auto-tunnels this UI to the public web for mobile monitoring.

🚧 Challenges we ran into

Building a system that operates at the root level of a Linux machine brought some massive systems engineering headaches:

  1. Virtual Environment Isolation vs. Global Execution: Wrapping the project in a safe Python venv meant standard terminal shells like zsh couldn't find the stacksentinel command. I had to engineer an install.sh script that correctly navigated PATH variables and .local/bin symlinks to make the CLI global without breaking the host system.
  2. POSIX Permissions and DBUS: Running the watchdog via sudo -E (to preserve AWS SSO credentials) caused clashes with the desktop display server (dbus), crashing the script when it tried to send desktop notifications. I had to refactor the notification logic to gracefully fail or bypass the local display server entirely.
  3. Strict File Locks: When creating the dummy logs for testing, I ran into classic chmod permission denials because the root watchdog owned the files, preventing my standard user account from injecting the test errors.

📚 What we learned

This project was a masterclass in low-level Linux administration and AI integration. I deepened my understanding of POSIX file permissions, atomic IPC mechanisms, and how to safely manage environment variables (sudo -E) across different privilege levels.

More importantly, I learned how to "tame" an LLM. By wrapping Amazon Nova 2 Lite in strict programmatic guardrails, I learned that you can safely bridge the gap between generative AI and deterministic, high-stakes system infrastructure.

🚀 What's next for StackSentinel

In the future, I want to expand the Execution Safety Net to include a dry-run simulation environment, allowing StackSentinel to test its generated bash commands in an isolated Docker container before executing them on the bare metal host. I also plan to add multi-node support, allowing a single StackSentinel C2 dashboard to manage an entire fleet of servers.

Built With

Share this project:

Updates