Hướng dẫn AI

Hướng dẫn triển khai Autonomous Pentest Agent tại máy cục bộ: từ cài đặt, cấu hình đến tự động khám phá và kiểm thử lại

Bài viết giới thiệu kiến trúc cốt lõi, cách cài đặt, cấu hình LLM và PostgreSQL, theo dõi tác vụ, đồng bộ tài sản, kiểm thử lại lỗ hổng và nâng cấp Autonomous Pentest Agent, đồng thời trình bày các lưu ý về proxy ngược và phát triển cục bộ.

9 tháng 10, 2026Thời gian đọc khoảng 30 phút

Hướng dẫn triển khai Autonomous Pentest Agent tại máy cục bộ

Tìm hiểu trước về phạm vi dự án và giới hạn sử dụng

Autonomous Pentest Agent là một hệ thống kiểm thử thâm nhập tự động do nhiều Agent dựa trên LLM điều khiển, sử dụng backend Go, frontend Next.js và PostgreSQL. Dự án có thể quản lý tác vụ, tài sản, chuỗi khám phá, kết quả phát hiện, bản ghi lưu lượng, phê duyệt công cụ và các cuộc hội thoại có con người tham gia.

Lưu ý quan trọng về an toàn và tuân thủ: README nêu rõ dự án này chỉ được sử dụng cho việc học cá nhân, nghiên cứu mã nguồn và xác minh kỹ thuật trong môi trường cô lập cục bộ. Không được sử dụng cho bất kỳ website, dịch vụ trực tuyến, hệ thống kết nối mạng, môi trường production hoặc hoạt động kiểm thử thâm nhập thực tế nào. Chỉ sử dụng trong phòng thí nghiệm cục bộ do bạn kiểm soát và tuân thủ luật pháp, quy định liên quan đến an ninh mạng, bảo vệ dữ liệu và tội phạm máy tính tại khu vực của bạn.

Dự án cung cấp Demo trực tuyến để tìm hiểu giao diện tương tác, nhưng việc triển khai và xác minh thực tế phải được giới hạn nghiêm ngặt trong môi trường cô lập cục bộ.

Tính năng và giao diện chính

Frontend của hệ thống cung cấp các trang bảng điều khiển, danh sách tác vụ, phiên thực thi, chuỗi khám phá, phát hiện, tài sản, bản đồ phạm vi tài sản, ghi lưu lượng, quản lý Agent, cấu hình LLM, phê duyệt chặn và nhật ký backend.

Bảng điều khiển dùng để xem trạng thái tổng thể, mức tiêu thụ Token và luồng hoạt động. Các trang tác vụ và phiên hiển thị quá trình thực thi tác vụ, bao gồm phiên Agent và các lần gọi công cụ.

Chuỗi khám phá dùng để theo dõi mối quan hệ nguồn gốc giữa mục tiêu, ý định, sự kiện và phát hiện; trang phát hiện dùng để xem lỗ hổng cùng bằng chứng, còn trang tài sản dùng để duyệt các tài sản mục tiêu được hệ thống thu thập và hợp nhất.

Bảng điều khiển

Tổng quan kiến trúc hệ thống

Hệ thống gồm backend Go dạng monolith tích hợp frontend tĩnh Next.js, PostgreSQL, engine Agent và một số hệ thống con hỗ trợ. Backend cung cấp dịch vụ cho frontend thông qua REST API, xác thực JWT và SSE; engine tác vụ chịu trách nhiệm điều phối planner cùng nhiều worker.

Dự án sử dụng kiến trúc hai đồ thị:

Đồ thị tài sản: kho dữ liệu chuẩn về tài sản được chia sẻ giữa các tác vụ, bao gồm các nút tên miền gốc, tên miền con, IP, dịch vụ, ứng dụng và endpoint.
Đồ thị khám phá: ghi lại mục tiêu, ý định, sự kiện, gợi ý và phát hiện theo từng tác vụ, đồng thời mô tả quá trình khám phá thông qua mối quan hệ nguồn gốc.
Quan hệ neo: liên kết các nút khám phá với tài sản cụ thể để xem mức độ bao phủ kiểm thử và phạm vi khám phá của tài sản.

