HAWK.io Approval Workflow App

Manages approval workflow for quarantine and containment actions with email notifications.

Features

• ✅ Email notifications with approve/deny links
• ✅ Secure one-time use tokens
• ✅ Configurable timeout (default: 4 hours)
• ✅ Automatic case escalation
• ✅ Audit trail of all approvals/denials
• ✅ Status checking and pending approvals list

Installation

cd hawk-soar-cloud-v3/apps/hawk-soar-app-approval-workflow
npm install

Configuration

In HAWK.io platform, navigate to Apps → Approval Workflow and configure:

Required Settings

• Approval Email Addresses: Comma-separated list of SOC manager emails
• SMTP Host: Your email server hostname (e.g., smtp.gmail.com)
• SMTP Port: Usually 587 for TLS or 465 for SSL
• SMTP Username: Email authentication username
• SMTP Password: Email authentication password
• From Email Address: Email address to send from

Optional Settings

• Approval Timeout: Hours until request expires (default: 4)
• Base URL: Your HAWK.io instance URL (default: https://ir.hawk.io)

Usage

Integration Notes

• HTTP routes are registered dynamically from apps/hawk-soar-app-approval-workflow/routes/ via registerRoutes(app) in index.js.
• Approval records are stored in OrientDB (Approvals class). This app does not use Mongo-style db.collection(...).
• WebSocket initiation uses the app handler with routes request_approval, check_approval_status, and list_pending_approvals.
• A client.js is provided for marketplace browser execution. Publish this script into marketplace product code.
• Do not add browser code or module_id fields to server/json/playbookActions.json.
• For the full app integration workflow and conventions, see docs/app-integration.md.

1. Request Approval

Used by AI agent or analysts to request approval:

{
  "action": "request_approval",
  "case_id": "#633:751",
  "action_type": "quarantine",
  "target": "172.16.131.125",
  "reason": "Suspicious lateral movement detected",
  "requester": "AI SOC Agent"
}

Response:

{
  "status": "pending",
  "approval_id": "a1b2c3d4-...",
  "expires_at": "2026-02-08T19:30:00Z",
  "message": "Approval request created. Email sent to..."
}

2. Check Approval Status

{
  "action": "check_approval_status",
  "approval_id": "a1b2c3d4-..."
}

Response:

{
  "approval_id": "a1b2c3d4-...",
  "case_id": "#633:751",
  "action_type": "quarantine",
  "target": "172.16.131.125",
  "status": "approved|denied|pending|expired",
  "created_at": "2026-02-08T15:30:00Z",
  "approved_by": "[email protected]",
  "approved_at": "2026-02-08T15:35:00Z"
}

3. List Pending Approvals

{
  "action": "list_pending_approvals"
}

Response:

{
  "count": 3,
  "approvals": [
    {
      "approval_id": "...",
      "case_id": "#633:751",
      "action_type": "quarantine",
      "target": "172.16.131.125",
      "reason": "...",
      "created_at": "...",
      "expires_at": "..."
    }
  ]
}

Email Template

Recipients receive:

Subject: 🚨 Quarantine Approval Required - Case #633:751

----------------------------------------
⚠️ QUARANTINE APPROVAL REQUIRED
----------------------------------------

A quarantine/containment action requires your immediate approval.

Case ID: #633:751
Action Type: QUARANTINE
Target: 172.16.131.125
Reason: Suspicious lateral movement detected
Requested By: AI SOC Agent
Requested At: 2026-02-08 15:30:00
Expires: 2026-02-08 19:30:00

[APPROVE]  [DENY]

Important Information:
- This approval request expires in 4 hours
- The AI agent investigation is paused
- Click the buttons above to respond

Approval Flow

1. Agent detects quarantine needed
   ↓
2. Calls request_approval action
   ↓
3. App creates approval record
   ↓
4. Email sent to SOC manager(s)
   ↓
5. Case escalated to Critical
   ↓
6. Manager clicks [APPROVE] or [DENY]
   ↓
7. App updates approval status
   ↓
8. Case note added
   ↓
9. Agent receives decision
   ↓
10. Agent proceeds or aborts

Database Schema

Collection: approvals

{
  id: 'uuid',                    // Unique approval ID
  case_id: '#633:751',           // Associated case
  action_type: 'quarantine',     // Action type
  target: '172.16.131.125',      // Target
  reason: 'string',              // Justification
  requester: 'AI SOC Agent',     // Requester
  status: 'pending|approved|denied|expired',
  token: 'secure-token',         // One-time use token
  created_at: 'ISO8601',
  expires_at: 'ISO8601',
  approved_by: 'email',          // Approver email
  approved_at: 'ISO8601',
  denied_by: 'email',            // Denier email
  denied_at: 'ISO8601',
  denial_reason: 'string'        // Optional reason
}

Security

• Secure Tokens: Cryptographically random 32-byte tokens
• One-Time Use: Tokens are invalidated after use
• Expiration: Requests auto-expire after configured timeout
• TLS Required: Approval links must use HTTPS
• Audit Trail: All actions logged with timestamps and emails

Testing

1. Create test approval:

   curl -X POST https://ir.hawk.io/api/actions/approval-workflow/request_approval \
     -H "Content-Type: application/json" \
     -d '{
       "case_id": "#633:751",
       "action_type": "quarantine",
       "target": "test-device",
       "reason": "Testing approval workflow",
       "requester": "Test User"
     }'

2. Check email for approval request

3. Click approve/deny link

4. Verify case note was added

Troubleshooting

Email Not Received

1. Check SMTP settings are correct
2. Verify email address format
3. Check spam/junk folder
4. Test SMTP connection:

   telnet smtp.gmail.com 587

Approval Link Not Working

1. Verify base_url is correct
2. Check token hasn't expired
3. Ensure HTTPS is being used
4. Check server logs for errors

Status Stuck on Pending

1. Check approval hasn't expired
2. Verify database connection
3. Check WebSocket connection
4. Review server logs

Future Enhancements

• Slack integration
• Mobile app notifications
• Multi-level approval
• Approval delegation
• Risk-based auto-approval
• Approval analytics dashboard

Support

For issues or questions:

• GitHub: https://github.com/hawkdefense/hawk-soar-cloud-v3
• Email: [email protected]
• Documentation: https://docs.hawk.io

License

Copyright © 2026 HAWK Defense. All rights reserved.