Autonoma

يكتشف Autonoma الأسرار المشفرة في الكود المصدري ويستبدلها بمراجع os.environ[...] باستخدام إعادة كتابة AST. لا تُطبق التغييرات إلا عندما تكون إعادة الكتابة حتمية وتحافظ على المعنى الدلالي.

تستخدم إعادة الكتابة شجرة الـ syntax المُحلَّلة — وليس regex على النص الخام.
يعمل محليًا دون استدعاءات شبكة. يعمل في CI مع تغييرات صغيرة ومتطابقة.

المشكلة التي يحلّها هذا الأداة

الأسرار المشفرة في قواعد الأكواد:

• تُرفع الأسرار إلى المستودع وتبقى في تاريخ git
• إصلاحها يدويًا يكسر الكود أو يفوِّت حالات حافة
• تكتشف الفِرق التسريبات لكنها تتجنب أدوات الإصلاح التلقائي لأنها غير آمنة

معظم الأدوات تكتشفها.
Autonoma يلمس فقط ما يمكنه إثبات أنه آمن لتغييره.

مثال سريع

autonoma scan .
autonoma fix .
git diff

التثبيت

pip install autonoma-cli

التكامل مع Pre-commit

أضف هذا إلى ملف .pre-commit-config.yaml لمنع الأسرار من الوصول إلى تاريخ مستودعك:

- repo: local
  hooks:
    - id: autonoma
      name: Autonoma Scan
      entry: autonoma scan
      language: system
      types: [python]

جربه في 60 ثانية

# 1. إنشاء ملف اختبار يحتوي على أسرار مشفرة
cat > test_secrets.py << 'EOF'
SENDGRID_API_KEY = "sg-live-abc123xyz789"
DB_PASSWORD = "Pr0dAccess2024!"
EOF

# أيضًا إنشاء ملف عقد البيئة (مطلوب للمعالجة الآمنة)
printf 'SENDGRID_API_KEY=\nDB_PASSWORD=\n' > .env.example

# 2. المسح — يُخرج نتائج JSON إلى stdout
autonoma scan test_secrets.py

# 3. الإصلاح — يعيد كتابة الملف في مكانه
autonoma fix test_secrets.py

# 4. المسح مرة أخرى — يجب أن يكون نظيفًا الآن (رمز الخروج 0)
autonoma scan test_secrets.py

# 5. عرض النتيجة
cat test_secrets.py

المخرجات المتوقعة بعد الإصلاح:

import os
SENDGRID_API_KEY = os.environ["SENDGRID_API_KEY"]
DB_PASSWORD = os.environ["DB_PASSWORD"]

الأوامر

scan

وضع الكشف. يُخرج JSON إلى stdout وملخصًا قابلًا للقراءة البشرية إلى stderr. غير معدِّل — لا يعدل الملفات أبدًا.

# مسح دليل (نتائج JSON إلى stdout)
autonoma scan src/

# حفظ نتائج JSON إلى ملف
autonoma scan src/ > findings.json

رموز الخروج لـ scan:

fix

يعالج الأسرار المشفرة باستخدام إعادة كتابة AST. يعدل الملفات في مكانها.

# تطبيق الإصلاحات
autonoma fix src/

# معاينة التصحيحات قبل الكتابة
autonoma fix src/ --diff

# كتابة سجل تدقيق المعالجة
autonoma fix src/ --report-out audit.json

رموز الخروج لـ fix:

يخرج الأمر fix بالرمز 1 كلما وجد أسرارًا قبل محاولة المعالجة، بغض النظر عن نجاح إعادة الكتابة. هذا مقصود: يجب أن تعلّم خطوط CI عن الـ commit الذي أدخل الأسرار، حتى بعد الإصلاح التلقائي. قم بتشغيل autonoma scan بعد ذلك للتأكد من نظافة المستودع.

history-scan

يمسح تاريخ git بحثًا عن أسرار تم رفعها ثم إزالتها أو تغييرها.

[!NOTE] كشف فقط. هذا الأمر لا يعيد كتابة تاريخ git أو يعدّل الـ commits.

autonoma history-scan .

قبل / بعد

هذه هي الأنماط التي يصلحها Autonoma حاليًا.

قبل

# settings.py
SENDGRID_API_KEY = "sg-live-abc123xyz789"
DB_PASSWORD = "Pr0dAccess2024!"