Planner chịu trách nhiệm đọc trạng thái khám phá và phân phối ý định; Worker nhận ý định, sử dụng công cụ để thực thi rồi ghi lại sự kiện, tài sản và phát hiện. Sau khi đồ thị thay đổi, Planner sẽ được đánh thức lại để hình thành vòng lặp khép kín dựa trên sự kiện. Nhiều Worker cũng có thể truy vấn quá trình thực thi của các Worker khác, trong khi todolist dùng chung giúp việc lập kế hoạch nhiều vòng tiến hành các bước liên tục theo dependency.

Chuẩn bị trước khi cài đặt

Để chạy dự án, tối thiểu cần có PostgreSQL. Để thực hiện khám phá, bạn cũng cần cấu hình LLM bằng ANTHROPIC_API_KEY hoặc OPENAI_API_KEY, hoặc có thể điền sau trên trang «Cấu hình LLM» của giao diện Web.

Nên chuẩn bị Docker để nhanh chóng khởi động cơ sở dữ liệu và ứng dụng. Dù chọn phương thức triển khai nào, bạn cũng nên tạo mạng kiểm thử cục bộ cô lập trước, sao lưu dữ liệu quan trọng và xác nhận mục tiêu kiểm thử thuộc môi trường thí nghiệm cục bộ.

Tác vụ

Cách một: Sử dụng script cài đặt một bước

Đây là phương thức cài đặt được README khuyến nghị. Script sẽ kiểm tra hoặc cài đặt Docker, sau đó cho phép bạn chọn triển khai Docker đầy đủ hoặc biên dịch và chạy cục bộ.

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
./install.sh

Khi chọn triển khai Docker đầy đủ, script sẽ yêu cầu nhập mật khẩu PostgreSQL; bạn cũng có thể nhấn Enter để tạo mật khẩu ngẫu nhiên, sau đó ghi vào .env và thực thi docker compose up -d. Khi chọn chạy cục bộ, bạn có thể kết nối cơ sở dữ liệu hiện có hoặc dùng Docker để khởi động cơ sở dữ liệu; script sẽ tạo config.json, biên dịch frontend tích hợp thành một binary Go duy nhất và khởi động dịch vụ.

Sau khi cài đặt hoàn tất, truy cập http://localhost:8787. Khi truy cập lần đầu, mở /setup để đặt mật khẩu quản trị.

Cách hai: Sử dụng Docker Compose

Nếu muốn kiểm soát môi trường thủ công, bạn có thể sử dụng trực tiếp Compose:

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
cp .env.example .env
docker compose up -d

Quá trình thực thi

Hãy chỉnh sửa .env để điền POSTGRES_PASSWORD, đồng thời cấu hình ANTHROPIC_API_KEY nếu cần. Sau khi khởi động, truy cập http://localhost:8787.

Image Docker bao gồm các công cụ phổ biến; ./skills và ./data được lưu dữ liệu bằng bind mount. MCP từ xa có thể được chọn là Streamable HTTP hoặc SSE phiên bản cũ trong phần cài đặt hệ thống; khi sử dụng SSE phiên bản cũ, URL thường điền là /sse và đặt header yêu cầu Authorization=Bearer <token> theo yêu cầu của dịch vụ.

Cách ba: Sử dụng binary biên dịch sẵn

Bạn cũng có thể tải gói nén tương ứng với nền tảng từ Releases. Sau khi giải nén, gói thường bao gồm apagent, start.sh hoặc start.bat trên Windows, skills/ và config.example.json.

cp config.example.json config.json
./start.sh

Hãy dùng start.sh hoặc start.bat để khởi động, không chạy trực tiếp ./apagent. Script khởi động chịu trách nhiệm quyết định có khởi chạy lại chương trình theo mã thoát sau khi chương trình kết thúc hay không; tính năng cập nhật một bước trong giao diện cũng phụ thuộc vào cơ chế này. Để chạy nền, có thể sử dụng:

nohup ./start.sh >apagent.log 2>&1 &

Cách bốn: Biên dịch từ mã nguồn

Chuỗi khám phá

