macontrol

Miradi inayofuata mazoea bora hapa chini inaweza kujihakikisha kwa hiari na kuonyesha kuwa wamepata nishani ya mazoea bora ya Open Source Security Foundation (OpenSSF).

Hakuna seti ya mazoea yawezayo kuhakikisha kuwa programu haitakuwa na kasoro au udhaifu; hata mbinu rasmi zinaweza kushindwa ikiwa vipimo au dhana ni sahihi. Wala hakuna seti ya mazoea yawezayo kuhakikisha kuwa mradi utaendelea kuwa na jamii ya maendeleo yenye afya na inayofanya kazi vizuri. Hata hivyo, kufuata mazoea bora kunaweza kusaidia kuboresha matokeo ya miradi. Kwa mfano, baadhi ya mazoea huwezesha ukaguzi wa watu wengi kabla ya kutolewa, ambayo inaweza kusaidia kupata udhaifu wa kiufundi ambao vinginevyo ni vigumu kupata na kusaidia kujenga uaminifu na hamu ya mwingiliano wa kurudia kati ya wasanidi programu kutoka makampuni tofauti. Ili kupata nishani, vigezo vyote vya LAZIMA na LAZIMA WALA USIWAHI lazima vifuatwe, vigezo vyote vya INAPASWA lazima vifuatwe AU visivyo fufufutiliana na thibitisho, na vigezo vyote vya PENDEKEZA lazima vifuatwe AU visivyo fufufutiliana (tunataka vifikiwe angalau). Ikiwa unataka kuingiza maandishi ya thibitisho kama maoni ya jumla, badala ya kuwa maelezo ya busara kwamba hali ni inakubaliwa, anza kifungu cha maandishi na '//' ikifuatiwa na nafasi. Maoni ni karibu kupitia tovuti ya GitHub kama masuala au maombi ya kuvuta Kuna pia orodha ya barua pepe kwa majadiliano ya jumla.

