Utangulizi wa ARTEX: Kujenga mfumo wa majaribio ya uvamizi unaojiendesha kwa AI na kuelewa usanifu wa uchunguzi wa grafu mbili

Elewa kwanza wigo wa matumizi

ARTEX ni kwa matumizi ya kujifunza binafsi, utafiti wa msimbo na uthibitishaji wa kiufundi katika mazingira ya ndani yaliyotengwa pekee. Kulingana na tamko la mradi, hairuhusiwi kuitumia kuchanganua, kuchunguza, kutumia mianya au kushambulia mfumo wowote wa mtandaoni, tovuti, mfumo uliounganishwa kwenye mtandao au mazingira ya uzalishaji, hata kama lengo ni lako au una idhini. Kabla ya kuanza, thibitisha kuwa unaelewa na unafuata leseni ya AGPL-3.0 ya mradi, sheria za usalama wa mtandao za eneo lako, pamoja na vikwazo vya matumizi na kanusho lililo kwenye hazina.

Makala hii inategemea uwekaji wa ndani na mazingira salama yaliyotengwa, na inaeleza jinsi ya kusakinisha ARTEX, kusanidi PostgreSQL na LLM, kufuatilia kazi kupitia kiolesura, na kutumia vipengele kama ulandanishi wa mali na majaribio ya kuthibitisha udhaifu.

ARTEX ni mfumo wa AI wa mawakala wengi wenye backend ya Go na frontend ya Next.js. Mradi unatoa Demo ya mtandaoni kwa ajili ya kuona mwingiliano. Wakati wa uendeshaji rasmi, frontend inaweza kupachikwa kwenye binary moja kwa kutumia go:embed ya Go.

ARTEX inaweza kufanya nini

ARTEX imejengwa kuzunguka uchunguzi wa kujitegemea, upangaji wa kazi na kuhifadhi kumbukumbu za mchakato. Mfumo una violesura vya dashibodi, orodha ya kazi, mchakato wa utekelezaji wa vipindi, mnyororo wa uchunguzi, ugunduzi, mali, ramani ya ufunikaji wa mali, rekodi za trafiki, mazungumzo ya ushiriki wa binadamu, usimamizi wa Agent na usanidi wa LLM.

• Uchunguzi wa mawakala wengi: Majukumu kama goals, planner, worker na mainagent hushirikiana kuendeleza kazi.
• Mfumo wa grafu mbili: Grafu ya mali huhifadhi ukweli wa mali unaoshirikiwa kati ya kazi, huku grafu ya uchunguzi ikirekodi malengo, nia, ukweli, vidokezo na ugunduzi wa kazi moja.
• Ubadilishanaji wa taarifa wa kiwango cha mchakato: worker anaweza kupata mchakato wa utekelezaji wa worker wengine na kutumia tena uchunguzi wao.
• Ushiriki wa binadamu: Kupitia mazungumzo na uidhinishaji wa hatua zilizonaswa, binadamu hushiriki katika miito ya zana na maamuzi muhimu ya uendeshaji.
• Mtiririko wa shughuli wa wakati halisi: Backend hutuma taarifa za shughuli kupitia SSE, hivyo mchakato wa utekelezaji wa kazi unaweza kufuatiliwa mfululizo kwenye kiolesura.
• Rekodi za trafiki: Wakala wa MITM wa kurekodi huhifadhi trafiki na ushahidi wa utekelezaji wa zana.
• Ulandanishi wa mali: Unaweza kusawazisha mali kama vikoa, vikoa vidogo, IP, bandari, tovuti na endpoint kutoka ScopeSentry.
• Majaribio ya kuthibitisha udhaifu: Unaweza kuunda kipindi cha Agent cha majaribio kwa udhaifu uliopo na kuhifadhi hitimisho, ushahidi na kiungo cha kipindi.

Kusakinisha ARTEX

Njia ya kwanza: Kutumia hati ya usakinishaji wa hatua moja

Hii ndiyo njia inayopendekezwa na mradi. Hati hukagua au kusakinisha Docker, na hutoa chaguo la kutumia Docker kikamilifu au kujenga na kuendesha ndani.

git clone https://github.com/Autumn-27/ARTEX.git
cd ARTEX
./install.sh

Unapochagua Docker kikamilifu, unahitaji kuweka nenosiri la PostgreSQL; unaweza pia kubonyeza Enter moja kwa moja ili hati itengeneze nenosiri la nasibu. Kisha hati itaandika .env na kutekeleza docker compose up -d.

