Skip to main content

ipscanner/types/
agentscan.rs

1use std::collections::HashMap;
2
3use serde::{Deserialize, Serialize};
4use serde_json::{Map, Value};
5
6use super::{AsnResponse, GeolocationResponse};
7
8/// Body of `POST /v1/agentscan/check`.
9#[derive(Debug, Clone, Default, PartialEq, Serialize)]
10pub struct AgentCheckRequest {
11    pub ip: String,
12    #[serde(skip_serializing_if = "Option::is_none")]
13    pub user_agent: Option<String>,
14    #[serde(skip_serializing_if = "Option::is_none")]
15    pub ja4: Option<String>,
16    #[serde(skip_serializing_if = "Option::is_none")]
17    pub headers: Option<HashMap<String, String>>,
18    #[serde(skip_serializing_if = "Option::is_none")]
19    pub headless_flags: Option<HashMap<String, bool>>,
20    #[serde(skip_serializing_if = "Option::is_none")]
21    pub request_id: Option<String>,
22}
23
24impl AgentCheckRequest {
25    pub fn new(ip: impl Into<String>) -> Self {
26        AgentCheckRequest {
27            ip: ip.into(),
28            ..Default::default()
29        }
30    }
31}
32
33/// Response of `POST /v1/agentscan/check`.
34#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
35#[serde(default, rename_all = "camelCase")]
36pub struct AgentCheck {
37    /// `human`, `known_bot`, `ai_agent` or `malicious_automation`.
38    pub class: String,
39    pub confidence: f64,
40    /// `allow`, `flag` or `block`.
41    pub action: String,
42    pub signals: Map<String, Value>,
43}
44
45/// One log line for `POST /v1/agentscan/batch`.
46#[derive(Debug, Clone, Default, PartialEq, Serialize)]
47pub struct AgentBatchLine {
48    pub line: i64,
49    pub ip: String,
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub user_agent: Option<String>,
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub ja4: Option<String>,
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub headers: Option<HashMap<String, String>>,
56}
57
58impl AgentBatchLine {
59    pub fn new(line: i64, ip: impl Into<String>) -> Self {
60        AgentBatchLine {
61            line,
62            ip: ip.into(),
63            ..Default::default()
64        }
65    }
66}
67
68/// Response of `POST /v1/agentscan/batch`.
69#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
70#[serde(default, rename_all = "camelCase")]
71pub struct AgentBatch {
72    pub submitted: i64,
73    pub processed: i64,
74    pub failed: i64,
75    pub truncated: bool,
76    /// Empty, or `quota_exceeded` when the batch was cut short.
77    pub reason: String,
78    pub by_class: HashMap<String, i64>,
79    pub results: Vec<AgentBatchResult>,
80    pub as_of: String,
81}
82
83/// One classified line of a batch.
84#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
85#[serde(default, rename_all = "camelCase")]
86pub struct AgentBatchResult {
87    pub line: i64,
88    pub ip: String,
89    pub user_agent: Option<String>,
90    pub class: Option<String>,
91    pub confidence: Option<f64>,
92    pub action: Option<String>,
93    pub signals: Option<Map<String, Value>>,
94    pub error: Option<String>,
95}
96
97/// Body of `POST /v1/agentscan/verify`. Set `bot` or `user_agent`.
98#[derive(Debug, Clone, Default, PartialEq, Serialize)]
99pub struct CrawlerVerifyRequest {
100    pub ip: String,
101    #[serde(skip_serializing_if = "Option::is_none")]
102    pub bot: Option<String>,
103    #[serde(skip_serializing_if = "Option::is_none")]
104    pub user_agent: Option<String>,
105}
106
107impl CrawlerVerifyRequest {
108    /// Verify `ip` against a crawler slug such as `googlebot`.
109    pub fn bot(ip: impl Into<String>, bot: impl Into<String>) -> Self {
110        CrawlerVerifyRequest {
111            ip: ip.into(),
112            bot: Some(bot.into()),
113            user_agent: None,
114        }
115    }
116
117    /// Verify `ip` against the crawler named in a User-Agent string.
118    pub fn user_agent(ip: impl Into<String>, user_agent: impl Into<String>) -> Self {
119        CrawlerVerifyRequest {
120            ip: ip.into(),
121            bot: None,
122            user_agent: Some(user_agent.into()),
123        }
124    }
125}
126
127/// Response of `POST /v1/agentscan/verify`.
128#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
129#[serde(default, rename_all = "camelCase")]
130pub struct CrawlerVerification {
131    pub ip: String,
132    pub slug: String,
133    pub crawler: String,
134    pub user_agent: Option<String>,
135    /// `verified`, `spoofed` or `unverifiable`.
136    pub outcome: String,
137    pub method: String,
138    pub summary: String,
139    pub checks: Vec<VerifyCheck>,
140    pub network_origin: String,
141    pub anonymized: bool,
142    pub asn: Option<String>,
143    pub asn_name: Option<String>,
144    pub country: Option<String>,
145    pub hostname: Option<String>,
146    pub docs: Option<String>,
147    pub checked_at: String,
148}
149
150/// One check behind a crawler verification.
151#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
152#[serde(default, rename_all = "camelCase")]
153pub struct VerifyCheck {
154    pub name: String,
155    pub status: String,
156    pub detail: String,
157}
158
159/// One entry of `GET /v1/agentscan/allowlist`.
160#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
161#[serde(default, rename_all = "camelCase")]
162pub struct AllowlistAgent {
163    pub id: i64,
164    pub ident: String,
165    /// `search`, `ai_crawler` or `partner`.
166    #[serde(rename = "type")]
167    pub kind: String,
168    pub verification_method: String,
169    pub customer_id: Option<i64>,
170    pub created_at: String,
171}
172
173#[derive(Debug, Default, Deserialize)]
174#[serde(default)]
175pub(crate) struct Allowlist {
176    pub agents: Vec<AllowlistAgent>,
177}
178
179/// Body of `POST /v1/agentscan/self`. Every field is optional.
180#[derive(Debug, Clone, Default, PartialEq, Serialize)]
181pub struct AgentSelfRequest {
182    #[serde(skip_serializing_if = "Option::is_none")]
183    pub ip: Option<String>,
184    #[serde(skip_serializing_if = "Option::is_none")]
185    pub user_agent: Option<String>,
186    #[serde(skip_serializing_if = "Option::is_none")]
187    pub headers: Option<HashMap<String, String>>,
188    #[serde(skip_serializing_if = "Option::is_none")]
189    pub ja4: Option<String>,
190}
191
192/// Response of `POST /v1/agentscan/self`.
193#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
194#[serde(default, rename_all = "camelCase")]
195pub struct AgentSelfCheck {
196    pub ip: String,
197    pub user_agent: String,
198    pub ja4: String,
199    /// `edge`, `client` or `unavailable`.
200    pub ja4_source: String,
201    pub class: String,
202    pub confidence: f64,
203    pub action: String,
204    pub signals: Map<String, Value>,
205    pub metered: bool,
206    pub as_of: String,
207    pub asn: Option<AsnResponse>,
208    pub geo: Option<GeolocationResponse>,
209    pub locked: Vec<String>,
210    pub plan_required: Option<String>,
211}