Create Top Threats Task

Create Top Threats Task#

Retrieve top security threats ranked by incident count, severity, or other metrics.

✅ All code examples tested: Verified against FortiAnalyzer v7.4.8, v7.6.4, v8.0.0.

Overview#

This example shows how to retrieve FortiView top threats data - useful for:

Identifying most common attack patterns and signatures
Security threat trend analysis and monitoring
Prioritizing security response based on incident frequency
Compliance reporting on threat landscape
Evaluating IPS/AV effectiveness
Threat intelligence gathering and analysis

This operation uses the two-step asynchronous pattern. See the workflow below for complete details.

Endpoint Details#

Method: POST URL: /jsonrpc API Path (Step 1): /fortiview/adom/{adom}/top-threats/run API Path (Step 2): /fortiview/adom/{adom}/top-threats/run/{tid} ADOM Support: Yes Requires Authentication: Yes Minimum Version: 7.4.0

Prerequisites#

Active session or valid API key
Read access to FortiView data in specified ADOM
IPS/AV features enabled on FortiAnalyzer and FortiGate devices
Threat logs being collected

Two-Step Workflow#

Step 1: Submit Task#

Submit the top threats query and receive a Task ID (TID).

Step 2: Fetch Results#

Poll using the TID until complete, then retrieve the top threats data.

Step 1: Submit Top Threats Query#

Parameters#

Parameter	Type	Required	Default	Description
`adom`	`string`	Yes	-	ADOM name (e.g., “root”)
`apiver`	`integer`	No	`3`	API version
`device`	`array`	Yes	-	Device filter specification
`filter`	`string`	No	`""`	Filter expression (e.g., threattype)
`limit`	`integer`	No	`50`	Number of top threats to return
`sort-by`	`array`	Yes	-	Sorting specification
`time-range`	`object`	Yes	-	Time range for data
`case-sensitive`	`boolean`	No	`false`	Filter case sensitivity

Device Filter#

Parameter	Type	Required	Description
`└─ devid`	`string`	Yes	Device ID or “All_Devices”

Sort Configuration#

Parameter	Type	Description
`└─ field`	`string`	Field to sort by: `incidents`, `severity`
`└─ order`	`string`	Sort order: `asc` or `desc`

Time Range Format#

Parameter	Type	Required	Description
`└─ start`	`string`	Yes	Start time: “YYYY-MM-DD HH:MM:SS”
`└─ end`	`string`	Yes	End time: “YYYY-MM-DD HH:MM:SS”

Common Filter Examples#

threattype=ips - IPS threats only
threattype=virus - Malware/virus threats
threattype=botnet - Botnet activity
severity=critical - Critical severity only

Request Example#

REQUEST

{
    "method": "add",
    "params": [{
        "url": "/fortiview/adom/root/top-threats/run",
        "apiver": 3,
        "case-sensitive": false,
        "device": [{
            "devid": "All_Devices"
        }],
        "filter": "threattype=ips",
        "limit": 50,
        "sort-by": [{
            "field": "incidents",
            "order": "desc"
        }],
        "time-range": {
            "start": "2025-11-09 00:00:00",
            "end": "2025-11-09 23:59:59"
        }
    }],
    "session": "{{session_id}}",
    "id": 1
}

RESPONSE

{
    "result": [{
        "data": {
            "tid": 12460
        },
        "status": {
            "code": 0,
            "message": "OK"
        }
    }]
}

Step 2: Fetch Results#

Parameters#

Parameter	Type	Required	Default	Description
`adom`	`string`	Yes	-	ADOM name (same as Step 1)
`tid`	`integer`	Yes	-	Task ID from Step 1
`limit`	`integer`	No	`100`	Results per page
`offset`	`integer`	No	`0`	Starting position for pagination

Request Example#

REQUEST

{
    "method": "get",
    "params": [{
        "url": "/fortiview/adom/root/top-threats/run/12460",
        "data": {
            "limit": 100,
            "offset": 0
        }
    }],
    "session": "{{session_id}}",
    "id": 2
}

RESPONSE

