argos_sdk 1.0.0

Argos Security SDK for Dart — HTTP monitoring and threat detection middleware for Shelf, Dart Frog, Conduit, Alfred, Serverpod, Appwrite, and Firebase Functions.

Argos Security SDK for Dart

HTTP monitoring and threat-detection middleware for Dart backend frameworks. Sends every request to the Argos dashboard for analysis and blocks malicious traffic (XSS, SQL injection, brute force, etc.) before it reaches your handlers.

Supports Shelf · Dart Frog · Conduit · Alfred · Serverpod · Appwrite Functions · Firebase Functions.

Looking for Supabase support? Use the TypeScript SDK — Supabase Edge Functions run on Deno, not Dart.

---

Install

Add to your pubspec.yaml:

dependencies:
  argos_sdk:
    git:
      url: https://github.com/argossecurity/argos-dart

Then add your framework of choice — shelf, dart_frog, conduit, alfred, serverpod, etc.

---

Quick start (Shelf)

import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
import 'package:argos_sdk/argos_sdk.dart';

void main() async {
  final client = ArgosClient(ArgosConfig(
    apiKey: Platform.environment['ARGOS_API_KEY']!,
    autoBlockOnBlock: true,
  ));

  final handler = const Pipeline()
      .addMiddleware(createShelfMiddleware(client, mode: MiddlewareMode.sync))
      .addHandler((req) => Response.ok('hello'));

  await io.serve(handler, 'localhost', 8080);
}

---

Framework integrations

Framework	Function	Notes
Shelf	createShelfMiddleware(client)	Standard Middleware = Handler Function(Handler)
Dart Frog	handler.use(createArgosShelfMiddleware(client))	Built on Shelf
Conduit	ArgosConduitMiddleware(client).process(request)	Call from a Controller
Alfred	app.all('*', createAlfredMiddleware(client))	Express-style callback
Serverpod	await argosCheckSession(client, session)	Call inside endpoint methods
Appwrite Functions	wrapAppwriteHandler(client, handler)	Wraps Future start(req, res)
Firebase Functions	createFirebaseHandler(client, handler)	Experimental — Dart Functions are still beta

All framework packages are optional — install only the one you use.

---

Demo: Todo app

A working demo lives in todo/ — a Shelf-based todo server protected by Argos middleware in sync mode with auto-block on BLOCK verdict.

Run it

cd todo
dart pub get
ARGOS_API_KEY=your_key dart run bin/server.dart

Then open http://localhost:8080 in your browser.

What to try

Action	Expected result
Add a normal todo (e.g. Buy milk)	✅ Saved, returns 200
Add <script>alert('xss')</script>	🚫 Blocked with 403, x-argos-verdict: BLOCK
Add '; DROP TABLE users; --	🚫 Blocked with 403, x-argos-verdict: BLOCK
Toggle / delete a todo	✅ Goes through
After a block, retry from the same IP	🚫 Auto-blocked at the blocklist check (cached locally + synced to dashboard)

Admin endpoints (dev only)

The demo exposes a few helpers for testing:

# List all blocked IPs / users
curl http://localhost:8080/api/argos/blocklist

# Unblock a specific entry
curl -X DELETE http://localhost:8080/api/argos/blocklist/<entry_id>

# Nuclear: unblock everyone
curl -X DELETE http://localhost:8080/api/argos/blocklist

How it works

1. bin/server.dart sets up a Shelf Pipeline with createShelfMiddleware(client, mode: MiddlewareMode.sync)
2. Every request body is read, sent to Argos /api/v1/ingest, and inspected for threats
3. On BLOCK verdict the middleware returns 403 immediately — your handler is never called
4. With autoBlockOnBlock: true, the offending IP is cached locally and added to the dashboard blocklist so future requests are rejected at the cheap checkAccess step

---

Configuration

ArgosConfig(
  apiKey: 'argus_env_...',
  baseUrl: 'https://api.argossecops.com',  // default
  autoBlockOnBlock: true,                  // auto-add IP to blocklist on BLOCK
  timeout: Duration(seconds: 30),
  maxRetries: 3,
  circuitBreakerThreshold: 5,              // open circuit after N failures
  circuitBreakerTimeout: Duration(seconds: 60),
  queueSize: 1000,                         // async-mode queue size
  flushInterval: Duration(seconds: 5),     // async-mode flush cadence
  blocklistCacheTtl: Duration(seconds: 60),
  retryStrategy: RetryStrategy.exponential,
)

---

Modes

Mode	Behavior
MiddlewareMode.sync	Wait for Argos verdict before responding. Blocks malicious requests inline. Use for security-critical endpoints.
MiddlewareMode.async_	Queue the event and respond immediately. Lower latency, but blocking only happens on the next request via cached blocklist.

---

Development

# Run analyzer
dart analyze

# Run all tests (48 tests)
dart test

# Run a single test file
dart test test/middleware_shelf_test.dart

---

License

MIT