feat(server): unify scan target param on target, keep url as REST alias

The scan target was named inconsistently across surfaces: the MCP
`scan_with_dalfox` tool and every response payload (`ResultPayload.target`,
the submit `{scan_id, target}`) used `target`, but the REST request body and
query string used `url`. Anyone wiring up both surfaces hit the mismatch.

Standardize on `target` and keep `url` working for existing REST clients:
- `ScanRequest.url` → `target` with `#[serde(alias = "url")]`, so POST `/scan`
  and POST `/preflight` accept `{"target": ...}` (canonical) or `{"url": ...}`.
- GET `/scan` reads the `target` query param, falling back to `url`.
- MCP already used `target` — unchanged.

Backwards compatible: every existing client sending `url` (JSON body or query
string) keeps working; responses are unchanged.

Verified end-to-end against a live server: POST/GET with `target` and with the
`url` alias all return a scan_id, `/preflight` with `target` works, and a body
with neither field is a 400. Docs (integrations/server.md) updated to show
`target` with the alias noted; added serde-alias + GET-`target` unit tests.

Author: hahwul

docs/content/integrations/server.md

@@ -51,15 +51,15 @@ For browser clients that can't set custom headers:
 
 ```bash
 dalfox server --jsonp --callback-param-name callback
-# then GET /scan?url=...&callback=myFunction
+# then GET /scan?target=...&callback=myFunction
 ```
 
 ## Endpoints
 
 | Method | Path | What it does |
 |--------|------|--------------|
 | `POST` | `/scan` | Submit a new scan (JSON body) |
-| `GET` | `/scan?url=...` | Submit a new scan (query string) |
+| `GET` | `/scan?target=...` | Submit a new scan (query string) |
 | `GET` | `/scan/:id` | Get scan status and results |
 | `DELETE` | `/scan/:id` | Cancel a queued or running scan |
 | `GET` | `/scans` | List all scans (optional `?status=`) |
@@ -74,7 +74,7 @@ curl -X POST http://127.0.0.1:6664/scan \
   -H "X-API-KEY: change-me" \
   -H "Content-Type: application/json" \
   -d '{
-    "url": "https://target.app?q=test",
+    "target": "https://target.app?q=test",
     "options": {
       "worker": 50,
       "timeout": 10,
@@ -84,6 +84,8 @@ curl -X POST http://127.0.0.1:6664/scan \
   }'
 ```
 
+The scan target field is `target` (matching the MCP `scan_with_dalfox` tool and the response payload). The legacy field name `url` is still accepted as an alias — for both the JSON body and the `?target=` / `?url=` query string — so existing clients keep working.
+
 Response:
 
 ```json

src/server/handlers.rs

