Firewall Log Data API

The Firewall Log Data API provides comprehensive access to firewall logs, traffic analysis, and security event data through Cognix's log analysis infrastructure.

---

Getting Started

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Please contact support at cognix.au/contact-us to obtain an API key.

---

API Reference

1. Log Query API

Query and analyze firewall log data.

Endpoint: GET https://api.cognix.au/v1/firewall/logs

Query Parameters

Parameter	Type	Required	Description
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD
source_ip	string	No	Source IP address filter
dest_ip	string	No	Destination IP address filter
action	string	No	Firewall action (allow, deny, drop)
limit	integer	No	Number of results (default: 1000)

Example Response

{
  "status": "success",
  "data": {
    "logs": [
      {
        "timestamp": "2024-01-31T15:45:00Z",
        "source_ip": "192.168.1.100",
        "source_port": 54321,
        "dest_ip": "203.0.113.1",
        "dest_port": 443,
        "protocol": "TCP",
        "action": "deny",
        "rule_id": "FW_RULE_123",
        "bytes_transferred": 0,
        "session_duration": 0,
        "threat_level": "medium",
        "category": "suspicious_traffic"
      }
    ],
    "summary": {
      "total_logs": 15000,
      "filtered_logs": 1000,
      "unique_sources": 45,
      "unique_destinations": 23
    }
  }
}

---

2. Security Events API

Retrieve security events and alerts from firewall logs.

Endpoint: GET https://api.cognix.au/v1/firewall/events

Query Parameters

Parameter	Type	Required	Description
severity	string	No	Minimum severity level
event_type	string	No	Type of security event
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD

Example Response

{
  "status": "success",
  "data": {
    "events": [
      {
        "event_id": "EVENT_123",
        "timestamp": "2024-01-31T15:45:00Z",
        "severity": "high",
        "event_type": "brute_force_attempt",
        "source_ip": "192.168.1.100",
        "target_ip": "203.0.113.1",
        "details": {
          "attempts": 50,
          "timeframe": "5 minutes",
          "blocked_status": true
        },
        "related_rules": ["FW_RULE_123", "FW_RULE_124"]
      }
    ],
    "summary": {
      "total_events": 250,
      "by_severity": {
        "high": 25,
        "medium": 75,
        "low": 150
      }
    }
  }
}

---

3. Traffic Analysis API

Analyze traffic patterns and trends from firewall logs.

Endpoint: GET https://api.cognix.au/v1/firewall/traffic

Query Parameters

Parameter	Type	Required	Description
metric	string	Yes	Traffic metric (bandwidth, sessions, etc)
interval	string	No	Time interval (1m, 5m, 1h, 1d)
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD

Example Response

{
  "status": "success",
  "data": {
    "traffic_analysis": {
      "time_series": [
        {
          "timestamp": "2024-01-31T15:00:00Z",
          "metrics": {
            "total_bytes": 1500000,
            "total_packets": 15000,
            "active_sessions": 250
          },
          "by_protocol": {
            "TCP": 75,
            "UDP": 20,
            "ICMP": 5
          }
        }
      ],
      "top_talkers": {
        "sources": [
          {
            "ip": "192.168.1.100",
            "bytes_sent": 500000,
            "session_count": 150
          }
        ],
        "destinations": [
          {
            "ip": "203.0.113.1",
            "bytes_received": 750000,
            "session_count": 200
          }
        ]
      }
    }
  }
}

---

4. Rule Analysis API

Analyze firewall rule effectiveness and usage.

Endpoint: GET https://api.cognix.au/v1/firewall/rules/analysis

Query Parameters

Parameter	Type	Required	Description
rule_id	string	No	Specific rule identifier
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD
metrics	string	No	Specific metrics to analyze

Example Response

{
  "status": "success",
  "data": {
    "rule_analysis": {
      "rule_id": "FW_RULE_123",
      "hits": 15000,
      "effectiveness": {
        "false_positives": 150,
        "blocked_threats": 450
      },
      "performance_impact": "low",
      "recommendations": [
        {
          "type": "optimization",
          "description": "Consider combining with Rule FW_RULE_124",
          "potential_impact": "25% reduction in processing time"
        }
      ]
    }
  }
}

---

Error Handling

Response Codes

Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error occurred
503	Service Unavailable - Temporary server maintenance

Error Response Format

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context about the error",
      "suggestion": "Recommended action to resolve the error"
    }
  },
  "request_id": "unique-request-identifier"
}

Common Error Codes

Authentication Errors

Error Code	Description	Resolution
INVALID_API_KEY	The provided API key is not valid	Verify your API key in the Cognix dashboard
EXPIRED_API_KEY	The API key has expired	Generate a new API key
MISSING_API_KEY	No API key provided in the request	Include API key in Authorization header

Firewall-Specific Errors

Error Code	Description	Resolution
INVALID_DATE_RANGE	Date range format is invalid	Check date format
LOG_UNAVAILABLE	Logs for specified period not available	Verify date range
QUERY_TOO_BROAD	Query would return too many results	Add filters to narrow search
INVALID_IP	Invalid IP address format	Check IP address format

Best Practices for Error Handling

1. Always check the status field in the response
2. Implement retry logic with exponential backoff for rate limits
3. Log the request_id for all errors
4. Monitor error rates to detect potential issues
5. Handle errors gracefully in your application

---