Unapochagua uendeshaji wa ndani, unaweza kuunganisha hifadhidata iliyopo au kuruhusu Docker ianzishe hifadhidata. Hati itatengeneza config.json, ijenge binary moja iliyo na frontend, na ianzishe huduma.

Baada ya usakinishaji kukamilika, tembelea http://localhost:8787. Unapofungua kwa mara ya kwanza, nenda kwenye /setup ili kuweka nenosiri la msimamizi.

Njia ya pili: Kutumia Docker Compose kwa mkono

git clone https://github.com/Autumn-27/ARTEX.git
cd ARTEX
cp .env.example .env
docker compose up -d

Hariri .env na ujaze angalau POSTGRES_PASSWORD; ikiwa ungependa kusanidi Anthropic kupitia vigezo vya mazingira, unaweza pia kujaza ANTHROPIC_API_KEY. Picha ya kontena ina zana za kawaida, na ./skills pamoja na ./data huhifadhiwa kupitia bind mount.

Baada ya kuanzisha, tembelea http://localhost:8787. Ikiwa unahitaji MCP ya mbali, chagua http au sse katika mipangilio ya mfumo. Toleo la zamani la SSE kwa kawaida hutumia /sse kuanzisha mtiririko wa matukio, kisha hupokea maombi ya JSON-RPC kupitia /message?sessionId=... inayorejeshwa; kichwa cha ombi la uthibitishaji husanidiwa kama Authorization=Bearer <token>.

Njia ya tatu: Kutumia binary iliyojengwa tayari

Pakua kifurushi cha jukwaa lako kutoka Releases, kisha kitoe. Kwa kawaida kitakuwa na artex, start.sh au start.bat kwenye Windows, skills/ na config.example.json.

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

Tumia start.sh au start.bat kuanzisha, na usiendeshe moja kwa moja ./artex. Hati ya uanzishaji inasimamia mchakato na huwezesha kuanzisha tena huduma baada ya kusasisha ukurasa kwa mbofyo mmoja. Ili kuendesha nyuma ya pazia, unaweza kutumia:

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

Njia ya nne: Kujenga kutoka kwenye msimbo wa chanzo

Ikiwa unahitaji kujenga binary moja yenye frontend iliyopachikwa kutoka kwenye msimbo wa chanzo, kwanza tengeneza faili tuli za Next.js, kisha zinakili kwenye saraka ya frontend iliyopachikwa ya backend.

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

Kukamilisha usanidi wa msingi

Kusanidi PostgreSQL

ARTEX inategemea PostgreSQL. Unapotumia uendeshaji wa ndani, unaweza kuweka taarifa za muunganisho wa hifadhidata kwenye config.json, au kuzibatilisha kupitia ARTEX_PG_DSN.

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

Kila huduma inapoanzishwa, hutekeleza kwa njia isiyobadilisha matokeo uanzishaji na uhamishaji wa muundo wa hifadhidata, ikiwemo mabadiliko muhimu ya sehemu na faharasa. Kabla ya kusasisha, bado inapendekezwa kuhifadhi nakala ya hifadhidata na saraka ya ./data.

Kusanidi LLM

Vipengele vya uchunguzi vinahitaji LLM. Unaweza kutumia API Key ya Anthropic au OpenAI, au kuijaza kwenye ukurasa wa「Usanidi wa LLM」wa kiolesura.

export ANTHROPIC_API_KEY=sk-...

Unaweza pia kuweka OPENAI_API_KEY. Mradi pia unaunga mkono ARTEX_LLM_PROVIDER, ARTEX_LLM_MODEL, ARTEX_LLM_BASE_URL na ARTEX_LLM_PROXY kwa ajili ya kurekebisha mtoa huduma, modeli, anwani na proksi.

Kurekebisha ulinganifu na bandari

Idadi ya work agent kwa kila kazi inaweza kurekebishwa katika「Mipangilio ya mfumo」; thamani chaguo-msingi ni 3. Vigezo vya uanzishaji vinaweza kuweka anwani ya Web/API na bandari ya proksi ya kurekodi trafiki:

./start.sh -addr :8787 -proxy :8788

Hati ya uanzishaji hupitisha vigezo hivyo bila kuvibadilisha kwa artex.

Kuanza kutumia kiolesura cha Web

1. Kuingia na kutazama dashibodi