@@ -41,7 +41,7 @@ pub(crate) async fn start_scan_handler(
 
     // Trim once and use the trimmed value throughout (validation, scan_id,
     // stored target, dispatch) so whitespace variants stay consistent.
-    let url = req.url.trim().to_string();
+    let url = req.target.trim().to_string();
     if url.is_empty() {
         let resp = ApiResponse::<serde_json::Value> {
             code: 400,
@@ -257,8 +257,11 @@ pub(crate) async fn get_scan_handler(
     // Trim once and use the trimmed value throughout, so whitespace variants
     // of the same URL validate, hash to the same scan_id, and store the same
     // target consistently.
+    // `target` is the canonical param (matches POST/MCP); `url` stays as a
+    // backwards-compatible alias for existing query-string / JSONP callers.
     let url = params
-        .get("url")
+        .get("target")
+        .or_else(|| params.get("url"))
         .cloned()
         .unwrap_or_default()
         .trim()
@@ -767,7 +770,7 @@ pub(crate) async fn preflight_handler(
         }
     };
 
-    let target_url = req.url.trim().to_string();
+    let target_url = req.target.trim().to_string();
     if target_url.is_empty() || !has_http_scheme(&target_url) {
         let resp = ApiResponse::<serde_json::Value> {
             code: 400,

src/server/tests.rs

@@ -656,7 +656,7 @@ async fn test_start_scan_handler_unauthorized_and_bad_request_jsonp() {
         HeaderMap::new(),
         Query(params_auth),
         Ok(Json(ScanRequest {
-            url: "http://example.com".to_string(),
+            target: "http://example.com".to_string(),
             options: None,
         })),
     )
@@ -674,7 +674,7 @@ async fn test_start_scan_handler_unauthorized_and_bad_request_jsonp() {
         HeaderMap::new(),
         Query(params_bad_req),
         Ok(Json(ScanRequest {
-            url: "   ".to_string(),
+            target: "   ".to_string(),
             options: None,
         })),
     )
@@ -693,7 +693,7 @@ async fn test_start_scan_handler_success_creates_queued_job() {
         HeaderMap::new(),
         Query(Map::new()),
         Ok(Json(ScanRequest {
-            url: "http://127.0.0.1:1/".to_string(),
+            target: "http://127.0.0.1:1/".to_string(),
             options: Some(ScanOptions {
                 include_request: Some(true),
                 include_response: Some(true),
@@ -738,7 +738,7 @@ async fn test_start_scan_handler_success_jsonp_response() {
         HeaderMap::new(),
         Query(q),
         Ok(Json(ScanRequest {
-            url: "http://127.0.0.1:1/".to_string(),
+            target: "http://127.0.0.1:1/".to_string(),
             options: None,
         })),
     )
@@ -1631,7 +1631,7 @@ async fn test_preflight_handler_rejects_invalid_url() {
         HeaderMap::new(),
         Query(Map::new()),
         Ok(Json(ScanRequest {
-            url: "not-http".to_string(),
+            target: "not-http".to_string(),
             options: None,
         })),
     )
@@ -1648,7 +1648,7 @@ async fn test_preflight_handler_requires_auth() {
         HeaderMap::new(),
         Query(Map::new()),
         Ok(Json(ScanRequest {
-            url: "http://example.com".to_string(),
+            target: "http://example.com".to_string(),
             options: None,
         })),
     )
@@ -1665,7 +1665,7 @@ async fn test_preflight_handler_unreachable_target() {
         HeaderMap::new(),
         Query(Map::new()),
         Ok(Json(ScanRequest {
-            url: "http://127.0.0.1:1/unreachable".to_string(),
+            target: "http://127.0.0.1:1/unreachable".to_string(),
             options: Some(ScanOptions {
                 timeout: Some(1),
                 ..ScanOptions::default()
@@ -1791,7 +1791,7 @@ async fn test_start_scan_handler_rejects_out_of_range_timeout() {
         HeaderMap::new(),
         Query(Map::new()),
         Ok(Json(ScanRequest {
-            url: "http://example.com".to_string(),
+            target: "http://example.com".to_string(),
             options: Some(ScanOptions {
                 timeout: Some(9999),
                 ..ScanOptions::default()
@@ -1834,7 +1834,7 @@ async fn test_start_scan_handler_rejects_non_http_url() {
             HeaderMap::new(),
             Query(Map::new()),
             Ok(Json(ScanRequest {
-                url: bad.to_string(),
+                target: bad.to_string(),
                 options: None,
             })),
         )
@@ -2570,7 +2570,7 @@ async fn test_start_scan_handler_503_when_at_capacity() {
         HeaderMap::new(),
         Query(Map::new()),
         Ok(Json(ScanRequest {
-            url: "http://example.com".to_string(),
+            target: "http://example.com".to_string(),
             options: None,
         })),
     )
@@ -2811,3 +2811,36 @@ async fn test_get_scan_handler_analyze_external_js_param_is_accepted() {
         "job must be present in the queue after handler returns"
     );
 }
+
+// Target/URL param unification: `target` is canonical (matches MCP + response),
+// `url` stays as a backwards-compatible alias on the REST surface.
+#[test]
+fn test_scan_request_accepts_target_canonical_and_url_alias() {
+    let from_target: ScanRequest =
+        serde_json::from_str(r#"{"target":"http://a.test/?q=1"}"#).expect("target key parses");
+    assert_eq!(from_target.target, "http://a.test/?q=1");
+
+    let from_url: ScanRequest =
+        serde_json::from_str(r#"{"url":"http://b.test/?q=1"}"#).expect("url alias parses");
+    assert_eq!(from_url.target, "http://b.test/?q=1");
+
+    // Neither key present is a hard error (target is required).
+    assert!(serde_json::from_str::<ScanRequest>(r#"{"options":{}}"#).is_err());
+}
+
+#[tokio::test]
+async fn test_get_scan_handler_accepts_target_query_param() {
+    let state = make_state(None, None, false, false, "cb");
+    let mut params = Map::new();
+    params.insert("target".to_string(), "http://127.0.0.1:1/?q=1".to_string());
+    let resp = get_scan_handler(State(state.clone()), HeaderMap::new(), Query(params))
+        .await
+        .into_response();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = response_body_string(resp).await;
+    let parsed: serde_json::Value = serde_json::from_str(&body).expect("json body");
+    assert!(
+        parsed["data"]["scan_id"].as_str().is_some(),
+        "a scan submitted via the `target` query param must return a scan_id"
+    );
+}

src/server/types.rs

@@ -135,7 +135,11 @@ pub(crate) struct ApiResponse<T> {
 
 #[derive(Debug, Clone, Deserialize)]
 pub(crate) struct ScanRequest {
-    pub(crate) url: String,
+    /// Scan target. Named `target` to match the MCP `scan_with_dalfox` tool and
+    /// the response payload's `target` field; `url` is accepted as a backwards-
+    /// compatible alias so existing REST clients keep working.
+    #[serde(alias = "url")]
+    pub(crate) target: String,
     #[serde(default)]
     pub(crate) options: Option<ScanOptions>,
 }