بعد (autonoma fix .)

# settings.py
import os
SENDGRID_API_KEY = os.environ["SENDGRID_API_KEY"]
DB_PASSWORD = os.environ["DB_PASSWORD"]

مرفوض (السلامة أولاً بالإعراض)

# f-string — مرفوض لأن إعادة الكتابة ستغير المعنى الدلالي
api_key = f"prefix_{BASE_KEY}"
# → REFUSED: refuse_fstring_mixed_expression

# قيمة داخل dict/متغير — مرفوض لأن الهدف ليس تخصيصًا بسيطًا
DATABASES = {
    "default": {"PASSWORD": "Pr0d@ccess2024!"}
}
# → REFUSED: unsupported assignment target type

يتم الإبلاغ عن النتائج المرفوضة في مخرجات JSON وتسبب رمز خروج غير صفري في CI. لا يتم تعديل الملفات التي تحتوي على نتائج مرفوضة أبدًا.

ما يصلحه Autonoma مقابل ما يرفضه

ميزات CI/CD

إعادة التشغيل على ملف نظيف لا تُحدث أي تغييرات. تحافظ إعادة الكتابة على المسافات البادئة الأصلية والتعليقات. يتم إضافة import os فقط إذا كان مفقودًا.

التكامل و CI/CD

GitHub Actions (مسح فقط)

لفشل البناء إذا تم اكتشاف أي أسرار:

- name: Scan for secrets
  run: autonoma scan .

أوامر قديمة

analyze محتفظ به للتوافق مع الإصدارات السابقة. يُرجى الترحيل إلى scan أو fix.

# مكافئ لـ 'autonoma scan'
autonoma analyze src/ --detect-only

# مكافئ لـ 'autonoma fix'
autonoma analyze src/ --auto-fix

القيود والسلوكيات

ما يعالجه

• التخصيصات البسيطة: API_KEY = "secret"
• سمات الأصناف: class Config: PASS = "secret"
• الوسائط الكلمة المفتاحية: connect(password="secret")

ما يرفضه (بالتصميم)

• التعبيرات المعقدة: f-string، التسلسلات النصية، أو استدعاءات الدوال في الجانب الأيمن.
• الأهداف الغامضة: التخصيصات المتعددة (A = B = "secret") أو تفكيك tuple.
• القيم المتداخلة/داخل dict: قيم داخل dict أو list أو tuple.
• غياب السياق: إذا لم يتم العثور على ملف .env.example أو عقد بيئة في المستودع.

يتم الإبلاغ عن الحالات المرفوضة في مخرجات JSON وستتسبب في رموز خروج غير صفرية في CI. لا يتم تعديل الملف أبدًا إذا تم رفض أي مشكلة فيه.

ما لا يفعله

• لا يستخدم العشوائية/التخمين (يستخدم مطابقة الأسماء الاسترشادية).
• لا يعدل ملفات غير Python في الإصدار Community.
• لا يحذف الكود الخاص بك؛ يتم كتابة نسخ احتياطية كـ <file>.bak قبل التعديل.

القيود الحالية

يجمع SEC002 حاليًا بين أنماط قيم الاعتمادات ومنطق التوجيه المشروط بالكلمات المفتاحية. قد لا يتم اكتشاف الاعتمادات المخصصة لأسماء متغيرات غير نمطية للغاية حاليًا.

يتجنب Autonoma عمدًا اكتشاف الأسرار القائم على العشوائية فقط (entropy) ما لم يمكن قياس تأثير الدقة مقابل مجموعة إيجابية كاذبة مُوسومة.

مخطط JSON

يُخرج autonoma scan تقريرًا من نوع detect-only إلى stdout:

{
  "schema_version": "1.0",
  "tool_name": "autonoma",
  "tool_version": "0.1.5",
  "generated_at": "2026-03-24T12:00:00Z",
  "mode": "detect-only",
  "summary": {
    "files_processed": 3,
    "total_findings": 2,
    "safe_to_fix": 1,
    "refused": 1
  },
  "findings": [
    {
      "file": "settings.py",
      "line": 4,
      "pattern_type": "api_key",
      "severity": "high",
      "rule_id": "SEC002",
      "safe_to_fix": true,
      "suggested_env_var": "SENDGRID_API_KEY",
      "refusal_reason": null,
      "fingerprint": "sha256:abc123..."
    }
  ]
}

الترخيص

MIT License