{
    "result": [{
        "data": {
            "tid": 12460,
            "status": "done",
            "percentage": 100,
            "total": 25,
            "threats": [
                {
                    "threat": "SQL.Injection",
                    "threattype": "ips",
                    "severity": "critical",
                    "incidents": 1523,
                    "sources": 15,
                    "destinations": 3,
                    "blocked": 1523,
                    "detected": 0
                },
                {
                    "threat": "XSS.Generic",
                    "threattype": "ips",
                    "severity": "high",
                    "incidents": 892,
                    "sources": 8,
                    "destinations": 2,
                    "blocked": 892,
                    "detected": 0
                },
                {
                    "threat": "Botnet.CnC.Generic",
                    "threattype": "ips",
                    "severity": "critical",
                    "incidents": 456,
                    "sources": 3,
                    "destinations": 12,
                    "blocked": 456,
                    "detected": 0
                }
            ]
        },
        "status": {
            "code": 0,
            "message": "OK"
        }
    }]
}

Response Fields#

Field	Type	Description
`tid`	`integer`	Task ID
`status`	`string`	Task status: “done”, “running”, “error”
`percentage`	`integer`	Completion percentage (0-100)
`total`	`integer`	Total number of threats returned
`threats`	`array`	Array of top threat objects

Threat Object Fields#

Field	Type	Description
`threat`	`string`	Threat signature name
`threattype`	`string`	Threat type: ips, virus, botnet
`severity`	`string`	Severity level: critical, high, medium, low
`incidents`	`integer`	Number of incidents
`sources`	`integer`	Number of unique source IPs
`destinations`	`integer`	Number of unique destination IPs
`blocked`	`integer`	Number of blocked incidents
`detected`	`integer`	Number of detected (not blocked) incidents

Complete Python Example#

import json
import requests
import urllib3
import time

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

def get_top_threats(session_id, adom, time_range, limit=50, threat_type="ips"):
    """
    Get top security threats for a time period

    Args:
        session_id: Active session ID
        adom: ADOM name
        time_range: Time range dict with 'start' and 'end'
        limit: Number of top threats to return (default: 50)
        threat_type: Threat type filter: ips, virus, botnet

    Returns:
        list: Top threats data
    """
    url = "https://faz.example.com/jsonrpc"

    # Step 1: Submit task
    payload = {
        "method": "add",
        "params": [{
            "url": f"/fortiview/adom/{adom}/top-threats/run",
            "apiver": 3,
            "case-sensitive": False,
            "device": [{"devid": "All_Devices"}],
            "filter": f"threattype={threat_type}",
            "limit": limit,
            "sort-by": [{
                "field": "incidents",
                "order": "desc"
            }],
            "time-range": time_range
        }],
        "session": session_id,
        "id": 1
    }

    response = requests.post(url, json=payload, verify=False)
    result = response.json()

    tid = result['result'][0]['data']['tid']
    print(f"✓ Task submitted. TID: {tid}")

    # Step 2: Poll for completion
    while True:
        poll_payload = {
            "method": "get",
            "params": [{
                "url": f"/fortiview/adom/{adom}/top-threats/run/{tid}"
            }],
            "session": session_id,
            "id": 2
        }

        response = requests.post(url, json=poll_payload, verify=False)
        data = response.json()['result'][0]['data']

        if data['status'] == 'done' and data['percentage'] == 100:
            print(f"✓ Found {data['total']} top threats")
            return data.get('threats', [])

        time.sleep(2)

# Example: Get top IPS threats
threats = get_top_threats(
    session_id="your_session_id",
    adom="root",
    time_range={
        "start": "2025-11-09 00:00:00",
        "end": "2025-11-09 23:59:59"
    },
    limit=50,
    threat_type="ips"
)

# Display results
print("\nTop IPS Threats by Incident Count:")
for i, threat in enumerate(threats[:10], 1):
    print(f"{i}. {threat['threat']}")
    print(f"   Severity: {threat['severity']}")
    print(f"   Incidents: {threat['incidents']:,}")
    print(f"   Sources: {threat['sources']}, Destinations: {threat['destinations']}")
    print(f"   Blocked: {threat['blocked']:,}, Detected: {threat['detected']:,}")
    print()

Use Cases#

Critical Threat Monitoring#

# Get critical severity threats only
threats = get_top_threats(
    session_id=session,
    adom="root",
    time_range={"last-n-hours": 24},
    limit=100,
    threat_type="ips"
)

# Filter for critical threats
critical = [t for t in threats if t['severity'] == 'critical']

if critical:
    print(f"⚠️ {len(critical)} critical threats detected:")
    for threat in critical[:5]:
        print(f"  {threat['threat']}: {threat['incidents']:,} incidents")

Threat Type Comparison#

# Compare different threat types
threat_types = ['ips', 'virus', 'botnet']
threat_summary = {}

