request-mock-skills

English · 简体中文 · Website source

---

request-mock-skills is a Go toolkit for mock-generating HTTP capture results. It builds HTTP requests from parameters or built-in scenario templates, produces HAR (HTTP Archive) captures, and exports them to many formats (curl, wget, python, postman, xml, yaml, har/json, jsonl, csv, markdown, html, text).

HAR construction and serialization reuse the internal har-skills library; this repo focuses on the "mock generation" domain: parameter models, scenario templates, deterministic batch derivation, transforms, splitting, and a unified export entry.

AI-friendly: usable as a Go SDK imported by downstream projects, or as a CLI invoked by AI agents. The CLI defaults to a structured JSON envelope {"ok":true,"count":N,"seed":S,"format":"json","data":"..."}; errors also go through JSON. Add --raw for raw output.

How it works

flowchart LR
    A["Parameters / Templates"] --> B["RequestSpec"]
    B --> C["Generate"]
    C --> D["*har.Har"]
    D --> E["Export"]
    E --> F["curl / wget / python"]
    E --> G["postman / xml / yaml"]
    E --> H["har / jsonl / csv"]
    E --> I["markdown / html / text"]
    D -.optional.-> J["Split / Dedup / AddHeaders"]
    J --> E

Loading

Architecture

flowchart TB
    subgraph CLI["cmd/request-mock (cobra CLI)"]
        C1[generate]
        C2[template]
        C3[batch]
        C4[split]
        C5[export]
        C6[dedup]
        C7[add-headers]
        C8[clone]
        C9[formats]
        C10[transforms]
    end

    subgraph SDK["pkg/mock (Go SDK)"]
        S1["RequestSpec model"]
        S2["Generate / GenerateOne"]
        S3["Generator / GenerateSpecs"]
        S4["Transform (16 built-in)"]
        S5["Templates (15 built-in)"]
        S6["Config / LoadConfig"]
        S7["Export / ExportToFile"]
        S8["Split / Deduplicate / AddHeaders / CloneHar"]
        S9["Result JSON envelope"]
    end

    CLI --> SDK
    SDK --> HAR[("har-skills pkg/har")]
    HAR --> OUT["curl / har / postman / ..."]

Loading

Installation

go install github.com/cyberspacesec/request-mock-skills/cmd/request-mock@latest

Or build from source:

git clone https://github.com/cyberspacesec/request-mock-skills.git
cd request-mock-skills
go build -o request-mock ./cmd/request-mock

CLI usage

generate — build requests from parameters

# Default: JSON envelope (AI-friendly)
request-mock generate -X POST -u https://api.example.com/login \
  -H 'Content-Type: application/json' -H 'Authorization: Bearer token-123' \
  -d '{"username":"alice","password":"secret"}'

# Batch derivation, export as jsonl
request-mock generate -X GET -u https://api.example.com/users -n 50 --seed 42 -f jsonl

# Raw curl output (humans / pipes)
request-mock generate -X GET -u https://api.example.com/users -f curl --raw

# Export as HAR JSON
request-mock generate -X GET -u https://api.example.com/users -f har --raw

Common flags:

Flag	Description
-X, --method	HTTP method, default GET
-u, --url	Request URL (required)
-H, --header	Request header, repeatable, Name: Value
--cookie	Request cookie, repeatable, name=value
-Q, --query	Query parameter, repeatable, name=value
-d, --data	Request body (defaults to application/json)
--data-raw	Raw body, pair with --post-mime
-F, --form	Form param, repeatable (application/x-www-form-urlencoded)
--status / --status-text	Mock response status / text
--resp-body / --resp-mime / --resp-header	Mock response content
--server-ip	Mock server IP
-f, --format	Export format, default json (AI-friendly envelope)
-o, --output	Output file, default stdout
--raw	Raw output (no JSON envelope)
--creator / --browser	HAR creator/browser metadata
-n, --count	Batch derivation count (>1 triggers seed-based randomization)
--seed	Deterministic random seed
--transform	Transform names to enable, repeatable

template — built-in scenario templates

