Attacks with rule hits

GET

/analytics/security/attacks

const url = 'https://api.nsin.ir/analytics/security/attacks?domain=example.com';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.nsin.ir/analytics/security/attacks?domain=example.com' \
  --header 'Authorization: Bearer <token>'

The 50 newest attacks on the domain, each with how often its rule acted (rule_hits, enforced and dry run).

Authorizations

bearerAuth
apiKeyAuth

Parameters

Query Parameters

domain

required

string

The domain name (for example example.com). These endpoints take the domain as a query parameter rather than a path segment.

Example

example.com

Responses

200

The figures.

application/json

object

available

False when rule hits cannot be read yet (they are then zeros).

boolean

attacks

Array

object

integer

domain_id

integer

domain_name

string

status

string

Allowed values: detected mitigating ended ignored

kind

volume: a flood, far more requests than usual. behaviour: the traffic suddenly behaves differently (for example no CSS/JS/image requests, no cookies, one HTTP version only), even at normal volume. A behaviour attack ends after 30 minutes without the change.

string

Allowed values: volume behaviour

drift

What changed (behaviour attacks; empty for floods), strongest first, at most 8.

Array<object>

object

feature

string

Allowed values: asset html api no_referer no_cookie many_cookie s2 s3 s4 s404 s5 post other_method h1 h2 h3 bot_low bot_high req_per_path req_per_ip

group

string

Allowed values: assets cookies status protocol bot paths ips

unit

share: 0–1 of requests. ratio: requests per path or per IP.

string

Allowed values: share ratio

normal

The usual value at this hour of day.

number

now

The value during the attack.

number

How unusual the change is (larger = stronger).

number

started_at

string format: date-time

ended_at

string format: date-time

nullable

calm_since

string format: date-time

nullable

peak_rpm

Highest requests per minute seen.

integer

baseline_rpm

Usual requests per minute for this hour of day.

number

signature

object

features

Array<object>

object

field

string

Allowed values: ja4h ja4 user_agent cookie header_set_hash path method asn country

key

The cookie name for cookie; else empty.

string

value

string

coverage

Share of the attack’s requests with this value (0–1).

number

baseline_share

Share of normal requests with this value (0–1).

number

expression

The rule’s conditions as text; empty without a rule.

string

attack_requests

integer

baseline_requests

integer

baseline_window

reference_day: the same time on the most normal recent day (behaviour attacks).

string

Allowed values: hour_before day_before reference_day none

coverage

Share of the attack the rule matches.

number

fp_estimate

Share of normal requests the rule would have hit; -1 = unknown.

number

rule_id

integer

nullable

rule

object

integer

name

string

enabled

boolean

action_mode

string

Allowed values: enforce dry_run

enforced_by

"", “user:” or “admin:”.

string

note

string

created_at

string format: date-time

updated_at

string format: date-time

rule_hits

object

enforced

integer

dry_run

integer

Example

{
  "attacks": [
    {
      "status": "detected",
      "kind": "volume",
      "drift": [
        {
          "feature": "asset",
          "group": "assets",
          "unit": "share"
        }
      ],
      "signature": {
        "features": [
          {
            "field": "ja4h"
          }
        ],
        "baseline_window": "hour_before"
      },
      "rule": {
        "action_mode": "enforce"
      }
    }
  ]
}

400

The domain query parameter is missing.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

missing

{
  "error": "domain is required"
}

401

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

402

The domain has no active plan at all, so no plan feature is available on it. Buy or renew a plan for the domain. (A plan that is active but does not include the feature answers 403 instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

noPlan

{
  "error": "This domain does not have an active plan."
}

403

The domain’s plan does not include the feature this endpoint needs (monitoring for most sections, logs for raw and top-N request data).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}

503

Either the analytics backend is temporarily unreachable (retry; no data is lost), or the answer is still being computed. The per-domain sections and the cached account-wide views (domains-overview, global-summary, global-summary/peak, requests-compare, bandwidth-overview, nodes-overview) wait at most about 25 seconds for their query; past that they answer 503 with pending: true and a Retry-After header, while the query keeps running and caches its result, so the retry is served from that cache instead of starting the same scan again. Identical concurrent requests share one computation.

application/json

object

error

required

Human-readable description of what went wrong.

string

pending

true when the query is still running rather than failing. Retry after Retry-After seconds.

boolean

Examples

{
  "error": "analytics unavailable"
}

{
  "error": "still computing — try again in a few seconds",
  "pending": true
}

Headers

Retry-After

integer

Example

Seconds to wait before retrying. Sent only with pending.

504

The query ran out of time for this period. Retrying the same request runs the same query again, so ask for a shorter period (or narrow it with hostname/path) instead.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

timedOut

{
  "error": "summary timed out for this period; try a shorter one"
}