Unapotembelea kwa mara ya kwanza, weka nenosiri la msimamizi, kisha nenda kwenye dashibodi kutazama muhtasari, matumizi ya Token na mtiririko wa shughuli. Dashibodi inafaa kwa kutathmini haraka ikiwa mfumo wa sasa unaendelea kawaida na ikiwa kazi zimezalisha shughuli mpya.

2. Kutazama kazi na mchakato wa utekelezaji

Katika orodha ya kazi, chagua kazi lengwa ili kutazama vipindi vyake, miito ya zana, rekodi za shughuli na mnyororo wa uchunguzi. Ukurasa wa mchakato wa utekelezaji huonyesha hatua za kazi za agent, huku mnyororo wa uchunguzi ukisaidia kuelewa uhusiano kati ya malengo, nia, ukweli na ugunduzi.

Unapotumia kurasa hizi, thibitisha kwanza mchakato katika mazingira ya ndani yaliyotengwa, na utumie rekodi za shughuli pamoja na rekodi za trafiki kukagua hatua ambazo agent alitekeleza kwa kweli.

3. Kutazama ugunduzi na mali

Ukurasa wa ugunduzi huonyesha kwa pamoja udhaifu au ugunduzi mwingine uliotokana na kazi, huku ukurasa wa mali ukionyesha taarifa za mali zilizokusanywa na kuunganishwa na mfumo.

Ramani ya ufunikaji wa mali inaweza kuonyesha mali zilizo ndani ya wigo kwa mpangilio unaoongozwa na nguvu, na kuangazia nodi zilizojaribiwa. Inaunga mkono kukunja na kupanua nodi, na inafaa kwa kuona kwa ujumla ni mali zipi tayari zimechunguzwa na zipi bado hazijafunikwa.

Kusawazisha mali za ScopeSentry

Ikiwa tayari umekusanya mali katika ScopeSentry, unaweza kuunganisha chanzo cha data kupitia ukurasa wa「Ulandanishi wa mali」wa ARTEX ili kuepuka ukusanyaji unaojirudia.

1. Jaza anwani ya ScopeSentry na API Key ili kukamilisha muunganisho wa chanzo cha data.
2. Chagua malengo ya kusawazisha kulingana na mradi au kazi.
3. Chagua aina za mali, kama vile kikoa, kikoa kidogo, IP, bandari, tovuti au endpoint.
4. Tekeleza uagizaji ili ARTEX iunganishe data kulingana na wigo wa mali wa kampuni.
5. Kagua matokeo ya uagizaji kwenye grafu ya mali, kisha uyawasilishe kwa agent kwa uchunguzi unaofuata.

Grafu ya mali ni hazina ya kimataifa ya ukweli wa mali inayoshirikiwa kati ya kazi. Programu huhesabu uhusiano wa mzazi na mtoto pamoja na funguo za kuondoa nakala, huku agent akiwasilisha taarifa ghafi za mali.

Kuelewa usanifu wa grafu mbili wa ARTEX

Grafu ya mali: inaeleza mali zilizopo

Nodi katika grafu ya mali zinajumuisha root_domain, subdomain, ip, service, app na endpoint. Vikoa, vikoa vidogo, huduma na vituo vya mwisho hupangwa kupitia uhusiano wa mzazi na mtoto, na huhusishwa na kampuni husika.

Grafu ya uchunguzi: inaeleza jinsi kazi inavyoendelezwa

Grafu ya uchunguzi huhifadhiwa kando kwa kila kazi, ikiwa na nodi za goal, intent, fact, finding na hint. Mfumo hurekodi mnyororo wa maendeleo kupitia uhusiano kama spawns, derived_from, yields na proves.

Grafu hizi mbili huunganishwa kupitia nanga. Intent, facts na udhaifu vinaweza kuunganishwa na mali mahususi. Hivyo, unaweza kuona mali zinazohusika kutoka upande wa uchunguzi, au kuanzia kwenye mali fulani na kuchunguza ni mwelekeo gani umeijaribu katika kazi ya sasa.

Jinsi planner na worker hushirikiana

Injini hutumia mzunguko funge unaoendeshwa na matukio: grafu inapobadilika, planner huamshwa, husoma hali ya sasa na kugawa intent; worker huchukua intent moja, hutumia zana kuitekeleza, kisha huandika mali, facts au findings mpya kwenye hifadhidata; operesheni hiyo ya kuandika huamsha planner tena.

Planner hugawa intent tu inapogundua mwelekeo mpya ambao bado haujashughulikiwa. Worker anapomaliza intent aliyoichukua, husimama ili kuzuia workers tofauti kurudia utekelezaji bila kikomo.