for ttype in threat_types:
    threats = get_top_threats(
        session_id=session,
        adom="root",
        time_range={"last-n-hours": 24},
        limit=100,
        threat_type=ttype
    )

    total_incidents = sum(t['incidents'] for t in threats)
    threat_summary[ttype] = {
        'count': len(threats),
        'incidents': total_incidents
    }

# Display comparison
print("Threat Landscape Summary:\n")
for ttype, data in sorted(threat_summary.items(), key=lambda x: x[1]['incidents'], reverse=True):
    print(f"{ttype.upper()}: {data['count']} threats, {data['incidents']:,} incidents")

IPS Effectiveness Analysis#

# Analyze IPS block rate
threats = get_top_threats(
    session_id=session,
    adom="root",
    time_range={
        "start": "2025-11-09 00:00:00",
        "end": "2025-11-09 23:59:59"
    },
    limit=100,
    threat_type="ips"
)

total_incidents = sum(t['incidents'] for t in threats)
total_blocked = sum(t['blocked'] for t in threats)
total_detected = sum(t['detected'] for t in threats)

block_rate = (total_blocked / total_incidents * 100) if total_incidents > 0 else 0

print(f"IPS Effectiveness Report:")
print(f"  Total Incidents: {total_incidents:,}")
print(f"  Blocked: {total_blocked:,}")
print(f"  Detected Only: {total_detected:,}")
print(f"  Block Rate: {block_rate:.2f}%")

Threat Intelligence Report#

# Generate comprehensive threat intelligence report
threats = get_top_threats(
    session_id=session,
    adom="root",
    time_range={"last-n-days": 7},
    limit=50,
    threat_type="ips"
)

print("=" * 80)
print("WEEKLY THREAT INTELLIGENCE REPORT")
print("=" * 80)
print(f"{'Rank':<6} {'Threat':<40} {'Severity':<10} {'Incidents':>12}")
print("-" * 80)

for i, threat in enumerate(threats, 1):
    severity_icon = {
        'critical': '🔴',
        'high': '🟠',
        'medium': '🟡',
        'low': '🟢'
    }.get(threat['severity'], '⚪')

    print(f"{i:<6} {threat['threat']:<40} {severity_icon} {threat['severity']:<8} {threat['incidents']:>12,}")

# Top threat details
if threats:
    top_threat = threats[0]
    print("\n" + "=" * 80)
    print(f"TOP THREAT: {top_threat['threat']}")
    print("=" * 80)
    print(f"Type: {top_threat['threattype'].upper()}")
    print(f"Severity: {top_threat['severity'].upper()}")
    print(f"Total Incidents: {top_threat['incidents']:,}")
    print(f"Unique Sources: {top_threat['sources']}")
    print(f"Unique Destinations: {top_threat['destinations']}")
    print(f"Blocked: {top_threat['blocked']:,} ({top_threat['blocked']/top_threat['incidents']*100:.1f}%)")

Error Handling#

ERROR RESPONSE

{
    "result": [{
        "status": {
            "code": -3,
            "message": "Invalid task ID"
        }
    }]
}

Common causes:

Task ID has expired
Invalid TID value
FortiView data not available for time range
IPS/AV not enabled
Insufficient permissions

Best Practices#

💡 Tip: Focus on critical and high severity threats first for security response prioritization.

💡 Tip: Compare blocked vs. detected ratios to evaluate IPS policy effectiveness.

⚠️ Warning: High incident counts for specific threats may indicate targeted attacks or misconfigurations.

💡 Tip: Use longer time ranges (7-30 days) for trend analysis, shorter ranges (1-24 hours) for incident response.

Threat Severity Levels#

Severity	Description	Recommended Action
Critical	Immediate threat to security	Immediate investigation and response required
High	Significant security risk	Investigate within 24 hours
Medium	Moderate security concern	Review and address within 48 hours
Low	Minor security issue	Monitor and review periodically

Create Top Threats Task

On this page

Create Top Threats Task#

Overview#

Endpoint Details#

Prerequisites#

Two-Step Workflow#

Step 1: Submit Task#

Step 2: Fetch Results#

Step 1: Submit Top Threats Query#

Parameters#

Device Filter#

Sort Configuration#

Time Range Format#

Common Filter Examples#

Request Example#

Step 2: Fetch Results#

Parameters#

Request Example#

Response Fields#

Threat Object Fields#

Complete Python Example#

Use Cases#

Critical Threat Monitoring#

Threat Type Comparison#

IPS Effectiveness Analysis#

Threat Intelligence Report#

Error Handling#

Best Practices#

Threat Severity Levels#

Related Endpoints#