request-mock template --list                       # list all templates
request-mock template --name login -f curl         # use login template
request-mock template --name postjson --url https://api.example.com/users -f har

Built-in templates: getjson, postjson, postform, login, upload, bearer, delete, put, patch, head, options, banner, redirect, error, portscan.

batch — config-driven bulk generation

request-mock batch --config examples/config/batch.yaml -o out.curl
request-mock batch --config examples/config/batch.yaml -n 100 --seed 42 -f har -o out.har

Config example (full version at examples/config/batch.yaml):

seed: 42            # deterministic seed: same seed + same input → same output
count: 10           # samples derived per base spec
templates:          # reference built-in templates (url/headers overridable)
  - name: getjson
    url: https://api.example.com/users
  - name: login
    url: https://api.example.com/login
transforms:         # transform rules; ["none"] disables all
  - server_ip
  - user_agent
  - path
  - query_noise
export:
  format: curl

split — split HAR by dimension

request-mock split --input out.har --by method -o parts/
request-mock split --input out.har --by size --size 10 -o parts/

Dimensions: page · domain · status · method · size · time.

export / dedup / add-headers / clone — HAR post-processing

request-mock export --input out.har -f curl --raw        # convert HAR → other format
request-mock dedup --input out.har -o dedup.har          # remove duplicate entries
request-mock add-headers --input out.har -H 'X-Test: 1' --target request   # batch add headers
request-mock clone --input out.har -o copy.har           # deep-copy a HAR
request-mock formats                                     # list export formats
request-mock transforms                                  # list built-in transforms

Supported export formats

curl · wget · python · postman · xml · yaml · har/json · jsonl · csv · markdown · html · text

Transform pipeline

Each transform mutates a derived RequestSpec. Transforms compose in sequence:

flowchart LR
    Base["Base RequestSpec"] --> T1["server_ip"]
    T1 --> T2["user_agent"]
    T2 --> T3["path"]
    T3 --> T4["query_noise"]
    T4 --> T5["status / timings"]
    T5 --> Out["Derived spec #N"]
    style Base fill:#e1f5ff
    style Out fill:#e8f5e9

Loading

Built-in transforms (16): server_ip, user_agent, path, query_noise, status, timings, index, port, host, resp_cookie, header, body_noise, seq_status, priority, resource_type, connection.

SDK usage

package main

import (
    "fmt"

    "github.com/cyberspacesec/request-mock-skills/pkg/mock"
)

func main() {
    spec := mock.Login("https://api.example.com/login", "alice", "secret")
    h, _ := mock.GenerateOne(spec)

    curl, _ := mock.Export(h, mock.FormatCurl)
    fmt.Println(curl)
}

Batch generation (SDK)

base := mock.GETJSON("https://api.example.com/users")
g := mock.NewGenerator(42)                     // deterministic seed
specs := g.GenerateSpecs(base, 100)            // derive 100 variants
h, _ := mock.Generate(specs)
curl, _ := mock.Export(h, mock.FormatCurl)
fmt.Println(curl)

Full examples: examples/quickstart · examples/batch. See also SDK guide and API reference.

Project structure

flowchart TB
    Root["request-mock-skills"] --> Cmd["cmd/request-mock"]
    Root --> Pkg["pkg/mock"]
    Root --> Examples["examples/"]
    Root --> Docs["docs/"]
    Root --> Website["website/"]

    Cmd --> Main["main.go (cobra subcommands)"]
    Pkg --> Request["request.go (RequestSpec)"]
    Pkg --> Builder["builder.go (Generate)"]
    Pkg --> Batch["batch.go (Generator)"]
    Pkg --> Transform["transform.go (16 transforms)"]
    Pkg --> Template["template.go (15 templates)"]
    Pkg --> Config["config.go (YAML/JSON)"]
    Pkg --> Export["export.go + export_ext.go"]
    Pkg --> Split["export_ext.go (Split/Dedup/AddHeaders)"]
    Pkg --> Conv["convenience.go"]
    Pkg --> Result["result.go (JSON envelope)"]

Loading

Documentation

• Vision
• Architecture
• SDK guide
• API reference
• Website source

License

See LICENSE.