Kwa minyororo ya uchunguzi yenye hatua nyingi na utegemezi wa mpangilio, planner hudumisha todolist ya pamoja inayohifadhiwa kwa kila kazi. Hatua inayofuata hugawiwa tu baada ya hatua ya awali kukamilika na fact inayohusiana kuwepo. Utaratibu huu huzuia mnyororo mzima kufunguliwa kwa sambamba kwa wakati mmoja.

Kutafuta mchakato wa utekelezaji wa workers wengine

Workers wanaofuata wanaweza kutumia search_all_worker_traces(q) kutafuta kwa neno muhimu katika michakato ya utekelezaji wa work nyingine za kazi hii, au kutumia list_worker_traces kuona work zilizotekelezwa, kisha kutumia get_worker_trace(intent_id, step_ids=[...]) kupata maudhui kamili ya hatua mahususi. Mfumo huondoa kiotomatiki intent ya worker wa sasa.

Ubadilishanaji huu wa taarifa katika kiwango cha mchakato humsaidia agent kutumia tena uchunguzi ambao bado haujaandikwa rasmi kama fact, huku ukidumisha mpaka kwamba kila worker atekeleze tu intent aliyopewa.

Rekodi za trafiki na idhini

ARTEX hutoa proksi ya kurekodi trafiki na lango la kuidhinisha zana. Ukurasa wa trafiki hutumika kutazama rekodi zinazozalishwa na utekelezaji wa zana, huku ukurasa wa idhini ukitumika kushughulikia operesheni zinazohitaji uthibitisho wa binadamu.

Wakati wa uthibitishaji wa usalama, inashauriwa kutazama kwa pamoja kipindi cha kazi, miito ya zana, mkondo wa shughuli na rekodi za trafiki ili kuthibitisha kuwa tabia ya mfumo inalingana na matarajio. Mazungumzo ya human-in-the-loop yanaweza pia kutumiwa kuongeza muktadha na kushiriki katika idhini.

Kutekeleza majaribio ya kurudia ya udhaifu

Kichupo cha “Majaribio ya kurudia” katika maelezo ya kazi hukuruhusu kuchagua udhaifu wa kazi hii kwa kurasa, kutazama hitimisho na ushahidi wa awali, na kuanzisha jaribio jipya kivyake. Orodha ya udhaifu, maelezo ya udhaifu, mwonekano wa makundi ya kazi na mwonekano wa mali vyote vina sehemu ya kuanzisha jaribio la kurudia.

1. Bofya “Majaribio ya kurudia” katika orodha au maelezo ya udhaifu.
2. Jaza toleo la marekebisho, masharti ya jaribio au vikwazo inapohitajika.
3. Anzisha kipindi huru cha Agent wa majaribio ya kurudia.
4. Tazama mchakato wa jaribio katika kipindi, kisha tazama hitimisho na ushahidi baada ya kukamilika.

Hitimisho la jaribio linajumuisha “Bado inaweza kurudiwa”, “Imerekebishwa” na “Haiwezi kuthibitishwa”. Jaribio likikamilika kwa mafanikio na hitimisho likawa “Imerekebishwa”, mfumo husasisha kiotomatiki hali ya kushughulikia udhaifu; hali ya utekelezaji, kushindwa, kusimamishwa au hitimisho lingine haibadilishi kiotomatiki hali ya awali. Ushahidi na ripoti za awali huhifadhiwa.

Mfumo huandaa Agent ya “Majaribio ya kurudia udhaifu” retester inayoweza kuhaririwa. Inaweza kusanidiwa katika usimamizi wa Agent kwa prompt, LLM, bajeti ya uendeshaji na zana; ikiwa LLM maalum haijaunganishwa, hutumia usanidi wa kimataifa ulioamilishwa. Udhaifu uleule unapokuwa kwenye jaribio la kurudia, kipindi kilichopo hutumiwa tena; baada ya kusimamishwa, kushindwa au kuanzishwa upya kwa huduma, jaribio linaweza kuanzishwa tena.

Kumbuka kuwa maelezo ya mradi yanaonyesha kwamba historia ya majaribio ya kurudia bado haijajumuishwa katika uhamishaji wa ripoti za udhaifu au kifurushi cha kuhifadhi kazi, wala haijaunganishwa kiotomatiki na kifurushi cha trafiki. Hali ya onyesho hutengeneza rekodi za kuigwa zilizoainishwa wazi pekee, na haiombi malengo halisi.

Mambo muhimu ya uwekaji wa reverse proxy