Khi biên dịch từ mã nguồn, trước tiên cần xây dựng các tệp tĩnh frontend, sau đó sao chép chúng vào thư mục tích hợp của backend và cuối cùng biên dịch chương trình Go bằng tag embedui.

cd web && npm ci && npm run build:static && cd ..
cp -r web/out server/webui/dist
CGO_ENABLED=0 go build -tags embedui -o apagent ./cmd/apagent
./start.sh

Nếu cần xây dựng gói phát hành đa nền tảng, có thể chạy:

./build.sh --release

Mặc định, hệ thống sẽ tạo nhiều gói đích cho Linux, macOS và Windows. Bạn cũng có thể tùy chỉnh các đích thông qua APAGENT_TARGETS. UPX mặc định không được bật vì binary tự giải nén sau khi nén có thể không tương thích với một số kernel Linux, môi trường ảo hóa hoặc chính sách bảo mật.

Cấu hình cơ sở dữ liệu và LLM

Khi chạy bản biên dịch cục bộ hoặc binary, có thể cấu hình PostgreSQL trong config.json:

{
  "database": {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "apagent",
    "password": "yourpass",
    "dbname": "apagent",
    "sslmode": "disable"
  }
}

Phát hiện

Bạn cũng có thể dùng APAGENT_PG_DSN để ghi đè cấu hình kết nối cơ sở dữ liệu. LLM có thể được cấu hình thông qua biến môi trường:

export ANTHROPIC_API_KEY=sk-...
# hoặc
export OPENAI_API_KEY=...

Các tham số tùy chọn gồm APAGENT_LLM_PROVIDER, APAGENT_LLM_MODEL, APAGENT_LLM_BASE_URL và APAGENT_LLM_PROXY. Nếu không muốn sử dụng biến môi trường, bạn có thể điền thông tin trên trang «Cấu hình LLM» của UI. Số lượng Worker của mỗi tác vụ có thể được điều chỉnh trong «Cài đặt hệ thống», giá trị mặc định là 3.

Quy trình sử dụng cơ bản

Hoàn tất khởi tạo: truy cập dịch vụ cục bộ, mở /setup để đặt mật khẩu quản trị và kiểm tra kết nối cơ sở dữ liệu.
Cấu hình LLM: thiết lập model khả dụng và các tham số cần thiết trong biến môi trường hệ thống hoặc trang «Cấu hình LLM».
Chuẩn bị mục tiêu cục bộ: chỉ thêm các tài sản thuộc môi trường thí nghiệm cô lập do bạn kiểm soát và xác nhận hệ thống sẽ không truy cập dịch vụ trực tuyến hoặc dịch vụ production.
Tạo và theo dõi tác vụ: quản lý tác vụ trên trang tác vụ, đồng thời xem trạng thái chạy trong bảng điều khiển và luồng hoạt động.
Xem kết quả khám phá: tìm hiểu mối quan hệ giữa ý định, sự kiện và phát hiện thông qua chuỗi khám phá; xem các tài sản đã hợp nhất qua đồ thị tài sản.
Kiểm tra bằng chứng thực thi: xem bản ghi quá trình trong các trang phiên, lần gọi công cụ và lưu lượng; khi gặp thao tác cần xác nhận thủ công, hãy xử lý trên trang phê duyệt chặn.

Bản đồ phạm vi tài sản hiển thị các tài sản trong phạm vi và các nút đã được kiểm thử bằng bố cục lực hướng, đồng thời hỗ trợ thu gọn và mở rộng nút. Bản đồ phù hợp để nhanh chóng xác định tài sản nào trong phạm vi thí nghiệm cục bộ đã được khám phá.

Đồng bộ tài sản từ ScopeSentry

Dự án hỗ trợ đồng bộ tài sản từ ScopeSentry để giảm việc thu thập trùng lặp. Mở trang «Đồng bộ tài sản», điền địa chỉ và API Key của ScopeSentry, sau đó chọn mục tiêu và loại tài sản cần đồng bộ theo dự án hoặc tác vụ.

Tài sản