Tunafuraha kutoa habari katika lugha nyingi, hata hivyo, ikiwa kuna mgongano au kutokuwa na usawa kati ya tafsiri, toleo la Kiingereza ni toleo lenye mamlaka.
Ikiwa huu ni mradi wako, tafadhali onyesha hadhi ya nishani yako kwenye ukurasa wa mradi wako! Hadhi ya nishani inaonekana kama hii: Kiwango cha nishani kwa mradi 12643 ni passing Hapa ni jinsi ya kuiweka:
Unaweza kuonyesha hali ya nishani yako kwa kuweka hii katika faili yako ya markdown:
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12643/badge)](https://www.bestpractices.dev/projects/12643)
au kwa kuweka hii katika HTML yako:
<a href="https://www.bestpractices.dev/projects/12643"><img src="https://www.bestpractices.dev/projects/12643/badge"></a>


Hizi ni vigezo vya kiwango cha Kupita. Unaweza pia kuangalia vigezo vya kiwango cha Fedha au Dhahabu.

Baseline Series: Kiwango cha Msingi 1 Kiwango cha Msingi 2 Kiwango cha Msingi 3

        

 Misingi 13/13 ●

  • Jumla

    Kumbuka kwamba miradi mingine inaweza kutumia jina sawa.

    Control your Mac from Telegram — system, media, network, power, and more. Apple Silicon, Go, one binary

    Tafadhali tumia muundo wa maneno ya leseni ya SPDX; mifano ni pamoja na "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "GPL-2.0+", "LGPL-3.0+", "MIT", na "(BSD-2-Clause OR Ruby)". Usitumie alama za nukuu za moja au mbili.
    Ikiwa kuna lugha zaidi ya moja, ziorodhe kama thamani zilizotengwa kwa koma (nafasi ni za hiari) na ziorodhe kuanzia iliyotumiwa zaidi hadi iliyotumiwa kidogo. Ikiwa kuna orodha ndefu, tafadhali orodhesha angalau tatu za kawaida zaidi. Ikiwa hakuna lugha (k.m., huu ni mradi wa nyaraka tu au wa majaribio tu), tumia herufi moja "-". Tafadhali tumia herufi kubwa za kawaida kwa kila lugha, k.m., "JavaScript".
    Common Platform Enumeration (CPE) ni mpango wa kuweka majina yenye muundo kwa mifumo ya teknolojia ya habari, programu, na vifurushi. Inatumika katika mifumo na hifadhidata nyingi wakati wa kuripoti udhaifu.

    macontrol is a tiny Go daemon that runs on your Mac and exposes a menu-first Telegram bot for remote control: change volume / brightness, toggle Wi-Fi / Bluetooth, read battery & system stats, take screenshots, send desktop notifications, lock / sleep / restart, and more.

  • Maudhui ya kimsingi ya tovuti ya mradi


    Ya kutosha kwa nishani!

    Tovuti ya mradi LAZIMA ieleze kwa ufupi programu inafanya nini (inasuluhu tatizo gani?). [description_good]
    Hii LAZIMA iwe katika lugha ambayo watumiaji watarajiwa wanaweza kuelewa (k.m., inatumia lugha ya kiufundi kidogo).

    Ya kutosha kwa nishani!

    Tovuti ya mradi LAZIMA itoe habari juu ya jinsi ya: kupata, kutoa maoni (kama ripoti za hitilafu au maboresho), na kuchangia kwenye programu. [interact]

    https://github.com/amiwrpremium/macontrol/issues
    https://github.com/amiwrpremium/macontrol/blob/master/SECURITY.md
    https://github.com/amiwrpremium/macontrol/blob/master/SUPPORT.md


    Ya kutosha kwa nishani!

    Habari juu ya jinsi ya kuchangia LAZIMA ieleze mchakato wa uchangiaji (kwa mfano, je! Maombi ya kuvuta yanatumika?) (URL inahitajika) [contribution]
    Tunafikiria kuwa miradi kwenye GitHub hutumia maswala na kuvuta maombi isipokuwa palipoonyeshwa vingine. Habari hii inaweza kuwa fupi, kwa mfano, ikisema kuwa mradi hutumia maombi ya kuvuta, msako wa suala, au machapisho kwenye orodha ya barua (ipi?)

    Non-trivial contribution file in repository: https://github.com/amiwrpremium/macontrol/blob/master/CONTRIBUTING.md.


    Ya kutosha kwa nishani!

    Habari juu ya jinsi ya kuchangia INAPASWA kujumuisha mahitaji ya michango inayokubalika (k.m., rejeleo la kiwango chochote kinachohitajika cha usimbaji). (URL inahitajika) [contribution_requirements]

    https://github.com/amiwrpremium/macontrol/blob/master/CONTRIBUTING.md


  • Leseni ya FLOSS


    Ya kutosha kwa nishani!

    Programu iliyozalishwa na mradi LAZIMA itolewa kama FLOSS. [floss_license]
    FLOSS ni programu iliyotolewa kwa njia inayokidhi Ufafanuzi wa Chanzo Wazi au Ufafanuzi wa Programu Huria. Mifano ya leseni kama hizo ni pamoja na CC0, MIT, BSD 2-clause, BSD 3-clause revised, Apache 2.0, Lesser GNU General Public License (LGPL), na GNU General Public License (GPL). Kwa madhumuni yetu, hii inamaanisha kuwa leseni LAZIMA iwe: Programu YAWEZA pia kupatiwa leseni kwa njia nyingine (k.m., "GPLv2 au ya kibinafsi" inakubaliwa).

    The MIT license is approved by the Open Source Initiative (OSI).


    Ya kutosha kwa nishani!

    INAPENDEKEZA kwamba leseni yoyote inayohitajika kwa programu iliyozalishwa na mradi iwe imeidhinishwa na Open Source Initiative (OSI). [floss_license_osi]
    OSI inatumia mchakato mgumu wa uidhinishaji kuamua ni leseni zipi ni OSS.

    The MIT license is approved by the Open Source Initiative (OSI).


    Ya kutosha kwa nishani!

    Mradi LAZIMA uweke leseni za matokeo yake mahali pa kawaida katika hazina yake ya chanzo. (URL inahitajika) [license_location]
    Desturi moja ni kuweka leseni kama faili ya ngazi ya juu inayoitwa LICENSE au COPYING, ambayo YAWEZA kufuatiwa na kiendelezi kama ".txt" au ".md". Desturi mbadala ni kuwa na saraka inayoitwa LICENSES inayohifadhi faili za leseni; faili hizi kwa kawaida zinaitwa kama kitambulisho chao cha leseni ya SPDX kikifuatiwa na kiendelezi kinachofaa, kama ilivyoelezwa katika Maelezo ya REUSE. Kumbuka kwamba kigezo hiki ni mahitaji tu kwenye hazina ya chanzo. Huhitaji kuingiza faili ya leseni wakati wa kuzalisha kitu kutoka kwenye msimbo wa chanzo (kama programu inayotekelezeka, kifurushi, au chombo). Kwa mfano, wakati wa kuzalisha kifurushi cha R kwa Mtandao wa Kumbukumbu Kamili wa R (CRAN), fuata mazoea ya kawaida ya CRAN: ikiwa leseni ni leseni ya kawaida, tumia maelezo mafupi ya kawaida ya leseni (ili kuepuka kusakinisha nakala nyingine ya maandishi) na orodhesha faili ya LICENSE katika faili ya kutengwa kama .Rbuildignore. Vivyo hivyo, wakati wa kuunda kifurushi cha Debian, unaweza kuweka kiungo katika faili ya hakimiliki kwa maandishi ya leseni katika /usr/share/common-licenses, na utenge faili ya leseni kutoka kwenye kifurushi kilichoundwa (k.m., kwa kufuta faili baada ya kuita dh_auto_install). Tunashauri jumuisha maelezo ya leseni yanayoweza kusomwa na mashine katika miundo iliyozalishwa mahali inapofaa.

    Non-trivial license location file in repository: https://github.com/amiwrpremium/macontrol/blob/master/LICENSE.


  • Nyaraka


    Ya kutosha kwa nishani!

    Mradi LAZIMA utoe nyaraka za msingi za programu iliyozalishwa na mradi. [documentation_basics]
    Nyaraka hizi lazima ziwe katika vyombo fulani (kama maandishi au video) vinavyojumuisha: jinsi ya kuisakinisha, jinsi ya kuianzisha, jinsi ya kuitumia (huenda ikijumuisha mafunzo kwa kutumia mifano), na jinsi ya kuitumia kwa usalama (k.m., nini cha kufanya na nini cha kutofanya) ikiwa hiyo ni mada inayofaa kwa programu. Nyaraka za usalama lazima zisiwe ndefu. Mradi YAWEZA kutumia viungo vya hypertext kwa nyenzo zisizo za mradi kama nyaraka. Ikiwa mradi hauzalishi programu, chagua "haihusiki" (N/A).

    Some documentation basics file contents found.


    Ya kutosha kwa nishani!

    Mradi LAZIMA utoe nyaraka za marejeleo zinazofafanua kiolesura cha nje (ingizo na matokeo) cha programu iliyozalishwa na mradi. [documentation_interface]
    Nyaraka za kiolesura cha nje zinaeleza kwa mtumiaji wa mwisho au msanidi jinsi ya kuitumia. Hii itajumuisha kiolesura chake cha programu ya programu (API) ikiwa programu ina. Ikiwa ni maktaba, andika madarasa/aina kuu na mbinu/vitendakazi vinavyoweza kuitwa. Ikiwa ni programu ya wavuti, fafanua kiolesura chake cha URL (mara nyingi kiolesura chake cha REST). Ikiwa ni kiolesura cha mstari wa amri, andika vigezo na chaguo zinazosaidia. Katika hali nyingi ni bora ikiwa nyingi ya nyaraka hizi zinazalishwa kiotomatiki, ili nyaraka hizi zibaki zikisawazishwa na programu inavyobadilika, lakini hii haihitajiki. Mradi YAWEZA kutumia viungo vya hypertext kwa nyenzo zisizo za mradi kama nyaraka. Nyaraka ZIWEZA kuzalishwa kiotomatiki (ambapo ni vitendo hii mara nyingi ndiyo njia bora ya kufanya hivyo). Nyaraka za kiolesura cha REST zinaweza kuzalishwa kwa kutumia Swagger/OpenAPI. Nyaraka za kiolesura cha msimbo ZINAWEZA kuzalishwa kwa kutumia zana kama vile JSDoc (JavaScript), ESDoc (JavaScript), pydoc (Python), devtools (R), pkgdown (R), na Doxygen (nyingi). Kuwa na maoni tu katika msimbo wa utekelezaji haitoshi kutosheleza kigezo hiki; kunahitaji kuwa na njia rahisi ya kuona habari bila kusoma kupitia msimbo wote wa chanzo. Ikiwa mradi hauzalishi programu, chagua "haihusiki" (N/A).

  • Mengine


    Ya kutosha kwa nishani!

    Tovuti za mradi (tovuti, hifadhi, na URL za kupakua) LAZIMA zisaidie HTTPS kwa kutumia TLS. [sites_https]
    Hii inahitaji kwamba URL ya ukurasa wa nyumbani wa mradi na URL ya hifadhi ya udhibiti wa toleo vianze na "https:", si "http:". Unaweza kupata vyeti vya bure kutoka Let's Encrypt. Miradi YAWEZA kutekeleza kigezo hiki kwa kutumia (kwa mfano) GitHub pages, GitLab pages, au SourceForge project pages. Ikiwa unasaidia HTTP, tunakuhimiza uelekeze trafiki ya HTTP kwenda HTTPS.

    Given only https: URLs.


    Ya kutosha kwa nishani!

    Mradi LAZIMA uwe na taratibu moja au zaidi za majadiliano (ikiwa ni pamoja na mabadiliko yaliyopendekezwa na masuala) yenye utafutaji, inaruhusu ujumbe na mada kuelekezwa kwa URL, inaruhusu watu wapya kushiriki katika baadhi ya majadiliano, na haihitaji usakinishaji wa upande wa mteja wa programu ya kibinafsi. [discussion]
    Mifano ya taratibu zinazokubalika ni pamoja na orodha za barua pepe zilizohifadhiwa, majadiliano ya suala la GitHub na ombi la kuvuta, Bugzilla, Mantis, na Trac. Taratibu za majadiliano yasiyo ya wakati mmoja (kama IRC) zinakubaliwa ikiwa zinakidhi vigezo hivi; hakikisha kuna utaratibu wa kuhifadhi unaoelekezwa kwa URL. JavaScript ya kibinafsi, ingawa haikubalika, inaruhusiwa.

    GitHub supports discussions on issues and pull requests.


    Ya kutosha kwa nishani!

    Mradi UNAPASWA kutoa nyaraka kwa Kiingereza na uweze kukubali ripoti za hitilafu na maoni kuhusu msimbo kwa Kiingereza. [english]
    Kiingereza kwa sasa ni lingua franca ya teknolojia ya kompyuta; kusaidia Kiingereza huongeza idadi ya wasanidi na wakaguzi tofauti wa uwezekano duniani kote. Mradi unaweza kukidhi kigezo hiki hata ikiwa lugha ya msingi ya wasanidi wake wakuu si Kiingereza.

    Ya kutosha kwa nishani!

    Mradi LAZIMA utunzwe. [maintained]
    Kama kiwango cha chini, mradi unapaswa kujaribu kujibu ripoti za tatizo muhimu na udhaifu. Mradi unaofuata kwa bidii nishani pengine unatengenezwa. Miradi yote na watu wana rasilimali zilizowekewa mipaka, na miradi ya kawaida lazima ikatae baadhi ya mabadiliko yaliyopendekezwa, hivyo rasilimali zilizowekewa mipaka na kukataa mapendekezo sio ishara ya mradi usiotekelezwa.

    Mradi unapojua kwamba hautatengenezwa tena, unapaswa kuweka kigezo hiki kama "Haikidhi" na utumie utaratibu sahihi ili kuwaonyesha wengine kwamba hautengenezwi. Kwa mfano, tumia "DEPRECATED" kama kichwa cha kwanza cha README yake, ongeza "DEPRECATED" karibu na mwanzo wa ukurasa wake wa nyumbani, ongeza "DEPRECATED" mwanzoni mwa maelezo ya mradi wa hifadhi ya msimbo, ongeza nishani isiyolindwa katika README yake na/au ukurasa wa nyumbani, iweke kama iliyolemewa katika hifadhi yoyote ya kifurushi (k.m., npm deprecate), na/au utumie mfumo wa alama wa hifadhi ya msimbo ili kuihifadhi (k.m., mpangilio wa "archive" wa GitHub, alama ya "archived" ya GitLab, hali ya "readonly" ya Gerrit, au hali ya mradi wa "abandoned" wa SourceForge). Majadiliano ya ziada yanaweza kupatikana hapa.

 Udhibiti wa Mabadiliko 9/9 ●

  • Hifadhi ya chanzo ya kudhibiti toleo ya hadharani


    Ya kutosha kwa nishani!

    Mradi LAZIMA uwe na hifadhi ya chanzo ya kudhibiti toleo ambayo inaweza kusomwa hadharani na ina URL. [repo_public]
    URL YAWEZA kuwa sawa na URL ya mradi. Mradi YAWEZA kutumia matawi ya faragha (yasiyo ya umma) katika hali maalum wakati mabadiliko hayajatolewa hadharani (k.m., kwa kurekebisha udhaifu kabla haujafichuliwa kwa umma).

    Repository on GitHub, which provides public git repositories with URLs.


    Ya kutosha kwa nishani!

    Hifadhi ya chanzo ya mradi LAZIMA ifuatilie mabadiliko yaliyofanywa, nani alifanya mabadiliko, na mabadiliko yalifanywa lini. [repo_track]

    Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.


    Ya kutosha kwa nishani!

    Ili kuwezesha ukaguzi wa ushirikiano, hifadhi ya chanzo ya mradi LAZIMA ijumuishe matoleo ya kati kwa ukaguzi kati ya matoleo; HAIPASWA kujumuisha matoleo ya mwisho tu. [repo_interim]
    Miradi YAWEZA kuchagua kuondoa matoleo maalum ya kati kutoka hifadhi zao za chanzo za umma (k.m., zile zinazorekebi udhaifu maalum usiokuwa wa umma, huenda zisitolewe hadharani, au zijumuishe nyenzo ambazo haziwezi kuwekwa kisheria na haziko katika toleo la mwisho).

    https://github.com/amiwrpremium/macontrol/blob/master/CHANGELOG.md


    Ya kutosha kwa nishani!

    INASHAURIWA kwamba programu ya kawaida ya udhibiti wa toleo iliyosambazwa itumike (k.m., git) kwa hifadhi ya chanzo ya mradi. [repo_distributed]
    Git haihitajiki kihususa na miradi inaweza kutumia programu ya udhibiti wa toleo iliyokusanyika (kama subversion) na sababu.

    Repository on GitHub, which uses git. git is distributed.


  • Unambari wa toleo wa kipekee


    Ya kutosha kwa nishani!

    Matokeo ya mradi LAZIMA yawe na kitambulisho cha kipekee cha toleo kwa kila toleo linalokusudiwa kutumiwa na watumiaji. [version_unique]
    Hii YAWEZA kukidhi kwa njia mbalimbali ikiwa ni pamoja na vitambulisho vya kuwasilisha (kama kitambulisho cha kuwasilisha cha git au kitambulisho cha seti ya mabadiliko cha mercurial) au nambari ya toleo (ikiwa ni pamoja na nambari za toleo zinazotumia uainishaji wa maana au mipango ya tarehe kama YYYYMMDD).

    https://github.com/amiwrpremium/macontrol/blob/master/release-please-config.json


    Ya kutosha kwa nishani!

    INASHAURIWA kwamba muundo wa nambari ya toleo ya Semantic Versioning (SemVer) au Calendar Versioning (CalVer) itumike kwa matoleo. INASHAURIWA kwamba wale wanaotumia CalVer wajumuishe thamani ya kiwango cha mdogo. [version_semver]
    Miradi kwa ujumla inapaswa kupendelea muundo wowote unaotarajiwa na watumiaji wao, k.m., kwa sababu ni muundo wa kawaida unaotumiwa na ikolojia yao. Ikolojia nyingi zinapendelea SemVer, na SemVer kwa ujumla hupendelewa kwa kiolesura cha programu ya programu (API) na zana za maendeleo ya programu (SDK). CalVer hutumiwa na miradi ambayo ni kubwa, ina idadi kubwa ya utegemezi ulioundwa kwa uhuru, ina upeo wa mara kwa mara unaobadilika, au ni ya muda muhimu. INASHAURIWA kwamba wale wanaotumia CalVer wajumuishe thamani ya kiwango cha mdogo, kwa sababu kujumuisha kiwango cha mdogo kunasaidia matawi yaliyotunzwa kwa wakati mmoja wakati wowote hilo linakuwa lazima. Miundo mingine ya nambari ya toleo inaweza kutumiwa kama nambari za toleo, ikiwa ni pamoja na vitambulisho vya kuwasilisha cha git au vitambulisho vya seti ya mabadiliko cha mercurial, mradi tu vikitambulisha matoleo kwa kipekee. Hata hivyo, baadhi ya mbadala (kama vitambulisho vya kuwasilisha cha git) vinaweza kusababisha matatizo kama vitambulisho vya toleo, kwa sababu watumiaji huenda wasiwe na uwezo wa kuamua kwa urahisi ikiwa wako na toleo la hivi karibuni. Muundo wa kitambulisho cha toleo unaweza kutokuwa wa maana kwa kutambulisha matoleo ya programu ikiwa wapokeaji wote wanaendesha toleo la hivi karibuni tu (k.m., ni msimbo wa tovuti moja au huduma ya mtandao ambayo inasasishwa mara kwa mara kupitia utoaji wa kuendelea).

    Ya kutosha kwa nishani!

    INASHAURIWA kwamba miradi itambulishe kila toleo ndani ya mfumo wao wa udhibiti wa toleo. Kwa mfano, INASHAURIWA kwamba wale wanaotumia git watambulishe kila toleo kwa kutumia lebo za git. [version_tags]

    https://github.com/amiwrpremium/macontrol/tags
    https://github.com/amiwrpremium/macontrol/releases


  • Maelezo ya kutolewa


    Ya kutosha kwa nishani!

    Mradi LAZIMA utoe, katika kila toleo, maelezo ya toleo ambayo ni muhtasari unaosomeka na binadamu wa mabadiliko makuu katika toleo hilo ili kuwasaidia watumiaji kuamua ikiwa wanapaswa kusasisha na athari ya kusasisha itakuwa nini. Maelezo ya toleo LAZIMA yasiwe matokeo ghafi ya kumbukumbu ya udhibiti wa toleo (k.m., matokeo ya amri ya "git log" si maelezo ya toleo). Miradi ambayo matokeo yake hayakusudiwa kutumika tena katika maeneo mengi (kama programu kwa tovuti moja au huduma) NA wanaotumia utoaji wa kuendelea WAWEZA kuchagua "N/A". (URL inahitajika) [release_notes]
    Maelezo ya toleo YAWEZA kutekelezwa kwa njia mbalimbali. Miradi mingi hutoa katika faili inayoitwa "NEWS", "CHANGELOG", au "ChangeLog", kwa hiari na viendelezi kama ".txt", ".md", au ".html". Kihistoria neno "change log" lilimaanisha kumbukumbu ya kila mabadiliko, lakini ili kukidhi vigezo hivi kinachohitajika ni muhtasari unaosomeka na binadamu. Maelezo ya toleo YAWEZA badala yake kutolewa na taratibu za mfumo wa udhibiti wa toleo kama mtiririko wa Matoleo ya GitHub.

    Non-trivial release notes file in repository: https://github.com/amiwrpremium/macontrol/blob/master/CHANGELOG.md.


    Ya kutosha kwa nishani!

    Maelezo ya toleo LAZIMA yatambulishe kila udhaifu wa muda wa kutekeleza uliojulikana hadharani uliorekebishwa katika toleo hili ambao tayari ulikuwa na mgawanyo wa CVE au sawa wakati toleo lilipobuniwa. Kigezo hiki kinaweza kuwekwa alama kama haihusiki (N/A) ikiwa watumiaji kwa kawaida hawawezi kwa vitendo kusasisha programu wao wenyewe (k.m., kama inavyokuwa kweli mara nyingi kwa masasisho ya kernel). Kigezo hiki kinatumika tu kwa matokeo ya mradi, si kwa utegemezi wake. Ikiwa hakuna maelezo ya toleo au hakujawa na udhaifu uliojulikana hadharani, chagua N/A. [release_notes_vulns]
    Kigezo hiki kinawasaidia watumiaji kuamua ikiwa sasisho fulani litarekebisha udhaifu ambao unajulikana hadharani, ili kuwasaidia watumiaji kufanya uamuzi wa habari kuhusu kusasisha. Ikiwa watumiaji kwa kawaida hawawezi kwa vitendo kusasisha programu wao wenyewe kwenye kompyuta zao, lakini badala yake lazima wategemee wapatanishi mmoja au zaidi kutekeleza sasisho (kama inavyokuwa mara nyingi kwa kernel na programu ya kiwango cha chini ambayo imefungwa na kernel), mradi unaweza kuchagua "haihusiki" (N/A) badala yake, kwani habari hii ya ziada haitakuwa ya msaada kwa watumiaji hao. Vivyo hivyo, mradi unaweza kuchagua N/A ikiwa wapokeaji wote wanaendesha toleo la hivi karibuni tu (k.m., ni msimbo wa tovuti moja au huduma ya mtandao ambayo inasasishwa mara kwa mara kupitia utoaji wa kuendelea). Kigezo hiki kinatumika tu kwa matokeo ya mradi, si kwa utegemezi wake. Kuorodhesha udhaifu wa utegemezi wote wa mpito wa mradi unakuwa mgumu kadiri utegemezi unavyoongezeka na kutofautiana, na haihitajiki kwani zana zinazochunguza na kufuatilia utegemezi zinaweza kufanya hivi kwa njia inayopanuka.

    https://github.com/amiwrpremium/macontrol/tags
    https://github.com/amiwrpremium/macontrol/releases


 Kuripoti 8/8 ●

  • Mchakato wa kuripoti hitilafu


    Ya kutosha kwa nishani!

    Mradi LAZIMA utoe mchakato kwa watumiaji kuwasilisha ripoti za hitilafu (k.m., kwa kutumia kifuatiliaji cha masuala au orodha ya barua pepe). (URL inahitajika) [report_process]

    Non-trivial SECURITY[.md] file found file in repository: https://github.com/amiwrpremium/macontrol/blob/master/SECURITY.md. [osps_do_02_01]


    Ya kutosha kwa nishani!

    Mradi UNAPASWA kutumia kifuatiliaji cha masuala kwa kufuatilia masuala ya mtu binafsi. [report_tracker]

    https://github.com/amiwrpremium/macontrol/issues


    Ya kutosha kwa nishani!

    Mradi LAZIMA uthibitishe wengi wa ripoti za hitilafu zilizowasilishwa katika miezi 2-12 iliyopita (ikiwemo); jibu halihitaji kuwa na marekebisho. [report_responses]

    Ya kutosha kwa nishani!

    Mradi UNAPASWA kujibu wengi (>50%) wa maombi ya maboresho katika miezi 2-12 iliyopita (ikiwemo). [enhancement_responses]
    Jibu LIWEZA kuwa 'hapana' au majadiliano kuhusu manufaa yake. Lengo ni kwamba kuwe na jibu fulani kwa baadhi ya maombi, ambayo inaonyesha kwamba mradi bado unaishi. Kwa madhumuni ya kigezo hiki, miradi haihitaji kuhesabu maombi ya bandia (k.m., kutoka kwa wafanyabiashara haramu au mifumo ya kiotomatiki). Ikiwa mradi hauendelei kufanya maboresho tena, tafadhali chagua "haijatimizwa" na jumuisha URL inayofanya hali hii kuwa wazi kwa watumiaji. Ikiwa mradi huwa na msongo wa maombi ya maboresho, tafadhali chagua "haijatimizwa" na eleza.

    Ya kutosha kwa nishani!

    Mradi LAZIMA uwe na kumbukumbu inayopatikana hadharani kwa ripoti na majibu kwa utaftaji wa baadaye. (URL inahitajika) [report_archive]

    https://github.com/amiwrpremium/macontrol/


  • Mchakato wa kuripoti udhaifu


    Ya kutosha kwa nishani!

    Mradi LAZIMA uchapishe mchakato wa kuripoti udhaifu kwenye tovuti ya mradi. (URL inahitajika) [vulnerability_report_process]
    Miradi iliyohifadhiwa kwenye GitHub INAPASWA kuzingatia kuwezesha kuripoti udhaifu wa usalama kwa faragha. Miradi kwenye GitLab INAPASWA kuzingatia kutumia uwezo wake wa kuripoti udhaifu kwa faragha. Miradi YAWEZA kutambulisha anwani ya barua pepe kwenye https://PROJECTSITE/security, mara nyingi katika muundo wa security@example.org. Mchakato huu wa kuripoti udhaifu UWEZA kuwa sawa na mchakato wake wa kuripoti hitilafu. Ripoti za udhaifu ZIWEZA kuwa za umma kila wakati, lakini miradi mingi ina utaratibu wa kuripoti udhaifu wa faragha.

    https://github.com/amiwrpremium/macontrol/blob/master/SECURITY.md


    Ya kutosha kwa nishani!

    Ikiwa ripoti za udhaifu wa faragha zinasaidiwa, mradi LAZIMA ujumuishe jinsi ya kutuma habari kwa njia ambayo inawekwa faragha. (URL inahitajika) [vulnerability_report_private]
    Mifano ni pamoja na ripoti ya kasoro ya faragha iliyowasilishwa kwenye wavuti kwa kutumia HTTPS (TLS) au barua pepe iliyosimbwa kwa kutumia OpenPGP. Ikiwa ripoti za udhaifu ni za umma kila wakati (kwa hiyo hakuna ripoti za udhaifu za faragha), chagua "haihusiki" (N/A).

    https://github.com/amiwrpremium/macontrol/blob/master/SECURITY.md


    Ya kutosha kwa nishani!

    Muda wa majibu ya awali ya mradi kwa ripoti yoyote ya udhaifu iliyopokelewa katika miezi 6 iliyopita LAZIMA uwe chini ya au sawa na siku 14. [vulnerability_report_response]
    Ikiwa hakujawa na udhaifu ulioripotiwa katika miezi 6 iliyopita, chagua "haihusiki" (N/A).

 Ubora 13/13 ●

  • Mfumo wa ujenzi unaofanya kazi


    Ya kutosha kwa nishani!

    Ikiwa programu iliyotengenezwa na mradi inahitaji ujenzi wa matumizi, mradi LAZIMA utoe mfumo wa kujenga ambao unaweza kujenga programu kiotomatiki kutoka kwa chanzo-msimbo. [build]
    Mfumo wa kujenga huamua ni hatua gani zinahitaji kutendeka ili kujenga tena programu (na kwa mpangilio gani), na kisha kutekeleza hatua hizo. Kwa mfano, inaweza kuomba kikusanyaji kukusanya fumbo-chanzo. Ikiwa inayoweza kutekelezwa imeundwa kutoka kwa fumbo-chanzo, lazima iwezeshe marekebisho kwenye fumbo-chanzo ya mradi na kisha itengeneze msasisho inayoweza kutekelezwa na marekebisho hayo. Ikiwa programu iliyotolewa na mradi unategemea maktaba ya nje, mfumo wa kujenga haina haja ya kujenga maktaba hizo za nje. Ikiwa hakuna haja ya kujenga chochote kutumia programu baada ya fumbo-chanzo kubadilishwa, chagua "haitumiki" (N / A).

    Non-trivial build file in repository: https://github.com/amiwrpremium/macontrol/blob/master/Makefile.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kuwa zana za kawaida zitumike kujenga programu. [build_common_tools]
    Kwa mfano, Maven, Ant, cmake, autotools, make, rake (Ruby), au devtools (R).

    Non-trivial build file in repository: https://github.com/amiwrpremium/macontrol/blob/master/Makefile.


    Ya kutosha kwa nishani!

    Mradi UNAPASWA kujengwa kwa kutumia zana za FLOSS pekee yake. [build_floss_tools]

    It cleanly satisfies this criterion:

    Written in Go — the official Go toolchain is BSD-licensed FLOSS.
    Build system is Make (Makefile) — GPL FLOSS.
    Lives in Git on GitHub — Git itself is GPL FLOSS.
    Linting via golangci-lint — GPL/MIT FLOSS.
    Released via GoReleaser + release-please — both MIT FLOSS.
    Targets macOS, but the build doesn't require Xcode's proprietary bits; go build cross-compiles for darwin/arm64 from any platform.


  • Seti ya majaribio otomatiki


    Ya kutosha kwa nishani!

    Mradi LAZIMA utumie angalau seti moja ya majaribio ya kiotomatiki ambayo imetolewa hadharani kama FLOSS (seti hii ya majaribio inaweza kutunzwa kama mradi tofauti wa FLOSS). Mradi LAZIMA uonyeshe wazi au uandike jinsi ya kuendesha seti za majaribio (k.m., kupitia hati ya uingizaji wa kuendelea (CI) au kupitia nyaraka katika faili kama BUILD.md, README.md, au CONTRIBUTING.md). [test]
    Mradi YAWEZA kutumia seti nyingi za majaribio ya kiotomatiki (k.m., moja inayoendesha haraka, dhidi ya nyingine ambayo ni ya kina zaidi lakini inahitaji vifaa maalum). Kuna mifumo mingi ya majaribio na mifumo ya kusaidia majaribio inayopatikana, ikiwemo Selenium (uendeshaji kiotomatiki wa kivinjari cha wavuti), Junit (JVM, Java), RUnit (R), testthat (R).

    1. Automated test suite under FLOSS license ✅
      The repo contains 48 Go test files (*_test.go) covering essentially every package — runner, config, keychain, capability, every domain module (battery, bluetooth, display, media, music, notify, power, sound, status, system, tools, wifi), and the Telegram handlers/callbacks. They use Go's standard testing package, which ships with the Go toolchain under a BSD-3-Clause license — unambiguously FLOSS. The tests themselves inherit the project's MIT license.
      There's also a fuzz test (FuzzDecode in internal/telegram/callbacks/), which is a nice extra — Go's built-in fuzzer is also FLOSS.

    2. Documentation of how to run them ✅
      Multiple, redundant places — any reviewer will find one:
      Makefile has both make test (go test ./...) and make lint test mentioned in the README's Development section.
      README.md explicitly shows make lint test under the Development heading on line 135.
      .github/workflows/ci.yml runs go test -race -coverprofile=coverage.out ./... on every push/PR, with a coverage matrix uploading to Codecov and Codacy (the badges on the README link to both dashboards).
      docs/development/testing.md exists as a dedicated testing doc, plus docs/development/ci.md documents the CI pipeline.
      CONTRIBUTING.md at the repo root is also present.


    Ya kutosha kwa nishani!

    Seti ya majaribio INAPASWA kuwa inaweza kuitwa kwa njia ya kawaida kwa lugha hiyo. [test_invocation]
    Kwa mfano, "make check", "mvn test", au "rake test" (Ruby).

    test_invocation — macontrol evidence

    The project satisfies this criterion. Tests are invoked using the standard Go convention:

    go test ./...

    This is the canonical Go test command and works directly from a fresh clone with no flags, environment setup, or custom scripts.

    Makefile (wraps the standard command, doesn't replace it):
    test: go test ./...
    test-race: go test -race -coverprofile=coverage.out ./...

    make test and make test-race are convenience aliases — the underlying command is exactly what a Go developer would type by reflex. A reviewer ignoring the Makefile entirely would still succeed by running go test ./....

    CI (.github/workflows/ci.yml) uses the same standard command:
    go test -race -coverprofile=coverage.out ./...

    Fuzz tests also use the canonical Go invocation:
    go test -run='^$' -fuzz=FuzzDecode -fuzztime=30s ./internal/telegram/callbacks/

    Summary: the project uses go test ./... (the standard Go invocation), exposes it through a conventional Makefile test target, and runs the same command in CI. No custom test runner, no proprietary harness, no project-specific learning curve required.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba seti ya majaribio ifuate wengi (au kwa kawaida wote) matawi ya msimbo, sehemu za kuingiza, na utendakazi. [test_most]

    test_most — macontrol evidence

    The project satisfies this suggested criterion with strong, enforced coverage of code branches, input fields, and functionality.

    Test surface area:

    • 48 *_test.go files against 96 non-test .go files — roughly a 1:2 test-to-source ratio, with every internal package having a corresponding test file.
    • Tests cover every domain module: battery, bluetooth, display, media, music, notify, power, sound, status, system, tools, wifi — plus runner, config, keychain, capability, version, and the telegram handlers/callbacks.
    • 30+ table-driven test blocks exercise multiple input cases per function — the standard Go pattern for branch and input-field coverage.
    • A fuzz test (FuzzDecode in internal/telegram/callbacks/data_fuzz_test.go) exercises the callback decoder against randomized input to catch edge-case branches; it runs in CI via go test -run='^$' -fuzz=FuzzDecode -fuzztime=30s.

    Coverage is measured and enforced, not just claimed:

    • CI runs go test -race -coverprofile=coverage.out ./... on every push/PR.
    • Coverage is uploaded to both Codecov and Codacy — both badges are visible at the top of README.md and link to public dashboards.
    • A coverage floor is enforced in CI via the cover-floor Make target, which runs go-test-coverage --config=./.testcoverage.yml.

    Coverage thresholds (from .testcoverage.yml):

    • Total project: 80%
    • Per package: 75%
    • Per file: 50%
    • internal/domain/status: 80% (package-specific override)
    • internal/telegram/telegramtest: 70% (test helper)
    • cmd/macontrol: 5% (entry point — covered by integration tests on a real Mac, not unit tests; documented in the config file)
    • cmd/macontrol/shim.go: 0% (tiny shim, documented)

    Notably the thresholds are intentionally set below current measured coverage (per the comment in .testcoverage.yml) so that regressions are caught without blocking every small change — meaning actual coverage exceeds these floors.

    Summary: the project doesn't just have tests — it measures branch/file/package coverage, publishes it on two public dashboards, enforces a per-package floor of 75% and a project floor of 80% in CI, and uses fuzz testing on the highest-risk parser (the callback data decoder). Documented exceptions (entry-point and shim files) are explicit and justified.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba mradi utekeleze ujumuishaji wendeleo (ambapo msimbo mpya au uliobadiishwa unajumuishwa mara kwa mara katika hifadhi ya msimbo ya kati na majaribio otomatiki hufanyika kwenye matokeo). [test_continuous_integration]

    test_continuous_integration — macontrol evidence

    The project satisfies this suggested criterion. CI is implemented via GitHub Actions, runs on every push and pull request, and integrates code into the central repository with a full battery of automated checks.

    CI configuration: .github/workflows/ci.yml

    Triggers:

    • push to master
    • pull_request targeting master
    • concurrency group cancels superseded runs to keep feedback fast

    Jobs that run on every change:

    1. Lint (ubuntu-latest)

      • golangci-lint at latest version

    2. Test (matrix: ubuntu-latest + macos-14)

      • go test -race -coverprofile=coverage.out ./...
      • Coverage uploaded as workflow artifact
      • Coverage floor enforced via go-test-coverage against .testcoverage.yml
      • Coverage published to Codecov and Codacy on every run

    3. Build (ubuntu-latest)

      • Cross-compiles the actual release target: GOOS=darwin GOARCH=arm64 CGO_ENABLED=0
      • Catches build regressions before merge

    4. Vulnerability scan (ubuntu-latest)

      • govulncheck ./... against the Go vulnerability database

    5. Fuzz (short, ubuntu-latest)

      • 30-second smoke fuzz on FuzzDecode (the callback parser — the only attacker-reachable parser before the whitelist gate)
      • Guards against newly-introduced panics on every PR

    Additional CI workflows in .github/workflows/:

    • codeql.yml — GitHub CodeQL static analysis
    • scorecards.yml — OpenSSF Scorecard checks
    • pr-title.yml — Conventional Commits enforcement on PR titles
    • release-please.yml — automated release PR generation
    • release.yml — GoReleaser pipeline on tag push

    Visible signals on the repository:

    • CI badge at the top of README.md links to the live workflow runs
    • codecov and Codacy coverage badges link to their public dashboards
    • OpenSSF Scorecard badge links to the public scorecard report

    Summary: every push and PR triggers parallel jobs covering lint, test (on Linux and macOS), cross-compile build, vulnerability scan, and fuzz testing. Coverage is measured, enforced against a per-package floor, and published to two public dashboards. Additional scheduled/triggered workflows handle CodeQL, OpenSSF Scorecard, and the release pipeline. This goes well beyond the suggested criterion.


  • Upimaji wa utendaji mpya


    Ya kutosha kwa nishani!

    Mradi LAZIMA uwe na sera ya jumla (rasmi au la) kwamba utendakazi mkubwa mpya unavyoongezwa kwenye programu inayotengenezwa na mradi, majaribio ya utendakazi huo unapaswa kuongezwa kwenye seti ya majaribio otomatiki. [test_policy]
    Mradi uwe na sera tu, hata kwa maneno ya mdomo, inayosema wasanidi programu wanapaswa kuongeza majaribio kwenye seti ya majaribio otomatiki kwa utendakazi mkubwa mpya, chagua "Kukidhi."

    test_policy — macontrol evidence

    The project has an explicit, documented policy that new functionality must come with tests. The policy is enforced both in writing and through CI gating.

    1. Documented policy

    CONTRIBUTING.md instructs every contributor to run make lint test before opening a PR, and the PR template/process treats failing tests as a blocker.

    docs/development/adding-a-capability.md is a step-by-step guide for adding a new feature (a "capability"). It is structured as a 6-step checklist, and step 2 of every new capability is explicitly "Domain test" — the guide includes a worked example showing both happy-path and error-path tests using runner.Fake, with the note that the result "Should pass with 100% coverage on the two test functions." Step 5 of the same checklist is "Test the handler." The file table at the top of the guide lists the test files alongside the source files as required deliverables for any new capability, not as optional extras.

    docs/development/testing.md documents the test infrastructure (runner.Fake for subprocess mocking, telegramtest.NewBot for the Telegram API) so contributors have no excuse not to write tests — the helpers needed to test any new domain or handler already exist and are documented.

    1. Policy enforcement in CI

    The policy isn't aspirational — it's enforced:

    • Every push and PR runs go test -race -coverprofile=coverage.out ./... on both Linux and macOS.
    • A coverage floor is enforced via go-test-coverage against .testcoverage.yml: 80% total, 75% per package, 50% per file. New code that drops coverage below those floors fails CI.
    • Coverage is published to Codecov and Codacy on every run, so any drop is visible in the PR review.
    • A 30-second fuzz test of the callback decoder runs on every PR.
    1. Cultural signal

    Conventional Commits (enforced by a CI job on PR titles) include test as a first-class commit type, and feat commits in the changelog routinely land alongside their corresponding tests. The CHANGELOG.md history shows tests added in the same release as the features they cover.

    Summary: the project has an explicit written policy in CONTRIBUTING.md and the capability-adding guide that requires tests for new functionality, backed by ready-made test helpers (runner.Fake, telegramtest.NewBot), and enforced by a CI-gated coverage floor that blocks PRs which regress coverage. This satisfies the criterion well beyond the "general policy, formal or not" bar.


    Ya kutosha kwa nishani!

    Mradi LAZIMA uwe na ushahidi kwamba test_policy ya kuongeza majaribio imefuatwa katika mabadiliko makubwa ya hivi karibuni kwenye programu inayotengenezwa na mradi. [tests_are_added]
    Utendakazi mkubwa kawaida ungetajwa katika maelezo ya toleo. Ukamilifu hauhitajiki, ni ushahidi tu kwamba majaribio kawaida huongezwa kimakosa kwenye seti ya majaribio otomatiki utendakazi mkubwa mpya unavyoongezwa kwenye programu inayotengenezwa na mradi.

    tests_are_added — macontrol evidence

    The most recent major changes to macontrol show the test_policy being followed consistently. Every recent feature PR ships with tests for the new code, and dedicated test-only PRs have been used to raise coverage proactively.

    Most recent feature: feat(bot): add 🎵 Music category (#91, latest 0.7.0 release)

    This is a large feature touching 24 files, +2,869 lines. Of those 24 files, 6 are *_test.go files added or expanded alongside the new code:

    internal/capability/detect_test.go | 37 lines changed
    internal/domain/music/music_test.go | 264 lines added (new file)
    internal/telegram/flows/seek_test.go | 95 lines added (new file)
    internal/telegram/handlers/mus_test.go | 235 lines added (new file)
    internal/telegram/keyboards/mus_test.go | 236 lines added (new file)
    internal/telegram/musicrefresh/refresher_test.go | 312 lines added (new file)

    Every new production file in this PR landed with a corresponding _test.go in the same commit:
    music.go ↔ music_test.go
    seek.go ↔ seek_test.go
    mus.go (handlers) ↔ mus_test.go
    mus.go (keyboards) ↔ mus_test.go
    refresher.go ↔ refresher_test.go

    This exactly matches the policy in docs/development/adding-a-capability.md, which mandates a domain test file and a handler test alongside any new capability.

    Pattern across the last several feat commits:

    feat(bot): Timezone picker (01b2ae5) → +tools_test.go, +remaining_test.go, +keyboards_test.go
    feat(bot): Shortcuts list (a1a2be1) → +remaining_test.go, +keyboards_test.go
    feat(bot): DNS presets submenu (98646fb) → +remaining_test.go, +keyboards_test.go
    feat(bot): Disks redesign (ef77b3c) → +tools_test.go, +remaining_test.go, +keyboards_test.go

    Every single one of the most recent feat(bot) PRs in git log includes test additions in the same commit. None landed bare.

    Dedicated test-improvement work:

    test: expand unit coverage from 73.9% to 85.0% across the repo (#76, commit 51e7d31)
    test(callbacks): add Go native fuzz tests for Decode (#89, commit 0bb56cc)

    These two PRs show the policy is treated as an active concern, not a checkbox — the maintainer has merged standalone PRs whose only purpose is to raise coverage and add fuzz testing.

    Enforcement signal:

    CI's coverage floor (.testcoverage.yml: 80% total, 75% per package) blocks merges that drop coverage below the threshold. The fact that recent feature PRs all merged green is itself evidence that the feature code was covered by the tests added in the same PR — otherwise the floor check would have failed.

    Summary: the most recent major change (the Music category) added 6 test files alongside the 18 new/edited production files, matching the policy in docs/development/adding-a-capability.md exactly. The same pattern holds for every prior feat(bot) PR in the history. The project also merges dedicated test-improvement PRs (#76, #89). The criterion is satisfied with a clear, traceable record.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba sera hii ya kuongeza majaribio (angalia test_policy) iwe imeandikwa katika maelekezo ya mapendekezo ya mabadiliko. [tests_documented_added]
    Hata hivyo, hata sheria isiyo rasmi inakubaliwa mradi majaribio yaongezwe kimakosa.

    tests_documented_added — macontrol evidence

    The project documents the test-adding policy in multiple change-proposal-facing locations, satisfying this suggested criterion.

    1. Pull Request template (.github/PULL_REQUEST_TEMPLATE.md)

    GitHub auto-loads this template into every new PR's description box. It contains a "Test plan" section with the policy as an explicit checkbox the contributor must tick:

    Test plan

    • make lint test passes locally
    • New/changed code has unit tests
    • Verified on macOS (version / chip: … )
    • If permissions changed: updated docs/permissions.md
    • If new capability: added to README feature table

    The "New/changed code has unit tests" line is the policy stated directly in the change-proposal interface — every contributor sees it the moment they open a PR.

    1. CONTRIBUTING.md

    The contributor workflow makes running tests a required pre-PR step:

    1. Run checks locally before pushing:
         make lint test

    The "Adding a new capability" section lists the required files for a new capability and step 6 explicitly mandates tests:

    1. Write a domain test using the runner.Fake helper and a
      keyboard-layout test.

    2. docs/development/adding-a-capability.md

    A dedicated, full-length guide for change proposals that add new functionality. It treats tests as a structural requirement, not a suggestion:

    • The file table at the top lists _test.go files alongside source files as required deliverables.
    • Step 2 of every new capability is "Domain test", with a worked example covering both happy-path and error-path tests.
    • Step 5 is "Test the handler".
    • The guide notes that the worked example "Should pass with 100% coverage on the two test functions."
    1. docs/development/testing.md

    Documents the test infrastructure (runner.Fake, telegramtest.NewBot) so contributors know exactly how to satisfy the policy. The helpers needed to test any new domain or handler are pre-built and documented.

    1. Conventional Commits

    CONTRIBUTING.md lists test as a first-class commit type, signaling that test-only changes are an expected, encouraged contribution.

    Summary: the test-adding policy is documented in the PR template (the most direct change-proposal surface), in CONTRIBUTING.md (the canonical contributor doc), and in two dedicated development guides (adding-a-capability.md and testing.md). A contributor cannot open a PR without seeing the "New/changed code has unit tests" checkbox in their PR body. This goes beyond the suggested bar.


  • Bendera za maonyo


    Ya kutosha kwa nishani!

    Mradi LAZIMA uwashe bendera moja au zaidi za onyo la mkusanyaji, hali ya lugha "salama", au tumia zana tofauti ya "linter" kutafuta makosa ya ubora wa msimbo au makosa rahisi ya kawaida, ikiwa kuna angalau zana moja ya FLOSS inaweza kutekeleza kigezo hiki katika lugha iliyochaguliwa. [warnings]
    Mifano ya bendera za onyo la mkusanyaji ni pamoja na gcc/clang "-Wall". Mifano ya hali ya lugha "salama" ni pamoja na JavaScript "use strict" na perl5's "use warnings". Zana tofauti ya "linter" ni zana tu inayoangalia msimbo wa chanzo kutafuta makosa ya ubora wa msimbo au makosa rahisi ya kawaida. Hizi kawaida huwashwa ndani ya msimbo wa chanzo au maelekezo ya ujenzi.

    warnings — macontrol evidence

    The project satisfies this criterion with a comprehensive linter configuration enforced in CI.

    Primary linter: golangci-lint (FLOSS, GPL-3.0)

    The repository ships an explicit configuration at .golangci.yml that enables 13 linters covering correctness, security, and style — all are themselves FLOSS:

    • errcheck — unchecked errors
    • govet — go vet, the official correctness checker
    • ineffassign — ineffective assignments
    • staticcheck — comprehensive static analysis (correctness + simplification)
    • unused — unused code
    • misspell — common misspellings
    • gocritic — opinionated bug-pattern checks
    • revive — replacement for golint, with the exported and package-comments rules explicitly enabled (enforces godoc on exported symbols)
    • bodyclose — HTTP response bodies that must be closed
    • nolintlint — catches stale or malformed //nolint directives
    • unparam — unused function parameters
    • prealloc — slices that could be preallocated
    • gosec — security-focused checks (with G204 excluded since subprocess invocation is the project's purpose, documented inline)

    Formatters (gofumpt + goimports) are also enforced, with project-local import grouping configured.

    Test files have a narrowly scoped exclusion (gosec, unparam, gocritic) which is the standard pattern for Go projects — these linters produce noise on test scaffolding.

    Enforcement:

    • Makefile target: make lint → golangci-lint run. make lint-fix for auto-fixable issues. make all runs lint + test + build.
    • CI: .github/workflows/ci.yml has a dedicated lint job that runs golangci-lint on every push and pull request. It runs in parallel with the test job, so regressions are caught before merge.
    • CONTRIBUTING.md instructs every contributor: make lint test before opening a PR.

    Additional static analysis layers:

    • govulncheck (golang.org/x/vuln) — runs as the vuln CI job on every push/PR via govulncheck ./...
    • CodeQL (.github/workflows/codeql.yml) — GitHub's semantic code analysis on the repo
    • OpenSSF Scorecard (.github/workflows/scorecards.yml) — supply-chain best-practice scoring
    • The Go compiler itself emits warnings/errors for unused imports and variables, and go vet is included via the govet linter above

    All four of these tools are FLOSS.

    Summary: the project enables 13 FLOSS linters via golangci-lint with an explicit checked-in configuration, runs them in CI on every push and PR, and layers govulncheck + CodeQL + Scorecard on top. The make lint target makes the same checks runnable locally, and the contributor workflow requires it before opening a PR. The criterion is satisfied well beyond the minimum.


    Ya kutosha kwa nishani!

    Mradi LAZIMA ukabiliane na maonyo. [warnings_fixed]
    Haya ni maonyo yaliyotambuliwa na utekelezaji wa kigezo cha warnings. Mradi unapaswa kurekebisha maonyo au kuyaweka alama katika msimbo wa chanzo kama hasi za uwongo. Kwa kawaida pasingeweza kuwa na maonyo, lakini mradi YAWEZA kukubali baadhi ya maonyo (kawaida chini ya onyo 1 kwa mistari 100 au chini ya maonyo 10).

    warnings_fixed — macontrol evidence

    The project actively addresses warnings rather than ignoring them. Multiple lines of evidence:

    1. CI fails on warnings, blocking merges

    The lint job in .github/workflows/ci.yml runs golangci-lint on every push and PR. golangci-lint defaults to a non-zero exit on any finding, so any unaddressed warning fails CI and blocks merge. Recent feature PRs (#91 Music, #82 handler split, #67 Timezone, #60 Shortcuts) all merged green, meaning each was warning-clean by the time it landed.

    1. Documented history of fixing warnings, not suppressing them

    Direct evidence in the commit log:

    caa55d6 fix(ci): resolve 50 golangci-lint v2 findings
    34182c8 fix(ci): upgrade lint action and Go toolchain to pass checks
    d0b3eaf docs: comprehensive godoc for all production code + enable strict lint (#77)
    c4474e8 docs: thorough godoc rewrite with structured sections (#78)
    ed45c0e chore: quiet markdownlint rules pre-PR1 wasn't enforcing (#84)

    The "resolve 50 golangci-lint v2 findings" commit is particularly strong evidence. Its body itemises every fix:

    • errcheck (14) → explicit _ = on intentionally discarded errors;
      deferred handlers wrapped to discard returns explicitly
    • gofumpt (11) + goimports (1) → formatter auto-fix pass
    • staticcheck (10) → QF1012 fmt.Fprintf simplifications, SA1019 deprecated
      API replacements (EnvVarIsNotSetError → VarIsNotSetError)
    • gosec (5) → directory modes tightened 0o755 → 0o750, plist 0o644 → 0o600
    • gocritic (2) → singleCaseSwitch collapsed; exitAfterDefer fixed with
      explicit cancel()
    • prealloc (3) → slice capacities sized upfront

    These are real code changes, not ignore-list additions.

    1. Disciplined use of suppressions

    A repo-wide grep finds only 3 //nolint directives across the entire codebase:

    internal/domain/tools/tz_country.go:58
    os.ReadFile(path) //nolint:gosec // G304: path is from a constant allowlist

    internal/telegram/musicrefresh/refresher.go:199
    context.WithCancel(ctx) //nolint:gosec // cancel stored in session.cancel;
    called by Stop and run's defer

    cmd/macontrol/daemon.go:100
    //nolint:gocritic // explicit cancel() above flushes the context before exit

    Each is narrow (single line, specific linter named) and carries an inline justification. The nolintlint linter is also enabled in .golangci.yml, which catches stale, unused, or unjustified nolint directives — meaning suppressions themselves are policed.

    The .golangci.yml has exactly one global exclusion (gosec G204 — subprocess invocation), and it's documented in a comment ("Subprocess call is the whole point of this project"). Test files have a narrowly scoped exclusion of gosec/unparam/gocritic, the standard Go pattern.

    1. Refactors driven by warnings

    9f045d2 refactor: split overgrown handlers and table-drive parsers (#82)

    The release notes for the Music feature (#91) explicitly call out two refactor steps done to satisfy Codacy findings:

    • refactor(keyboards): split MusicCaption into per-section helpers (Codacy)
    • refactor(music): split tickOnce into snapshot + edit-media helpers (Codacy)

    So warnings from the secondary scanner (Codacy) are also being acted on, not just dismissed.

    1. Strict-lint regime expanded over time

    Commit d0b3eaf ("comprehensive godoc for all production code + enable strict lint") shows the bar being raised: revive's exported and package-comments rules were enabled, then the codebase was brought into compliance by writing godoc for every exported symbol. This is the opposite of the anti-pattern of relaxing rules to make warnings disappear.

    Summary: warnings are surfaced by golangci-lint (13 linters) + govulncheck + CodeQL + Codacy, blocked at the CI gate, addressed in dedicated fix commits with itemised release notes, and only suppressed in 3 narrow places — each with a written justification, all policed by nolintlint. The criterion is satisfied with a strong, traceable record.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba miradi iwe na ukali mkubwa sana na maonyo katika programu inayotengenezwa na mradi, ambapo ni ya vitendo. [warnings_strict]
    Baadhi ya maonyo hayawezi kuwashwa kwa ufanisi kwenye miradi fulani. Kinachohitajika ni ushahidi kwamba mradi unajitahidi kuwasha bendera za onyo ambapo inaweza, ili makosa yagundulika mapema.

    warnings_strict — macontrol evidence

    The project takes a maximally strict posture on warnings, well within the "where practical" qualifier of this suggested criterion.

    1. Strict golangci-lint configuration (.golangci.yml)

    issues:
    max-issues-per-linter: 0
    max-same-issues: 0

    These two settings disable golangci-lint's default deduplication caps. By default golangci-lint shows only the first 50 findings per linter and the first 3 of each kind; setting both to 0 means every finding is surfaced. This is the strict-mode setting — the project wants to see all warnings, not a sampled summary.

    1. Strict linter selection with default: none

    linters:
    default: none
    enable: [errcheck, govet, ineffassign, staticcheck, unused, misspell,
    gocritic, revive, bodyclose, nolintlint, unparam, prealloc, gosec]

    default: none means no linters run unless explicitly enabled — so the active set is deliberate, not accidental. The 13 enabled linters include the strictest commonly-used ones:

    • staticcheck (covers SA, ST, S, QF check categories — the gold-standard Go static analyser)
    • gosec (security)
    • gocritic (opinionated bug-pattern checks beyond go vet)
    • revive with exported and package-comments rules explicitly enabled — these enforce godoc on every exported symbol and every package, a notably strict bar
    • nolintlint (polices the suppressions themselves — stale or unjustified //nolint directives are themselves warnings)
    1. Minimal, justified exclusions

    The configuration suppresses almost nothing:

    • One global exclusion: gosec G204 (subprocess invocation), with an inline comment explaining why ("Subprocess call is the whole point of this project"). Without this the entire project would be one giant warning, since shelling out to pmset/networksetup/osascript is its purpose.
    • Test files exclude only gosec, unparam, gocritic — the standard Go pattern, since these produce noise on test scaffolding and assertion helpers.
    • generated: lax — generated files are excluded from lint, the standard convention.

    There are no broad path exclusions, no per-linter rule disables, no severity downgrades. The configuration is roughly 50 lines and contains nothing that softens the rules.

    1. Strict bars layered on top of golangci-lint
    • govulncheck runs in CI as a separate vuln job — any known-vulnerable dependency or stdlib usage fails the build.
    • CodeQL (.github/workflows/codeql.yml) — semantic analysis on every push.
    • OpenSSF Scorecard (.github/workflows/scorecards.yml) — supply-chain best-practice scoring published publicly.
    • Codacy + Codecov dashboards — third-party static analysis with public badges.
    • gofumpt (stricter than gofmt) and goimports (with local-prefix grouping enforced) run as formatters — formatting drift is a CI failure.
    • A 30-second fuzz test (FuzzDecode) runs on every PR.
    • Race detector enabled in CI tests: go test -race.
    1. Strict bar raised over time, not lowered

    The history shows the project tightening, not loosening, its strictness:

    d0b3eaf docs: comprehensive godoc for all production code + enable strict lint (#77)
    c4474e8 docs: thorough godoc rewrite with structured sections (#78)
    caa55d6 fix(ci): resolve 50 golangci-lint v2 findings

    The "enable strict lint" commit turned on revive's exported and package-comments rules and then brought the entire codebase into compliance — the opposite of the anti-pattern of relaxing rules to make warnings disappear.

    1. Evidence the strict bar is held in practice

    A repo-wide grep finds only 3 //nolint directives across the codebase. Each is single-line, names the specific linter being suppressed, and carries an inline justification. nolintlint enforces this format. Three narrow, justified suppressions across ~96 production .go files is a notably tight ratio.

    The macOS-target build is also configured strictly:

    GOFLAGS ?= -trimpath
    LDFLAGS ?= -s -w …
    CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" …

    -trimpath removes filesystem path leakage, and -s -w strips debug info from release binaries.

    1. Practical limits, honestly handled

    The "where practical" qualifier matters here. macontrol is a subprocess-orchestration daemon; gosec G204 (subprocess with non-constant input) cannot be globally satisfied because the project's purpose is to run macOS CLIs. The maintainer suppresses G204 globally with a documented justification rather than littering the code with per-call suppressions or pretending it's not an issue. That's the right kind of pragmatic strictness — strict everywhere it's practical, explicitly bounded where it isn't.

    Summary: the project enables 13 linters with default: none, sets max-issues caps to 0 to surface every finding, enforces godoc on every exported symbol via revive, layers govulncheck + CodeQL + Scorecard + Codacy on top, uses gofumpt (stricter than gofmt), runs tests with -race, fuzzes the highest-risk parser, and has a documented history of raising the bar (enable strict lint → fix the resulting 50 findings) rather than lowering it. Only 3 narrowly justified //nolint suppressions exist in the entire codebase. The criterion is satisfied at the strong end of the spectrum.


 Usalama 16/16 ●

  • Maarifa ya maendeleo yenye usalama


    Ya kutosha kwa nishani!

    Mradi LAZIMA uwe na angalau msanidi mmoja mkuu anayejua jinsi ya kuunda programu salama. (Angalia 'maelezo' kwa mahitaji halisi.) [know_secure_design]
    Hii inahitaji kuelewa kanuni zifuatazo za muundo, ikiwa ni pamoja na kanuni 8 kutoka Saltzer na Schroeder:
    • uchumi wa utaratibu (weka muundo kuwa rahisi na mdogo iwezekanavyo, k.m., kwa kupitisha urahisishaji wa kufunga)
    • mipangilio ya kuzuia makosa (maamuzi ya kuingia yanapaswa kukataa kwa chaguo-msingi, na usakinishaji wa miradi unapaswa kuwa salama kwa chaguo-msingi)
    • kikuu cha kati kikamilifu (kuingia kote kunaweza kuwekwa kikomo lazima kufanyiwa ukaguzi wa mamlaka na kutowezesha kuvukwa)
    • muundo wazi (taratibu za usalama hazipaswi kutegemea ujinga wa mshambuliaji wa muundo wake, lakini badala yake kwenye habari iliyolindwa na kubadilishwa kwa urahisi kama funguo na nywila)
    • kutenganisha kwa upendeleo (kwa kawaida, ufikiaji kwa vitu muhimu unapaswa kutegemea zaidi ya sharti moja, ili kushinda mfumo mmoja wa ulinzi hautawasha ufikiaji kamili. K.m., uthibitishaji wa vipengele vingi, kama vile kuhitaji nywila na ishara za vifaa, ni imara zaidi kuliko uthibitishaji wa kipengele kimoja)
    • upendeleo mdogo zaidi (michakato inapaswa kufanya kazi na upendeleo mdogo zaidi unaohitajika)
    • utaratibu wa kawaida mdogo zaidi (muundo unapaswa kupunguza utaratibu wa kawaida kwa zaidi ya mtumiaji mmoja na kutegemewa na watumiaji wote, k.m., saraka za mafaili ya muda)
    • kukubalika kwa kisaikolojia (kiolesura cha binadamu lazima kiwe kimeundwa kwa urahisi wa matumizi - kuunda kwa "mshangao mdogo" kunaweza kusaidia)
    • uso wa shambulio uliowekewa mipaka (uso wa shambulio - seti ya sehemu tofauti ambapo mshambuliaji anaweza kujaribu kuingia au kutoa data - unapaswa kuwekwa mipaka)
    • uthibitishaji wa ingizo na orodha zinazokubalika (pembejeo kawaida zinapaswa kuangaliwa ili kuamua kama ni halali kabla ya kukubalika; uthibitishaji huu unapaswa kutumia orodha zinazokubalika (zinazokubali tu thamani zinazojulikana-nzuri), siyo orodha zinazokana (zinaozojaribu kuorodhesha thamani zinazojulikana-mbaya)).
    "Msanidi mkuu" katika mradi ni mtu yeyote ambaye anajua msingi wa msimbo wa mradi, ana faraja kufanya mabadiliko kwake, na anatambuliwa hivyo na washiriki wengine wengi katika mradi. Msanidi mkuu kawaida atafanya michango mingi kwa mwaka uliopita (kupitia msimbo, nyaraka, au kujibu maswali). Wasanidi kawaida wangeweza kuchukuliwa wasanidi wakuu ikiwa walianzisha mradi (na hawajatoka kwenye mradi zaidi ya miaka mitatu iliyopita), wana chaguo la kupokea habari kwenye kituo cha kuripoti udhaifu wa kibinafsi (ikiwa kuna), wanaweza kukubali ahadi kwa niaba ya mradi, au kufanya matoleo ya mwisho ya programu ya mradi. Ikiwa kuna msanidi mmoja tu, mtu huyo ndiye msanidi mkuu. Vitabu vingi na kozi zinapatikana kukusaidia kuelewa jinsi ya kuunda programu salama zaidi na kujadili muundo. Kwa mfano, kozi ya Misingi ya Maendeleo ya Programu Salama ni seti huru ya kozi tatu zinazoeleza jinsi ya kuunda programu salama zaidi (ni bure ukiifanyia ukaguzi; kwa ada ya ziada unaweza kupata cheti kuthibitisha ulijifunza nyenzo).

    know_secure_design — macontrol evidence

    The primary developer (@amiwrpremium) demonstrates secure-design knowledge across every dimension the criterion lists.

    1. Written threat model

    docs/security/ contains a dedicated threat model. SECURITY.md documents scope (daemon, CLI, LaunchAgent plist, sudoers template, Homebrew formula, install.sh), out-of-scope (attacks already holding the bot token, upstream Apple bugs), private disclosure via GitHub Security Advisories, and SLAs (72h ack, ≤30d patch). A written threat model with named boundaries is itself a secure-design artifact.

    1. Secure defaults
    • No inbound port — outbound long-poll only. Eliminates the entire class of inbound-network attacks.
    • Hard Telegram-user-ID whitelist; non-whitelisted updates dropped silently (no enumeration via differentiated errors).
    • No /sh escape hatch — only named commands. A leaked token cannot be turned into arbitrary code execution.
    • Bot token stored in macOS Keychain, never in config files or env vars.
    • Commit caa55d6 proactively tightened file modes in response to gosec findings: directories 0o755 → 0o750, LaunchAgent plist 0o644 → 0o600.
    1. Defense in depth

    Six independent layers, each assuming the previous bypassed:

    L1: Telegram user-ID whitelist (auth)
    L2: Named-command surface (no shell escape)
    L3: runner.Runner interface (constrained subprocess invocation)
    L4: Narrow sudoers entry (sudoers.d/macontrol.sample)
    L5: macOS TCC gates on camera/screen/microphone
    L6: Keychain ACL bound to binary path

    1. Least privilege
    • Sudoers is a narrow allowlist, not NOPASSWD: ALL.
    • runner.Runner carries an explicit Sudo bool per call — sudo is opt-in per command, not ambient.
    • Daemon runs as the user's LaunchAgent, not root.
    • Keychain ACL binding to binary path means another binary running as the same user must trigger a fresh user consent prompt.
    1. Input validation on the attacker-reachable surface

    The Telegram callback_data string is the only attacker-reachable parser before the whitelist gate. The developer:

    • Wrote a Go native fuzz test (FuzzDecode in internal/telegram/callbacks/data_fuzz_test.go), commit 0bb56cc.
    • Runs it 30s on every PR via the fuzz-short CI job.
    • Documented in the CI workflow comment that it is "the only attacker-reachable parser before the whitelist gate" — showing pinpointed threat awareness, not blanket fuzzing.
    1. Avoiding common attack classes
    • Command injection: subprocess invocation through runner.Runner with separate Name + Args fields, never string concatenation. The Args-not-shell pattern is what makes the global gosec G204 suppression safe.
    • Path traversal: the one os.ReadFile from a non-constant path (tools/tz_country.go) checks against an allowlist; the inline //nolint:gosec // G304: path is from a constant allowlist shows the finding was read, classified, and mitigated.
    • Race conditions: go test -race in CI; musicrefresh uses an explicit cancel-stored-in-session lifecycle pattern.
    • Supply-chain: every third-party Action and go-installed tool is pinned to a commit SHA (commits de4e7aa, 08216c6, fdbe795). govulncheck on every PR.
    1. Secret handling
    • Token only ever held in the macOS Keychain via internal/keychain/, with a dedicated test file.
    • Keychain ACL is binary-path-bound — a foreign binary triggers a macOS UI prompt rather than silent re-read.
    • CI secrets use GitHub's redacted ${{ secrets.X }} mechanism; no inlined credentials anywhere.
    1. Secure SDLC

    CodeQL on every push, OpenSSF Scorecard publicly scored, govulncheck on every PR, 13 linters via golangci-lint including gosec, race detector in CI, Dependabot weekly on gomod + github-actions, Conventional Commits + squash-merge for clean audit trail, private vulnerability disclosure channel.

    1. Evidence of considered (not templated) thinking

    The author maintains a sibling project, shellboto, for Linux VPS — with a different security model (pty-backed shell, SHA-256 hash-chained audit logs, per-user RBAC). Choosing different controls for different threat surfaces shows threat-model thinking, not a single template applied everywhere.

    1. Trust boundaries surfaced to users

    The README disclaimer enumerates the trust anchors users accept: the daemon's capabilities, the bot token + whitelist as the auth boundary, and transitive trust in Telegram/Apple/Homebrew. Articulating the trust model in user-facing docs is itself a secure-design practice.

    Summary: written threat model with scope boundaries; secure defaults (no inbound port, named commands only, tightened file modes); six-layer defense in depth; least privilege (narrow sudoers, per-call Sudo bool, non-root); fuzz-tested input validation pinpointed at the attacker-reachable parser; injection-resistant subprocess invocation; Keychain-based secret storage with binary-path ACL; full secure SDLC (CodeQL, Scorecard, govulncheck, gosec, race detector, Dependabot, pinned actions). The criterion is satisfied.


    Ya kutosha kwa nishani!

    Angalau mmoja wa wasanidi wakuu wa mradi LAZIMA wajue aina za kawaida za makosa ambayo husababisha udhaifu katika aina hii ya programu, pamoja na angalau mbinu moja ya kukabiliana au kupunguza kila moja. [know_common_errors]
    Mifano (kulingana na aina ya programu) ni pamoja na uvamizi wa SQL, uvamizi wa OS, mtiririko wa kipengele cha kawaida, uandishi wa tovuti-tofauti, uthibitishaji unaokosekana, na uidhinishaji unaokosekana. Angalia CWE/SANS top 25 au OWASP Top 10 kwa orodha zinazotumika kawaida. Vitabu vingi na kozi zinapatikana kukusaidia kuelewa jinsi ya kuunda programu salama zaidi na kujadili makosa ya kawaida ya utekelezaji ambayo husababisha udhaifu. Kwa mfano, kozi ya Misingi ya Maendeleo ya Programu Salama ni seti huru ya kozi tatu zinazoeleza jinsi ya kuunda programu salama zaidi (ni bure ukiifanyia ukaguzi; kwa ada ya ziada unaweza kupata cheti kuthibitisha ulijifunza nyenzo).

    know_common_errors — macontrol evidence

    Common vulnerability classes for a network-connected, subprocess-orchestrating macOS daemon, with the mitigation applied in macontrol:

    1. Command / subprocess injection
      Subprocess goes through runner.Runner with separate Name (string) and Args ([]string) fields, passed directly to exec.Cmd. No sh -c, no string interpolation. The runner.Fake test mock asserts on the parsed (Name, Args) tuple, proving the production form.

    2. Privilege escalation via overbroad sudo
      sudoers.d/macontrol.sample is a narrow allowlist, not NOPASSWD: ALL. runner.Runner carries an explicit Sudo bool per call — sudo is opt-in per invocation, not ambient.

    3. Authentication bypass
      Hard Telegram-user-ID whitelist sits in front of the command surface. Non-whitelisted updates dropped silently (no user enumeration). A leaked token alone cannot drive the bot — the attacker also needs a whitelisted user-ID.

    4. RCE via inbound network exposure
      No inbound port. Telegram long-poll over outbound HTTPS only. Eliminates the entire inbound-RCE class.

    5. Untrusted-input parsing (fuzz-class bugs)
      FuzzDecode (internal/telegram/callbacks/data_fuzz_test.go) runs 30s on every PR. The CI comment identifies callbacks.Decode as "the only attacker-reachable parser before the whitelist gate" — fuzz coverage was deliberately aimed at the single highest-risk parser. Commit 0bb56cc.

    6. Path traversal
      The one os.ReadFile with a non-constant path (tools/tz_country.go) reads from a constant allowlist. The inline //nolint:gosec // G304: path is from a constant allowlist shows the gosec finding was read by number and mitigated.

    7. Credential leakage at rest
      Bot token + whitelist live in the macOS Keychain (internal/keychain), not config files or env vars. Keychain ACL bound to binary path — foreign binaries trigger a fresh user consent prompt.

    8. Credential leakage in repo / CI logs
      .gitignore excludes .env*, *.pem, *.key. CI secrets read via ${{ secrets.X }}, never inlined. The only token-shaped strings in the repo are Telegram's published BotFather placeholder (123456789:AAE-aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456). GitHub secret-scanning runs by default.

    9. Race conditions / TOCTOU
      go test -race on Linux + macOS in CI. musicrefresh uses an explicit cancel-stored-in-session lifecycle.

    10. Goroutine leaks
      musicrefresh.Manager has Start/Stop/Touch with a 10-minute hard cap; Stop is called on navigate-away. refresher_test.go (312 lines) covers lifecycle paths.

    11. Supply-chain attacks via mutable Action tags
      Every third-party Action pinned to commit SHA (commits de4e7aa, 08216c6). go-installed tools pinned to versions (commit fdbe795).

    12. Vulnerable dependencies
      govulncheck on every push/PR. Dependabot scans gomod weekly. Total deps: 3 direct + 1 indirect.

    13. Information disclosure via verbose errors
      Sanitised user-facing Telegram messages; detailed errors go to the local log only.

    14. Logging secrets
      Keychain abstraction returns the token only at the call site that needs it. lumberjack rotates logs to bound retention.

    15. Insecure file permissions on artifacts
      Commit caa55d6 tightened LaunchAgent plist 0o644 → 0o600 and Library/Logs / LaunchAgents directories 0o755 → 0o750 in response to gosec findings.

    16. Insecure-by-default configuration
      No default whitelist — macontrol setup forces the user to enter their Telegram user-ID. A misconfigured install fails closed (no whitelisted users → no commands accepted).

    17. Cross-binary credential confusion
      macOS Keychain ACL is binary-path-bound. CONTRIBUTING.md explicitly warns dev contributors not to use go run for iterative dev because its random tempdir paths defeat the ACL.

    18. Insecure release pipeline
      GoReleaser triggered by release-please is fully automated; build flags -trimpath -s -w CGO_ENABLED=0 produce reproducible stripped binaries; the same workflow updates the Homebrew tap.

    19. Missed bug-class patterns
      13 linters via golangci-lint including gosec, staticcheck, gocritic, errcheck, ineffassign. CodeQL semantic analysis on every push. nolintlint polices suppressions themselves — only 3 //nolint directives exist in the entire codebase, each with an inline justification.

    20. No vulnerability disclosure channel
      SECURITY.md publishes the GitHub Security Advisories URL with documented SLAs (72h ack, ≤30d patch).

    Direct evidence of awareness (not incidental coverage):

    • Commit caa55d6 ("resolve 50 golangci-lint v2 findings") itemises fixes by linter category — errcheck, staticcheck, gosec, gocritic — showing findings are read, classified, and category-specific fixes applied (file-mode tightening for gosec, formatter for gofumpt).
    • Commit 0bb56cc fuzzed the single attacker-reachable parser with a CI comment explaining the choice — pinpointed threat awareness.
    • README disclaimer enumerates trust anchors (Telegram, Apple, Homebrew) explicitly — the developer thinks in trust boundaries.
    • Sibling project shellboto applies a different security model (Linux VPS, multi-user RBAC, hash-chained audit logs) — showing secure design adapted to threat surface, not a single template.

    Summary: the primary developer recognises and mitigates every common vulnerability class for this kind of software — command injection, privilege escalation, auth bypass, RCE, parser bugs, path traversal, credential leakage at rest and in transit, races, goroutine leaks, supply-chain attacks, vulnerable deps, info disclosure, log secrets, file-mode laxity, insecure defaults, cross-binary credential confusion, release-pipeline integrity, missing static analysis, and absent disclosure channels. Each class has at least one applied mitigation, and several have layered ones.


  • Tumia mazoea mazuri ya msingi ya usimbuaji

    Kumbuka kwamba programu fulani haihitaji kutumia taratibu za usimbuaji. Ikiwa mradi wako unazalisha programu ambayo (1) inajumuisha, inaamilisha, au inafanya usimbuaji kuwa hai, na (2) inaweza kutolewa kutoka Marekani (US) kwenda nje ya Marekani au kwa raia asiye wa Marekani, inaweza kuwa ni lazima kisheria kuchukua hatua chache za ziada. Kawaida hii inahusisha tu kutuma barua pepe. Kwa maelezo zaidi, tazama sehemu ya usimbuaji ya Kuelewa Teknolojia ya Chanzo Wazi & Udhibiti wa Usafirishaji wa Marekani.

    Ya kutosha kwa nishani!

    Programu iliyotengenezwa na mradi LAZIMA itumie, kwa chaguo-msingi, tu itifaki za kriptografia na mifumbo ambazo zimechapishwa hadharani na kukaguliwa na wataalam (ikiwa itifaki za kriptografia na mafumbo imetumika). [crypto_published]
    Vigezo hivi vya kriptografia mara mingi havitumiki kwa sababu programu zingine hazina haja ya kutumia moja kwa moja uwezo wa kriptografia.

    Ya kutosha kwa nishani!

    Ikiwa programu iliyotengenezwa na mradi ni programu au maktaba, na kusudi lake la msingi sio kutekeleza usimbuaji, basi INAPASWA tu kuita programu iliyoundwa kihususa kutekeleza kazi za kielelezo; HAIPASWI kutekeleza-upya shughuli hiyo. [crypto_call]

    Ya kutosha kwa nishani!

    Utendaji wote katika programu iliyotengenezwa na mradi ambayo inategemea usimbuaji LAZIMA iweze kutekelezwa kwa kutumia FLOSS. [crypto_floss]
    Tazama Mahitaji ya Viwango wazi ya Programu kupitia Open Source Initiative.

    Ya kutosha kwa nishani!

    Mifumo ya usalama ndani ya programu inayozalishwa na mradi LAZIMA itumie kwa msingi keylengths ambazo angalau zinakidhi mahitaji ya chini ya NIST kufikia mwaka wa 2030 (kama ilivyoelezwa mnamo 2012). LAZIMA iwe rahisi kusanidi programu ili keylengths ndogo zimezimwa kabisa. [crypto_keylength]
    Vipimo hivi vya urefu wa charaza ni: symmetric key 112, factoring modulus 2048, discrete logarithm key 224, discrete logarithmic group 2048, elliptic curve 224, na hash 224 (ufichuzi wa nywila haujashughulikiwa kwenye urefu wa charaza hii, maelezo zaidi ya ufichuzi wa nywila yanapatikana ndani ya kigezo cha crypto_password_storage). Ona https://www.keylength.com kwa mliganisho wa mapendekezo ya funguo-refu kutoka mashirika mbali mbali. Programu YAWEZA kubali funguo-refu ndogo katika usanidi (haifai kukubali, maana hii huwacha mashambulizi ya kushusha, lakini funguo-refu fupi wakati mwingine ina manufaa ya upatanifu).

    Ya kutosha kwa nishani!

    Mifumo ya usalama ya chaguo-msingi ndani ya programu inayozalishwa na mradi LAZIMA ISITEGEMEE algoriti zilizovunjika za kriptologia (k.m., MD4, MD5, DES moja, RC4, Dual_EC_DRBG), au kutumia hali za cipher ambazo si sahihi kwa muktadha, isipokuwa ni muhimu kutekeleza itifaki inayoweza kushirikiana (ambapo itifaki iliyotekelezwa ni toleo la hivi karibuni zaidi la kiwango hicho kinachotegemeana sana na mfumo wa mtandao, mfumo huo unahitaji matumizi ya algoriti au hali hiyo, na mfumo huo haupatii chaguo lolote salama zaidi). Nyaraka LAZIMA zieleze hatari zozote za usalama husika na upungufu wowote unaojulikana ikiwa algoriti hizi zilizovunjika au hali ni muhimu kwa itifaki inayoweza kushirikiana. [crypto_working]
    Hali ya ECB ni karibu kamwe haifai kwa sababu inaonyesha block zinazofanana ndani ya ciphertext kama ilivyoonyeshwa na penguin wa ECB, na hali ya CTR mara nyingi si sahihi kwa sababu haifanyi uthibitishaji na husababisha nakala ikiwa hali ya ingizo inarudiwa. Katika hali nyingi ni bora kuchagua hali ya algoriti ya block cipher iliyoundwa kuchanganya siri na uthibitishaji, k.m., Galois/Counter Mode (GCM) na EAX. Miradi YAWEZA kuwaruhusu watumiaji kuwasha taratibu zilizovunjika (k.m., wakati wa usanidi) ambapo ni muhimu kwa upatanifu, lakini hapo watumiaji wanajua wanafanya hivyo.

    Ya kutosha kwa nishani!

    Mifumo ya usalama ya chaguo-msingi ndani ya programu inayozalishwa na mradi INAPASWA ISITEGEMEE algoriti za kriptologia au hali zenye udhaifu mkubwa unaojulikana (k.m., algoriti ya hash ya kriptologia ya SHA-1 au hali ya CBC katika SSH). [crypto_weaknesses]
    Wasiwasi kuhusu hali ya CBC katika SSH unajadiliwa katika CERT: SSH CBC vulnerability.

    Ya kutosha kwa nishani!

    Mifumo ya usalama ndani ya programu iliyotengenezwa na mradi INAPASWA kutekeleza kwa ukamilifu usiri wa umbele ya itifaki za makubaliano ya funguo ili funguo la kipindi kilicho tokana na kikao cha vifungo muda-mrefu haziwezi kuridhi mabaya ikiwa mojawapo ya vifunguo vya muda-mrefu imeridhi mabaya katika usoni. [crypto_pfs]

    Ya kutosha kwa nishani!

    Ikiwa programu iliyotengenezwa na mradi imesababisha uhifadhi wa nywila kwa minajili ya uthibitishaji ya watumiaji wa kutoka nje, nywila LAZIMA zihifadhiwe kwa mficho uliorudiarudia na chumvi kwa kila-mtumiaji kwa kutumia kanuni ya upanuaji (rudiarudia) wa funguo (k.m., Argon2id, Bcrypt, Scrypt, or PBKDF2). Ona pia Kurasadogo ya Uhifadhi wa Nywila la OWASP). [crypto_password_storage]
    Kigezo hili linatumika tu wakati programu linatekeleza uthibitishaji wa watumiaji kutumia nywila kwa watumiaji wa nje (ambayo pia ni uthibitishaji unaelekezwa ndani), kama vile programu za tovuti zinazobakia seva). Haitumiki katika visa ambavyo programu inahifadhi nywila ili kudhibitisha ndani ya mifumo mingine (ambayo pia ni ithibitishaji unaelekezwa nje, k.m., programu inatekeleza teja la mfumo lingineyo), maana angalau sehemu za programu lazima ziwe na njia ya kupata hiyo nywila isigalifichwa.

    Ya kutosha kwa nishani!

    Mifumo ya usalama ndani ya programu iliyotengenezwa na mradi LAZIMA itoe funguo zote za kriptologia na nonces kwa kutumia kitengeneza cha nambari za bahati kuptia kriptologia salama, na ISIWEZE kufanya hivo kutumia vitengenezi zisizo salama kikriptologia. [crypto_random]
    Kitengeneza cha nambari za bahati nasibu za kriptologia salama kinaweza kuwa kitengeneza cha nambari za bahati nasibu za vifaa, au kinaweza kuwa kitengeneza cha nambari za bahati nasibu za kriptologia salama (CSPRNG) kwa kutumia algoriti kama vile Hash_DRBG, HMAC_DRBG, CTR_DRBG, Yarrow, au Fortuna. Mifano ya simu kwa vitengeneza cha nambari za bahati nasibu salama ni pamoja na java.security.SecureRandom ya Java na window.crypto.getRandomValues ya JavaScript. Mifano ya simu kwa vitengeneza cha nambari za bahati nasibu zisizo salama ni pamoja na java.util.Random ya Java na Math.random ya JavaScript.

  • Utoaji salama dhidi ya mashambulizi ya mtu-katikati (MITM)


    Ya kutosha kwa nishani!

    Mradi LAZIMA utumie utaratibu wa utoaji ambao unakabiliana na mashambulizi ya MITM. Kutumia https au ssh+scp ni inakubaliwa. [delivery_mitm]
    Utaratibu wenye nguvu zaidi ni kutoa programu na vifurushi vilivyosainiwa kidigitali, kwa kuwa hiyo inapunguza mashambulizi kwenye mfumo wa usambazaji, lakini hii inafanya kazi tu ikiwa watumiaji wanaweza kuwa na uhakika kwamba funguo za umma kwa saini ni sahihi na ikiwa watumiaji watakagua saini kweli kweli.

    Distribution channels use HTTPS exclusively. [osps_br_03_02]


    Ya kutosha kwa nishani!

    Hash ya kriptologia (k.m., sha1sum) LAZIMA ISICHUKULIWE kupitia http na kutumika bila kuangalia saini ya kriptologia. [delivery_unsigned]
    Hash hizi zinaweza kurekebishwa wakati wa usafiri.

  • Udhaifu uliofahamika hadharani umeshughulikiwa


    Ya kutosha kwa nishani!

    LAZIMA kuwe hakuna udhaifu usiorekebishwa wa kiwango cha kati au juu zaidi ambao umejulikana hadharani kwa zaidi ya siku 60. [vulnerabilities_fixed_60_days]
    Udhaifu lazima urekebishwe na kutolewa na mradi wenyewe (rekebisho zinaweza kutengenezwa mahali pengine). Udhaifu unakuwa unajulikana hadharani (kwa kusudi hili) mara tu unapata CVE yenye taarifa zilizotolewa hadharani zisizolipwa (zilizoripotiwa, kwa mfano, katika Hifadhidata ya Taifa ya Udhaifu) au wakati mradi umefahamishwa na taarifa imetolewa kwa umma (labda na mradi). Udhaifu unazingatiwa kuwa wa kiwango cha kati au juu ikiwa alama yake ya Common Vulnerability Scoring System (CVSS) ya msingi ya ubora ni kati au juu. Katika matoleo ya CVSS 2.0 hadi 3.1, hii ni sawa na alama ya CVSS ya 4.0 au zaidi. Miradi inaweza kutumia alama ya CVSS kama ilivyochapishwa katika hifadhidata ya udhaifu inayotumika sana (kama vile Hifadhidata ya Taifa ya Udhaifu) kwa kutumia toleo la hivi karibuni la CVSS lililoripotiwa katika hifadhidata hiyo. Miradi badala yake inaweza kuhesabu ukali wao wenyewe kwa kutumia toleo la hivi karibuni la CVSS wakati wa ufunuzi wa udhaifu, ikiwa ingizo la hesabu linatangazwa hadharani mara tu udhaifu unajulikana hadharani. Kumbuka: hii inamaanisha kwamba watumiaji wanaweza kuachwa katika hatari kwa washambuliaji wote duniani kwa siku hadi 60. Kigezo hiki ni rahisi zaidi kukidhi kuliko yale Google inapendekeza katika Rebooting responsible disclosure, kwa sababu Google inapendekeza kwamba kipindi cha siku 60 kianze wakati mradi unafahamishwa hata ikiwa ripoti si ya umma. Pia kumbuka kwamba kigezo hiki cha nishani, kama vigezo vingine, kinatumika kwa mradi wa mtu binafsi. Baadhi ya miradi ni sehemu ya mashirika makubwa ya mwavuli au miradi mikubwa, labda katika safu nyingi, na miradi mingi inatoa matokeo yao kwa mashirika mengine na miradi kama sehemu ya mnyororo wa usambazaji wenye utata. Mradi wa mtu binafsi mara nyingi hauwezi kudhibiti wengine, lakini mradi wa mtu binafsi unaweza kufanya kazi kutoa rekebisho ya udhaifu kwa wakati. Kwa hiyo, tunazingatia tu muda wa jibu wa mradi wa mtu binafsi. Mara tu rekebisho inapatikana kutoka kwa mradi wa mtu binafsi, wengine wanaweza kuamua jinsi ya kushughulikia rekebisho (k.m., wanaweza kusasisha kwenye toleo jipya au wanaweza kutumia rekebisho tu kama suluhisho lililochaguliwa-cherry).

    vulnerabilities_fixed_60_days — macontrol evidence

    The project satisfies this criterion. There are no known unpatched vulnerabilities of medium or higher severity, the dependency surface is minimal, and multiple automated systems continuously scan for new vulnerabilities.

    1. Minimal dependency surface

    go.mod declares only 3 direct dependencies and 1 indirect dependency:

    require (
    github.com/go-telegram/bot v1.20.0
    golang.org/x/term v0.42.0
    gopkg.in/natefinch/lumberjack.v2 v2.2.1
    )
    require golang.org/x/sys v0.43.0 // indirect

    A small dependency tree means a small attack surface and faster patch turnaround when CVEs land.

    1. Continuous vulnerability scanning in CI

    .github/workflows/ci.yml runs govulncheck ./... on every push and pull request as a dedicated vuln job. govulncheck is the official Go vulnerability scanner, backed by the Go vulnerability database (vuln.go.dev), and it checks both direct/indirect dependencies and stdlib usage. A new CVE affecting any reachable code path fails the build.

    .github/workflows/codeql.yml runs GitHub CodeQL on the codebase for semantic vulnerability detection.

    .github/workflows/scorecards.yml runs OpenSSF Scorecard, which independently checks for vulnerable dependencies and publishes the result to a public dashboard (badge linked in README).

    1. Automated patch ingestion via Dependabot

    .github/dependabot.yml is configured to:

    • Scan the gomod ecosystem weekly (Mondays 06:00 UTC) and open up to 5 update PRs
    • Scan the github-actions ecosystem on the same schedule
    • Group minor + patch updates so security-relevant patches land quickly without PR noise
    • Label PRs dependencies for triage

    This means new upstream patches (including those addressing CVEs) reach the maintainer's review queue within 7 days of publication — well inside the 60-day window.

    The Dependabot badge on README.md ("Dependabot enabled") publicly signals the policy.

    1. Disclosed vulnerability handling policy (SECURITY.md)

    The maintainer commits in writing to:

    • Acknowledge reports within 72 hours
    • Ship a patch or mitigation within 30 days of confirming a vulnerability

    30 days is half the 60-day SLA the badge criterion requires, with explicit room for mitigation if a fix is complex.

    1. Private disclosure channel

    SECURITY.md instructs reporters to use GitHub's private vulnerability reporting (security advisories) rather than public issues, allowing fixes to ship before public disclosure starts the 60-day clock.

    1. Public security advisories database

    A check against https://github.com/amiwrpremium/macontrol/security/advisories shows the project has no published advisories. The Go vulnerability database (vuln.go.dev) shows no entries for github.com/amiwrpremium/macontrol. The OpenSSF Scorecard report (linked from the README badge) shows no vulnerable-dependency findings against the current master.

    1. Pinned, reproducible CI tooling

    CI workflows pin third-party GitHub Actions to commit SHAs (commit de4e7aa "ci: pin third-party actions to commit SHAs"; 08216c6 "ci: pin first-party github actions to commit shas") and pin go-installed tool versions (commit fdbe795 "ci: pin go install tool versions"). This prevents supply-chain attacks via mutable tags from introducing untracked vulnerable code into the build pipeline.

    Summary: only 4 dependencies total, all on recent versions; govulncheck + CodeQL + Scorecard run on every push/PR; Dependabot scans weekly and groups patches; SECURITY.md commits to a 30-day patch SLA (half the badge requirement); private disclosure channel published; no security advisories filed against the project; pinned-SHA action references prevent supply-chain regressions. The criterion is satisfied with strong defence in depth.


    Ya kutosha kwa nishani!

    Miradi INAPASWA kurekebisha udhaifu wote muhimu haraka baada ya kuripotiwa. [vulnerabilities_critical_fixed]

    vulnerabilities_critical_fixed — macontrol evidence

    The project satisfies this suggested criterion. There are no known critical vulnerabilities outstanding against macontrol, and the project has the policy, automation, and demonstrated practice in place to fix any that are reported rapidly.

    1. No known critical vulnerabilities currently outstanding
    • GitHub Security Advisories for the repo: none published
      (https://github.com/amiwrpremium/macontrol/security/advisories)
    • Go vulnerability database (vuln.go.dev): no entries for
      github.com/amiwrpremium/macontrol
    • govulncheck runs on every push and PR via the vuln job in
      .github/workflows/ci.yml — current master passes
    • OpenSSF Scorecard (badge linked from README) reports no
      vulnerable-dependency findings on the current master
    • CodeQL semantic analysis (.github/workflows/codeql.yml) runs on
      every push — current master passes
    1. Documented rapid-fix commitment (SECURITY.md)

    The published security policy states explicit, time-bounded SLAs:

    • Acknowledge reports within 72 hours
    • Ship a patch (or provide a mitigation) within 30 days of
      confirming a vulnerability

    For critical issues this is the upper bound — the policy says "30 days
    of confirming a vulnerability", not "30 days regardless of severity",
    which leaves room to ship faster when severity warrants it. A 30-day
    upper bound is well inside the "rapidly" bar implied by this criterion.

    1. Private disclosure channel — fixes can ship before public clock starts

    SECURITY.md instructs reporters to use GitHub's private vulnerability
    reporting (security advisories) rather than public issues:

    https://github.com/amiwrpremium/macontrol/security/advisories/new

    This means a critical vulnerability can be patched and a release cut
    before any public disclosure, minimising the exposure window for users.

    1. Release infrastructure supports rapid patching

    The release pipeline is fully automated:

    • release-please opens a release PR whenever master accumulates
      release-worthy commits
    • Merging the release PR tags the version
    • GoReleaser (.goreleaser.yaml) builds the tarball and updates the
      Homebrew tap (amiwrpremium/homebrew-tap) automatically

    A critical fix can therefore go from merged commit → tagged release →
    Homebrew-installable patched binary in a single CI run, with no manual
    release ceremony to delay it. The CHANGELOG.md history shows multiple
    patch releases (e.g., 0.6.1) cut shortly after their parent minor
    release, demonstrating the patch-release path works in practice.

    1. Defence-in-depth shrinks the critical-vulnerability surface

    The threat model documented in docs/security/ and SECURITY.md treats
    the bot token + whitelisted Telegram account as equivalent to shell
    access by design, narrowing what counts as a vulnerability:

    • Hard Telegram-user-ID whitelist as the auth boundary; non-
      whitelisted updates dropped silently
    • No /sh escape hatch — only named commands
    • Bot token stored in macOS Keychain (not config files or env vars)
    • Outbound long-poll only — no inbound port exposed
    • Subprocess invocation via a constrained runner.Runner interface
      rather than free-form shell exec
    • Sudoers template (sudoers.d/macontrol.sample) limits sudo to a
      narrow allowlist of commands

    This architecture means whole classes of critical vulnerability (RCE
    via inbound network, command injection via shell metacharacters,
    privilege escalation via broad sudo) are structurally hard to
    introduce in the first place.

    1. Demonstrated rapid-response posture on lint/security findings

    While not CVE-class, the maintainer's response time to security-
    adjacent findings shows the cadence is fast:

    caa55d6 fix(ci): resolve 50 golangci-lint v2 findings
    — including 5 gosec findings (file modes tightened
    0o755 → 0o750, plist 0o644 → 0o600)

    Tightening file permission modes in response to gosec findings is the
    same muscle memory that handles CVEs. The fix-and-ship cycle is short.

    1. Supply-chain hardening to prevent introducing critical vulns

    de4e7aa ci: pin third-party actions to commit SHAs
    08216c6 ci: pin first-party github actions to commit shas
    fdbe795 ci: pin go install tool versions

    Pinning every action and tool to a commit SHA prevents a compromised
    upstream from silently injecting vulnerable code into the build —
    shrinking the chance that a critical vulnerability is shipped via the
    release pipeline rather than written into the code.

    1. Dependabot ensures upstream critical fixes reach the maintainer fast

    .github/dependabot.yml runs weekly on both gomod and github-actions
    ecosystems. A critical CVE in an upstream dependency triggers a
    Dependabot PR within at most 7 days; combined with the automated
    release pipeline, the patched version can reach end users via Homebrew
    within a single business day of merge.

    Summary: no known critical vulnerabilities currently outstanding (per
    GitHub Advisories, vuln.go.dev, govulncheck, CodeQL, and Scorecard);
    SECURITY.md commits to acknowledge in 72 hours and patch in ≤30 days;
    private disclosure channel allows fixes to ship before public
    disclosure; fully automated release-please + GoReleaser pipeline can
    turn a critical fix into a tagged release and a Homebrew-installable
    binary in a single CI run; defence-in-depth architecture (whitelist,
    named commands, Keychain, no inbound port, narrow sudoers) shrinks
    the critical-vuln surface; supply-chain pinning prevents critical
    vulns from being introduced via tooling. The criterion is satisfied.


  • Masuala mengine ya usalama


    Ya kutosha kwa nishani!

    Hazina za umma LAZIMA ZISIVUJE uthibitisho halali wa faragha (k.m., nywila inayofanya kazi au funguo ya faragha) ambayo imekusudiwa kupunguza upatikanaji wa umma. [no_leaked_credentials]
    Mradi UNAWEZA kuvuja uthibitisho wa "sampuli" kwa majaribio na hifadhidata zisizo muhimu, mradi tu hazikusudiwa kupunguza upatikanaji wa umma.

    no_leaked_credentials — macontrol evidence

    The project satisfies this criterion. No valid private credentials are present anywhere in the public repository.

    1. Repository-wide credential search — clean

    A repo-wide search for the standard credential patterns finds zero hits:

    • Private keys (BEGIN (RSA|EC|DSA|OPENSSH|)PRIVATE KEY) → 0 matches
    • AWS access keys (AKIA[0-9A-Z]{16}) → 0 matches
    • .env files, *.pem, .key, id_rsa files → 0 matches
    • GitHub Personal Access Tokens (gh[pousr]_[A-Za-z0-9]{36,}) → 0 matches

    The only token-like strings in the repo are the obvious documentation placeholders described below.

    1. Documentation placeholders are not valid credentials

    Three matches for the Telegram bot token pattern (<digits>:<base64-ish>)
    appear in documentation:

    docs/getting-started/credentials-telegram.md:55
    docs/getting-started/credentials-telegram.md:146
    docs/security/bot-token.md:11

    All three reproduce the BotFather example token from Telegram's own
    docs (123456789:AAE-...0123456), inside a quoted illustration of
    what BotFather's reply looks like and how to test the token with curl.
    This is an obviously fabricated placeholder:

    • The user-id portion is "123456789", a sequential demo value
    • The secret portion follows an alphabetical pattern
      (AAE-aBcDeFgHiJkL...)
    • It appears verbatim in Telegram's public BotFather walkthrough
    • It does not authenticate against api.telegram.org — calling
      https://api.telegram.org/bot<that-token>/getMe returns
      "Unauthorized"

    So this is not a leaked credential; it's a documentation literal,
    matching the convention used by Telegram's own documentation.

    1. .gitignore protects against accidental credential commits

    The .gitignore explicitly excludes credential file patterns:

    Secrets

    .env
    .env.*
    *.pem
    *.key

    This means a contributor who creates a local .env or .pem file cannot
    accidentally git add it.

    1. Real credentials are stored outside the repository

    The architecture is designed so that production credentials never
    touch the repo:

    • Bot token + Telegram user-ID whitelist live in the macOS Keychain
      (internal/keychain/), written by macontrol setup at runtime.
      They are never serialised to disk in cleartext, never written to
      config files, and never committed.
    • CONTRIBUTING.md tells dev contributors to use a separate dev token
      written to their own Keychain (macontrol token set), or to run
      under a separate macOS user account with its own login keychain.
    • sudoers.d/macontrol.sample is a template — the actual sudoers
      entry is written by the installer, not committed.
    1. CI secrets are referenced via GitHub Secrets, never inlined

    Every secret in .github/workflows/*.yml is read via the ${{ secrets.X }}
    mechanism, which GitHub redacts from logs and which is never visible
    in the repository contents:

    CODECOV_TOKEN (ci.yml)
    CODACY_PROJECT_TOKEN (ci.yml)
    GITHUB_TOKEN (pr-title.yml, release.yml — provided by GH)
    RELEASE_PLEASE_PAT (release-please.yml)
    HOMEBREW_TAP_TOKEN (release.yml)

    No CI workflow inlines a token, hex blob, or base64 secret.

    1. Active leak detection
    • GitHub's secret-scanning service runs on every public repository
      by default and alerts the maintainer on any pattern match.
    • OpenSSF Scorecard (.github/workflows/scorecards.yml) runs and
      publishes results publicly; the badge in README links to the
      dashboard.
    • CodeQL semantic analysis (.github/workflows/codeql.yml) runs on
      every push and would flag credential-handling anti-patterns.
    1. Documented credential hygiene

    SECURITY.md and docs/security/bot-token.md explicitly call out that
    the bot token is the project's primary credential and document where
    it lives (Keychain) and how to rotate it. The README's Disclaimer
    section reminds users:

    "You are responsible for the bot token and the whitelist."

    This is the opposite of the anti-pattern of treating credentials as
    casual values that might end up in commits.

    Summary: no valid credentials in the repo (zero matches for private
    keys, AWS keys, GitHub PATs, or .env-style files); the only
    token-shaped strings are Telegram's own documented placeholder, used
    inside docs/ to illustrate BotFather output; .gitignore blocks the
    common credential file patterns; production credentials live in the
    macOS Keychain and never touch the filesystem; CI secrets are
    referenced exclusively through GitHub's redacted secrets mechanism;
    GitHub secret-scanning + CodeQL + Scorecard provide active leak
    detection. The criterion is satisfied.


 Uchanganuzi 8/8 ●

  • Uchambuzi tuli wa msimbo


    Ya kutosha kwa nishani!

    Angalau zana moja ya uchambuzi wa msimbo tuli (zaidi ya maonyo ya mkusanyaji na hali za lugha "salama") LAZIMA itumike kwa toleo lolote lililopendekezwa kubwa la uzalishaji wa programu kabla ya toleo lake, ikiwa kuna angalau zana moja ya FLOSS inayotekeleza kigezo hiki katika lugha iliyochaguliwa. [static_analysis]
    Zana ya uchambuzi wa msimbo tuli inachunguza msimbo wa programu (kama msimbo wa chanzo, msimbo wa kati, au utekelezaji) bila kuutekeleza na ingizo maalum. Kwa madhumuni ya kigezo hiki, maonyo ya mkusanyaji na hali za lugha "salama" hazihesabiwi kama zana za uchambuzi wa msimbo tuli (hizi kwa kawaida huepuka uchambuzi wa kina kwa sababu kasi ni muhimu). Baadhi ya zana za uchambuzi wa msimbo tuli zinazingatia kugundua hitilafu za jumla, nyingine zinazingatia kupata aina fulani za hitilafu (kama vile udhaifu), na baadhi hufanya mchanganyiko. Mifano ya zana hizo za uchambuzi wa msimbo tuli ni pamoja na cppcheck (C, C++), clang static analyzer (C, C++), SpotBugs (Java), FindBugs (Java) (ikiwa ni pamoja na FindSecurityBugs), PMD (Java), Brakeman (Ruby on Rails), lintr (R), goodpractice (R), Coverity Quality Analyzer, SonarQube, Codacy, na HP Enterprise Fortify Static Code Analyzer. Orodha kubwa za zana zinaweza kupatikana katika maeneo kama vile orodha ya Wikipedia ya zana za uchambuzi wa msimbo tuli, taarifa za OWASP kuhusu uchambuzi wa msimbo tuli, orodha ya NIST ya vichambua usalama wa msimbo wa chanzo, na orodha ya Wheeler ya zana za uchambuzi tuli. Ikiwa hakuna zana za uchambuzi tuli za FLOSS zinazopatikana kwa lugha za utekelezaji zilizotumika, unaweza kuchagua 'N/A'.

    static_analysis — macontrol evidence

    The project applies multiple FLOSS static-analysis tools to every proposed change, well before any release:

    1. golangci-lint (FLOSS, GPL-3.0) — configured in .golangci.yml with 13 linters: errcheck, govet, ineffassign, staticcheck, unused, misspell, gocritic, revive (with exported and package-comments rules enabled), bodyclose, nolintlint, unparam, prealloc, gosec. Runs as the lint job in .github/workflows/ci.yml on every push and PR. make lint exposes the same check locally.

    2. CodeQL — .github/workflows/codeql.yml runs GitHub's semantic code analysis on every push to master.

    3. govulncheck — runs as the vuln CI job (govulncheck ./...), pinned to v1.1.4.

    4. OpenSSF Scorecard — .github/workflows/scorecards.yml runs supply-chain best-practice analysis with public results (badge in README).

    5. Codacy — third-party static analysis with public dashboard linked from README badges.

    Releases use release-please + GoReleaser; both run after CI is green, so no release tag is created without all five tools having passed.

    Summary: golangci-lint, CodeQL, govulncheck, Scorecard, and Codacy run on every push/PR. The criterion is satisfied.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba angalau moja ya zana za uchambuzi tuli zilizotumika kwa kigezo cha static_analysis ijumuishe sheria au njia za kutafuta udhaifu wa kawaida katika lugha au mazingira yaliyochambuliwa. [static_analysis_common_vulnerabilities]
    Zana za uchambuzi tuli ambazo zimeundwa hasa kutafuta udhaifu wa kawaida zina uwezekano mkubwa wa kuzipata. Hata hivyo, kutumia zana zozote za tuli kwa kawaida itasaidia kupata baadhi ya matatizo, kwa hivyo tunashauri lakini hatunahitaji hii kwa kiwango cha nishani ya 'kupita'.

    static_analysis_common_vulnerabilities — macontrol evidence

    Several of the static-analysis tools used target common vulnerabilities directly:

    • gosec (enabled in .golangci.yml) — Go security checker covering subprocess use (G204), file-permission laxity (G302/G306), insecure tempfile creation, weak crypto, integer overflow, path traversal (G304), TLS misconfig, and SQL injection patterns.
    • govulncheck — checks reachable code paths against the official Go vulnerability database (vuln.go.dev), covering both stdlib and dependencies.
    • CodeQL — semantic vulnerability detection (taint flow, injection, unsafe deserialisation, etc.) using GitHub's vulnerability query packs.
    • OpenSSF Scorecard — supply-chain vulnerability checks (vulnerable deps, pinned dependencies, signed releases, branch protection).
    • staticcheck — includes the SA category which catches correctness bugs that frequently underlie vulnerabilities (deprecated API use, unsafe type assertions, ignored errors).

    Evidence the vulnerability-focused rules fire and get acted on: commit caa55d6 ("resolve 50 golangci-lint v2 findings") explicitly itemises 5 gosec security findings fixed (file modes 0o755 → 0o750, plist 0o644 → 0o600, trusted-path file opens annotated). The criterion is satisfied.


    Ya kutosha kwa nishani!

    Udhaifu wote wenye ukali wa kati na juu zaidi unaoweza kudhoofishwa uliogundulika kupitia uchambuzi wa msimbo tuli LAZIMA urekebishwe kwa wakati baada ya kuthibitishwa. [static_analysis_fixed]
    Udhaifu unazingatiwa kuwa wa kiwango cha kati au juu zaidi ikiwa alama yake ya Common Vulnerability Scoring System (CVSS) ya msingi ya ubora ni kati au juu. Katika matoleo ya CVSS 2.0 hadi 3.1, hii ni sawa na alama ya CVSS ya 4.0 au zaidi. Miradi inaweza kutumia alama ya CVSS kama ilivyochapishwa katika hifadhidata ya udhaifu inayotumika sana (kama vile Hifadhidata ya Taifa ya Udhaifu) kwa kutumia toleo la hivi karibuni la CVSS lililoripotiwa katika hifadhidata hiyo. Miradi badala yake inaweza kuhesabu ukali wao wenyewe kwa kutumia toleo la hivi karibuni la CVSS wakati wa ufunuzi wa udhaifu, ikiwa ingizo la hesabu linatangazwa hadharani mara tu udhaifu unajulikana hadharani. Kumbuka kwamba kigezo cha vulnerabilities_fixed_60_days kinahitaji kwamba udhaifu wote kama huo urekebishwe ndani ya siku 60 baada ya kuwa wa umma.

    static_analysis_fixed — macontrol evidence

    No medium-or-higher severity exploitable vulnerabilities are currently outstanding from any static analyser:

    • golangci-lint with default: none and max-issues-per-linter: 0 runs clean on master (the lint job is green; CI blocks merges that introduce findings).
    • govulncheck ./... is green on master.
    • CodeQL has no open alerts on master.
    • OpenSSF Scorecard public report shows no vulnerable-dependency findings.

    Demonstrated track record of timely fixes:

    • caa55d6 "fix(ci): resolve 50 golangci-lint v2 findings" addressed all findings in a single PR with itemised release notes by linter category, including 5 gosec items (file-mode tightening, trusted-path annotations).
    • 9f045d2 "refactor: split overgrown handlers and table-drive parsers" addressed Codacy complexity findings.
    • The Music feature PR (#91) explicitly lists two refactors done to satisfy Codacy: splitting MusicCaption into per-section helpers and tickOnce into snapshot + edit-media helpers.

    CI gates merges on lint + vuln passing, so static-analysis findings cannot accumulate. The criterion is satisfied.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba uchambuzi wa msimbo wa chanzo tuli ufanyike kwenye kila ahadi au angalau kila siku. [static_analysis_often]

    static_analysis_often — macontrol evidence

    Static analysis runs on every commit, not merely daily:

    .github/workflows/ci.yml triggers on push to master and on pull_request targeting master. On every such event the following jobs run in parallel:

    • lint → golangci-lint (13 linters)
    • test → go test -race + coverage floor enforcement
    • vuln → govulncheck ./...
    • fuzz-short → 30s FuzzDecode

    .github/workflows/codeql.yml runs CodeQL on every push to master.
    .github/workflows/scorecards.yml runs OpenSSF Scorecard on schedule and publishes results publicly.
    Codacy runs on every push (continuous integration with the repo).

    Concurrency is configured to cancel superseded runs (cancel-in-progress: true) so the most recent commit always has fresh results. The criterion is satisfied at the strong end (per-commit, not daily).


  • Uchambuzi wa msimbo wa nguvu za ziada


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba angalau zana moja ya uchambuzi wa nguvu itumike kwenye toleo kubwa lolote la uzalishaji lililopendekezwa la programu kabla ya kutolewa kwake. [dynamic_analysis]
    Zana ya uchambuzi wa nguvu inachunguza programu kwa kuitekeleza na ingizo maalum. Kwa mfano, mradi YAWEZA kutumia zana ya fuzzing (k.m., American Fuzzy Lop) au kitafutaji cha programu ya wavuti (k.m., OWASP ZAP au w3af). Katika hali fulani mradi wa OSS-Fuzz unaweza kuwa tayari kutumia majaribio ya fuzz kwenye mradi wako. Kwa madhumuni ya kigezo hiki zana ya uchambuzi wa nguvu inahitaji kubadilisha ingizo kwa njia fulani kutafuta aina mbalimbali za matatizo au kuwa seti kiotomatiki ya majaribio yenye angalau asilimia 80 ya ukaguzi wa tawi. Ukurasa wa Wikipedia kuhusu uchambuzi wa nguvu na ukurasa wa OWASP kuhusu fuzzing hutambulisha baadhi ya zana za uchambuzi wa nguvu. Zana za uchambuzi ZINAWEZA kuzingatia kutafuta udhaifu wa usalama, lakini hii haihitajiki.

    dynamic_analysis — macontrol evidence

    Dynamic analysis is applied on every PR before release:

    1. Go native fuzzing — FuzzDecode in internal/telegram/callbacks/data_fuzz_test.go runs 30s on every PR via the fuzz-short job in .github/workflows/ci.yml. Targets the only attacker-reachable parser before the whitelist gate. Commit 0bb56cc.

    2. Race detector — go test -race -coverprofile=coverage.out ./... runs on the test matrix (ubuntu-latest + macos-14) on every push/PR. The race detector is a dynamic instrumentation tool that observes actual goroutine memory accesses at runtime.

    3. Coverage measurement — go test -coverprofile is dynamic instrumentation; the resulting profile feeds go-test-coverage which enforces a per-package floor.

    Releases are produced by release-please + GoReleaser only after CI is green, so no release ships without these dynamic checks having passed. The criterion is satisfied.


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba ikiwa programu iliyozalishwa na mradi inajumuisha programu iliyoandikwa kwa kutumia lugha isiyosalama ya kumbukumbu (k.m., C au C++), basi angalau zana moja ya nguvu (k.m., fuzzer au kitafutaji cha programu ya wavuti) itumike kwa kawaida kwa pamoja na utaratibu wa kugundua matatizo ya usalama wa kumbukumbu kama vile uandikaji zaidi wa kipengele. Ikiwa mradi hauzalishi programu iliyoandikwa katika lugha isiyosalama ya kumbukumbu, chagua "haihusiki" (N/A). [dynamic_analysis_unsafe]
    Mifano ya taratibu za kugundua matatizo ya usalama wa kumbukumbu ni pamoja na Address Sanitizer (ASAN) (inapatikana katika GCC na LLVM), Memory Sanitizer, na valgrind. Zana nyingine zinazoweza kutumika ni pamoja na thread sanitizer na undefined behavior sanitizer. Madai ya kila mahali pia yaweza kufanya kazi.

    dynamic_analysis_unsafe — macontrol evidence

    N/A.

    macontrol is written entirely in Go, a memory-safe language with garbage collection, bounds-checked slices, no pointer arithmetic, and runtime nil-check enforcement. The build sets CGO_ENABLED=0, so no C/C++ code is linked into the binary. There is no memory-unsafe code in the project to apply this criterion to.

    (For completeness: the project does run the Go race detector via go test -race on every push/PR and a Go native fuzzer on the callback parser — but the criterion does not apply because the language is memory-safe.)


    Ya kutosha kwa nishani!

    INAPENDEKEZWA kwamba mradi utumie usanidi wa angalau baadhi ya uchambuzi wa nguvu (kama vile majaribio au fuzzing) ambao huwezesha madai mengi. Katika hali nyingi madai haya yasipaswi kuwa yamewezeshwa katika mijengo ya uzalishaji. [dynamic_analysis_enable_assertions]
    Kigezo hiki hakipendekezi kuwezesha madai wakati wa uzalishaji; hilo ni kabisa kwa mradi na watumiaji wake kuamua. Lengo la kigezo hiki ni badala yake kuboresha ugunduzaji wa hitilafu wakati wa uchambuzi wa nguvu kabla ya kusambazwa. Kuwezesha madai katika matumizi ya uzalishaji ni tofauti kabisa na kuwezesha madai wakati wa uchambuzi wa nguvu (kama vile majaribio). Katika hali fulani kuwezesha madai katika matumizi ya uzalishaji ni busara sana (hasa katika vipengele vya uadilifu wa juu). Kuna hoja nyingi dhidi ya kuwezesha madai katika uzalishaji, k.m., maktaba hazipaswi kuvuruga waita, uwepo wao unaweza kusababisha kukataliwa na maduka ya programu, na/au kuamilisha madai katika uzalishaji kunaweza kufunua data za faragha kama vile funguo za faragha. Kumbuka kwamba katika usambazaji mwingi wa Linux NDEBUG haijafafanuliwa, hivyo C/C++ assert() kwa chaguo-msingi itawezeshwa kwa uzalishaji katika mazingira hayo. Inaweza kuwa muhimu kutumia utaratibu tofauti wa madai au kufafanua NDEBUG kwa uzalishaji katika mazingira hayo.

    dynamic_analysis_enable_assertions — macontrol evidence

    The project's dynamic analysis configuration enables checks well beyond what production builds carry:

    1. Race detector enabled in tests, disabled in production
      CI: go test -race -coverprofile=coverage.out ./...
      Production build: go build -trimpath -ldflags="-s -w" CGO_ENABLED=0 — no -race
      The race detector is an extensive instrumentation layer (assertion-style runtime checks on every memory access between goroutines) that is documented to be unsuitable for production due to overhead. macontrol enables it for the test matrix on every PR and strips it from release binaries.

    2. Go native fuzzer with assertion-style checks
      FuzzDecode runs the parser against random inputs and asserts on panics, oracle violations, and structural invariants. The fuzz harness is only compiled into test binaries, never the release artifact.

    3. Test-only assertion helpers
      internal/runner/runner.go's Fake test mock asserts on the parsed (Name, Args) tuple of every subprocess call, providing test-time invariant checks the production runner does not perform.

    4. Coverage floor as a runtime assertion
      go-test-coverage runs against the live coverage profile and asserts the floor is met (total 80%, package 75%, file 50%). This is a CI-time runtime check that does not exist in production.

    These assertion-style checks are configured for test/CI runs only — production builds use stripped binaries (-s -w) with no debug info, no race detector, no fuzz harness, no coverage instrumentation. The criterion is satisfied.


    Ya kutosha kwa nishani!

    Udhaifu wote wenye ukali wa kati na juu zaidi unaoweza kudhoofishwa uliogundulika kupitia uchambuzi wa msimbo wa nguvu LAZIMA urekebishwe kwa wakati baada ya kuthibitishwa. [dynamic_analysis_fixed]
    Ikiwa haujafanya uchambuzi wa msimbo wa nguvu na kwa hivyo hukupata udhaifu wowote kwa njia hii, chagua "haihusiki" (N/A). Udhaifu unazingatiwa kuwa wa kiwango cha kati au juu zaidi ikiwa alama yake ya Common Vulnerability Scoring System (CVSS) ya msingi ya ubora ni kati au juu. Katika matoleo ya CVSS 2.0 hadi 3.1, hii ni sawa na alama ya CVSS ya 4.0 au zaidi. Miradi inaweza kutumia alama ya CVSS kama ilivyochapishwa katika hifadhidata ya udhaifu inayotumika sana (kama vile Hifadhidata ya Taifa ya Udhaifu) kwa kutumia toleo la hivi karibuni la CVSS lililoripotiwa katika hifadhidata hiyo. Miradi badala yake inaweza kuhesabu ukali wao wenyewe kwa kutumia toleo la hivi karibuni la CVSS wakati wa ufunuzi wa udhaifu, ikiwa ingizo la hesabu linatangazwa hadharani mara tu udhaifu unajulikana hadharani.

    dynamic_analysis_fixed — macontrol evidence

    No medium-or-higher severity exploitable vulnerabilities are currently outstanding from any dynamic analyser:

    • The race detector (go test -race) is green on the CI matrix (ubuntu-latest + macos-14) on master.
    • FuzzDecode runs 30s per PR on the callback parser; no panics or oracle violations have been reported in the corpus or in CI.
    • Coverage floor is met on master.

    Demonstrated track record of timely fixes for dynamic-analysis findings:

    • The cancel-stored-in-session pattern in internal/telegram/musicrefresh/refresher.go was structured specifically to avoid the race-detector and gosec false-positive interaction; the inline //nolint:gosec // cancel stored in session.cancel; called by Stop and run's defer documents why the fix is safe.
    • Commit 0bb56cc proactively added fuzz coverage to the highest-risk parser, a forward-looking dynamic-analysis investment rather than a reactive fix.
    • Commit fdbe795 ("ci: pin go install tool versions") pinned the dynamic-analysis tooling itself (govulncheck, go-test-coverage) so dynamic-check behaviour is reproducible.

    CI gates merges on the race-detector test job passing and on FuzzDecode not panicking, so dynamic-analysis findings cannot accumulate unfixed. The criterion is satisfied.



Data hii inapatikana chini ya Community Data License Agreement – Permissive, Version 2.0 (CDLA-Permissive-2.0). Hii inamaanisha kuwa Mpokeaji wa Data anaweza kushiriki Data, na au bila marekebisho, mradi Mpokeaji wa Data anapatanisha maandishi ya mkataba huu na Data iliyoshirikiwa. Tafadhali tambua AMiWR na wachangiaji wa nishani ya Mazoea Bora ya OpenSSF.

Ingizo la nishani ya mradi linamilikiwa na: AMiWR.
Ingizo liliundwa siku 2026-04-25 02:20:50 UTC, iliyosasishwa mara ya mwisho siku 2026-04-25 02:59:10 UTC. Ilipata mara ya mwisho nishani ya kupita siku 2026-04-25 02:59:10 UTC.