Frontend, API na SSE hutolewa kwa chaguo-msingi na mlango mmoja wa backend. Kwa kawaida, unahitaji tu kufungua mlango wa HTTPS kwa umma na kuweka 8787 ya ARTEX ndani ya mtandao wa ndani. Mkondo wa shughuli wa wakati halisi hutumia anwani ya chanzo kimoja, hivyo kwa kawaida hakuna haja ya kuweka NEXT_PUBLIC_SSE_BASE.

Reverse proxy kama Nginx lazima izime buffering ya SSE na iweke muda mrefu wa kusubiri usomaji; la sivyo, kivinjari kinaweza kuunganishwa kwa mafanikio lakini kikashindwa kuendelea kupokea matukio ya shughuli.

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 "";
}

NEXT_PUBLIC_SSE_BASE inahitajika tu pale SSE inapolazimika kutumia chanzo tofauti, kwa mfano subdomain huru. Kigezo hiki huwekwa moja kwa moja kwenye kifurushi tuli wakati wa next build; kukiweka wakati wa kuendesha kontena hakutafanya kazi.

Kuboresha na kurejesha toleo la awali

Uboreshaji wa ARTEX hubadilisha programu, lakini huhifadhi volume ya data ya PostgreSQL, ./data na ./skills. Inapendekezwa kutekeleza usasishaji wa kubofya mara moja kupitia kadi ya “Matoleo na masasisho” katika ukurasa wa usanidi wa mfumo. Mchakato wa usasishaji hupakua kifurushi cha toleo la jukwaa la sasa, hukagua SHA256SUMS, huendesha jaribio la awali la binary mpya, kisha script ya kuanzisha hukamilisha uingizwaji.

Ukaguzi au jaribio la awali likishindwa, programu iliyohifadhiwa kwa muda hutupiliwa mbali; toleo jipya likishindwa kuanzishwa mara tatu mfululizo, mfumo hurejesha kiotomatiki toleo la awali. Toleo la awali huhifadhiwa kama artex.old. Hata hivyo, muundo wa hifadhidata haurudishwi pamoja na programu, hivyo bado unapaswa kuweka nakala rudufu ya hifadhidata na ./data kabla ya kuboresha.

Usasishaji huanzisha upya huduma na kukatiza kazi zinazoendelea, hivyo unapaswa kuutekeleza wakati wa mapumziko. Kwa uwekaji wa Docker, kumbuka pia kuwa usasishaji wa ukurasa hubadilisha programu pekee, wala haubadilishi mlolongo wa zana ndani ya image. Ili kuboresha image, tekeleza:

docker compose pull artex
docker compose up -d artex

Unaweza pia kutumia script ya usasishaji iliyo kwenye hazina:

cd ARTEX
./update.sh

Maendeleo na majaribio ya ndani

Mazingira ya maendeleo yanaweza kutumia dev.sh kuanzisha backend, proksi ya trafiki na seva ya maendeleo ya Next.js kwa wakati mmoja:

./dev.sh

Kwa chaguo-msingi, mlango wa backend ni 8787, mlango wa proksi ya trafiki ni 8788, na seva ya maendeleo ya frontend ni 5173. Unaweza pia kuziendesha kando:

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

Ikiwa unahitaji tu kuhakiki frontend bila kuanzisha backend, unaweza kutumia:

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

Muhtasari

ARTEX huunganisha backend ya Go ya monolith, kiolesura cha Next.js, PostgreSQL, agent wa LLM, rekodi za trafiki, utaratibu wa idhini na usimamizi wa mali katika mfumo mmoja. Unapoanza, unaweza kwanza kupeleka mfumo kupitia Docker au script ya usakinishaji, kisha usanidi PostgreSQL na LLM, na baadaye ujifunze tabia ya mfumo hatua kwa hatua kupitia kazi, vipindi, minyororo ya uchunguzi, ramani ya ufunikaji wa mali na rekodi za trafiki.

Kuelewa mgawanyo wa majukumu kati ya grafu ya mali na grafu ya uchunguzi ni muhimu kwa kuimudu ARTEX: grafu ya mali hujibu “Ni mali gani zilizopo?”, huku grafu ya uchunguzi ikijibu “Kazi inaendelezwaje?”. Kabla ya jaribio lolote, punguza kwa ukali upeo kwenye mazingira ya ndani yaliyotengwa na matumizi ya kujifunza yanayoruhusiwa na mradi, na uzingatie tamko la mradi, leseni ya chanzo huria na sheria zinazotumika.