Hỗ trợ lựa chọn theo phạm vi các loại tài sản như tên miền, tên miền con, IP, cổng, website và endpoint.
Sau khi nhập, các tài sản sẽ được gộp theo phạm vi tài sản của công ty.
Kết quả đồng bộ sẽ được đưa vào đồ thị tài sản của Autonomous Pentest Agent để sử dụng cho các tác vụ thử nghiệm cục bộ tiếp theo.

Ghi lại lưu lượng và phê duyệt

Hệ thống cung cấp proxy ghi lưu lượng, có thể chỉ định địa chỉ frontend, API và proxy lưu lượng bằng cách sử dụng lệnh tương tự ./start.sh -addr :8787 -proxy :8788. Quá trình thực thi công cụ của Worker sẽ để lại nhật ký hoạt động, còn cơ chế phê duyệt chặn được dùng để yêu cầu con người xác nhận thao tác của công cụ khi cần.

Chi tiết nhật ký phê duyệt có thể được xem trong nhật ký phê duyệt toàn cục, phê duyệt chặn trong tác vụ và thẻ phê duyệt trong cuộc trò chuyện. Khi sử dụng, cần kiểm tra cẩn thận đối tượng thao tác và các tham số, đồng thời luôn giới hạn mục tiêu trong môi trường thử nghiệm biệt lập.

Kiểm thử lại lỗ hổng

Tab “Kiểm thử lại” trong chi tiết tác vụ cho phép chọn lỗ hổng theo từng trang, xem các kết luận và bằng chứng trước đây, đồng thời khởi chạy một phiên Agent kiểm thử lại độc lập. Danh sách lỗ hổng, chi tiết lỗ hổng và chế độ xem tài sản đều cung cấp lối vào kiểm thử lại.

Kết luận kiểm thử lại gồm “Vẫn có thể tái hiện”, “Đã khắc phục” và “Không thể xác nhận”. Kết luận, bằng chứng và liên kết phiên của mỗi lần kiểm thử lại sẽ được lưu trong chi tiết lỗ hổng. Khi kiểm thử lại thành công và kết luận là “Đã khắc phục”, hệ thống sẽ tự động cập nhật trạng thái xử lý lỗ hổng; trạng thái ban đầu sẽ không tự động thay đổi nếu đang thực thi, thất bại, bị dừng hoặc có kết luận khác.

Lần đầu khởi động, backend sẽ tạo sẵn Agent “Kiểm thử lại lỗ hổng” có thể chỉnh sửa, tức retester. Agent này có thể được cấu hình về prompt, LLM, ngân sách chạy và công cụ trong phần quản lý Agent. Nếu cùng một lỗ hổng đang được kiểm thử lại, hệ thống sẽ sử dụng lại phiên hiện có; có thể khởi chạy lại sau khi dừng, thất bại hoặc dịch vụ khởi động lại. README cũng nêu rõ rằng nhật ký kiểm thử lại trước đây hiện chưa được đưa vào bản xuất báo cáo lỗ hổng hoặc gói lưu trữ tác vụ, cũng chưa được tự động liên kết với gói lưu lượng.

Bản đồ phạm vi tài sản

Triển khai proxy ngược

Frontend, API và SSE mặc định được cung cấp từ cùng một cổng backend, vì vậy thông thường không cần thiết lập NEXT_PUBLIC_SSE_BASE. Nếu công khai HTTPS qua Nginx, cần tắt bộ đệm SSE và đặt thời gian chờ đọc đủ dài:

server {
    listen 443 ssl;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Chỉ khi SSE sử dụng nguồn khác với trang web thì mới cần thiết lập NEXT_PUBLIC_SSE_BASE trong giai đoạn build. Biến này sẽ được cố định vào gói tĩnh khi chạy next build; thiết lập lại trong thời gian chạy container sẽ không có hiệu lực.

Nâng cấp và bảo vệ dữ liệu

Khi nâng cấp dự án, hệ thống chỉ thay thế chương trình, không chủ động xóa volume dữ liệu PostgreSQL, ./data hoặc ./skills. Khi ứng dụng khởi động, hệ thống sẽ thực hiện khởi tạo và migration cấu trúc cơ sở dữ liệu theo cách idempotent, vì vậy thông thường không cần chạy thủ công các script migration. Tuy nhiên, vẫn nên sao lưu ./data và cơ sở dữ liệu trước khi nâng cấp.

Khuyến nghị thực hiện cập nhật trong thẻ “Phiên bản và cập nhật” trên trang cấu hình hệ thống. Chương trình sẽ tải gói phát hành cho nền tảng hiện tại, kiểm tra SHA256, thực hiện kiểm thử nhanh, sau đó script khởi động sẽ hoàn tất việc thay thế. Khi kiểm tra thất bại, các tệp tạm sẽ bị loại bỏ; nếu phiên bản mới liên tục khởi động thất bại, hệ thống sẽ tự động khôi phục. Việc cập nhật sẽ khởi động lại dịch vụ và làm gián đoạn các tác vụ đang chạy, nên thực hiện khi hệ thống không bận.

Khi triển khai bằng Docker, cập nhật từ giao diện chỉ thay thế chương trình, không cập nhật bộ công cụ như Playwright và nmap trong image. Để cập nhật image, chạy:

Lưu lượng

docker compose pull apagent
docker compose up -d apagent

Cũng có thể sử dụng script cập nhật trong kho mã:

./update.sh

Phát triển và kiểm thử cục bộ

Chế độ phát triển có thể đồng thời khởi chạy backend, proxy lưu lượng và máy chủ phát triển Next.js:

./dev.sh

Địa chỉ truy cập mặc định là http://localhost:5173. Cũng có thể chạy riêng:

go run ./cmd/apagent
cd web && npm run dev
go test ./...

Khi không có -tags embedui, backend sẽ không nhúng frontend. Nếu chỉ muốn xem trước frontend mà không khởi động backend, có thể sử dụng:

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

Lưu ý thường gặp

Xác nhận PostgreSQL đã khởi động và kiểm tra tên người dùng, mật khẩu, tên cơ sở dữ liệu तथा cổng.
Nếu kết nối luồng hoạt động thành công nhưng không có sự kiện, hãy kiểm tra proxy ngược đã tắt bộ đệm hay chưa và xác nhận thời gian chờ kết nối dài đủ.
Khi sử dụng phiên bản biên dịch sẵn, không bỏ qua start.sh hoặc start.bat, nếu không cơ chế tự động thay thế và khởi động lại sau khi cập nhật trang có thể không hoạt động bình thường.
Sau khi sửa tài nguyên tĩnh frontend, phải chạy lại npm run build:static, sau đó sao chép vào server/webui/dist và biên dịch lại.
Sao lưu cơ sở dữ liệu, ./data và ./skills trước khi nâng cấp; cấu trúc cơ sở dữ liệu có thể tự động migration nhưng không tự động khôi phục.
Không nhập tài sản trực tuyến thực tế, thông tin xác thực production hoặc dữ liệu nhạy cảm vào hệ thống thử nghiệm cục bộ.

Tóm tắt

Autonomous Pentest Agent kết hợp dịch vụ Go, giao diện Next.js, mô hình dữ liệu hai đồ thị PostgreSQL và cơ chế điều phối nhiều Agent LLM để cung cấp khả năng quản lý tác vụ, chuỗi khám phá, phạm vi tài sản, lưu dấu lưu lượng, phê duyệt và kiểm thử lại lỗ hổng. Bạn có thể bắt đầu bằng Docker hoặc script cài đặt trong môi trường cục bộ biệt lập, sau đó cấu hình cơ sở dữ liệu và LLM, rồi từng bước tìm hiểu hành vi hệ thống thông qua tác vụ, đồ thị tài sản và phiên thực thi. Trong quá trình sử dụng, cần tuân thủ mục đích học tập cục bộ được dự án công bố và mọi yêu cầu pháp lý, tuân thủ liên quan.

Dự án sử dụng giấy phép AGPL-3.0; nếu sửa đổi và cung cấp dịch vụ cho người dùng qua mạng, cần công khai toàn bộ mã nguồn tương ứng theo yêu cầu của giấy phép. Có thể tham khảo thêm mã nguồn trong kho, norma SDK và tệp LICENSE của dự án để biết thêm chi tiết triển khai.