42crunch/api-security-audit-actionCI/CD में OpenAPI अनुबंधों की स्थैतिक API सुरक्षा ऑडिटिंग को स्वचालित करता है, प्रमाणीकरण, प्राधिकरण और डेटा बाधाओं के लिए 300+ जाँच चलाता है, तथा न्यूनतम-स्कोर गेट्स और SARIF आउटपुट के साथ।
यह REST API स्टैटिक सुरक्षा परीक्षण एक्शन उन REST API कॉन्ट्रैक्ट्स का पता लगाता है जो OpenAPI Specification (OAS, जिसे पहले Swagger के नाम से जाना जाता था) का पालन करते हैं और उन पर गहन सुरक्षा जाँच चलाता है। OAS v2 और v3.0.x दोनों समर्थित हैं, JSON और YAML दोनों प्रारूपों में।
आप इस एक्शन का उपयोग निम्नलिखित परिदृश्यों में कर सकते हैं:
यह एक्शन 42Crunch API Security Audit द्वारा संचालित है। Security Audit API परिभाषा का स्टैटिक विश्लेषण करता है जिसमें प्रमाणीकरण, प्राधिकरण और डेटा बाधाओं से संबंधित सर्वोत्तम प्रथाओं और संभावित कमजोरियों पर 300 से अधिक जाँच शामिल हैं।
डिफ़ॉल्ट रूप से, यह एक्शन निम्न कार्य करेगा:
.json और .yaml फ़ाइल की खोज करें।इस प्रकार, आप रिपॉज़िटरी में किसी भी नए या बदले हुए API कॉन्ट्रैक्ट का पता लगा सकते हैं।
आप API डिस्कवरी में शामिल या बाहर किए जाने वाले रिपॉज़िटरी के विशिष्ट भागों या फ़ाइलनाम मास्क को निर्दिष्ट करके एक्शन के व्यवहार को बारीकी से समायोजित कर सकते हैं। आप डिस्कवरी को पूरी तरह से अक्षम भी कर सकते हैं और इसके बजाय केवल विशिष्ट API फ़ाइलों को सूचीबद्ध कर सकते हैं जिन्हें जाँचा जाना है और उन्हें 42Crunch API Security Platform में अपने मौजूदा APIs से मैप कर सकते हैं। आप ये सभी सेटिंग्स कॉन्फ़िगरेशन फ़ाइल 42c-conf.yaml में कॉन्फ़िगर करते हैं। उन्नत उदाहरणों के लिए, यहाँ देखें।
सभी खोजे गए APIs को 42Crunch Platform में एक API कलेक्शन में अपलोड किया जाता है। डिफ़ॉल्ट रूप से, एक्शन पर्यावरण चर GITHUB_REPOSITORY और GITHUB_REF का उपयोग उस रिपॉज़िटरी और ब्रांच/टैग/PR नाम के लिए करता है जहाँ से API कलेक्शन उत्पन्न हुआ है। आप default-collection-name एक्शन पैरामीटर का उपयोग करके नाम को ओवरराइड कर सकते हैं। बाद के रन के दौरान, कलेक्शन में मौजूद APIs आपकी रिपॉज़िटरी में हुए बदलावों के साथ सिंक में रहते हैं।
इस एक्शन को GitHub में अपने CI/CD वर्कफ़्लो में जोड़ें और इसे सुरक्षा मुद्दों वाली API परिभाषाओं पर विफल होने दें।
Security Audit प्रत्येक API कॉन्ट्रैक्ट को 0 से 100 के बीच एक ऑडिट स्कोर देता है जो आपके APIs की सुरक्षा सतह को दर्शाता है। आप GitHub Action के min-score पैरामीटर का उपयोग ऑडिट स्कोर के लिए थ्रेशोल्ड सेट करने के लिए कर सकते हैं जिस पर एक्शन विफल होता है (यदि कोई अन्य मान निर्दिष्ट नहीं है तो डिफ़ॉल्ट 75 है)। यह खराब गुणवत्ता वाली API परिभाषाओं को पकड़ने और डिज़ाइन समय पर ही मुद्दों का समाधान करने में मदद करता है।
अधिक उन्नत विफलता स्थितियाँ कॉन्फ़िगरेशन फ़ाइल 42c-conf.yaml में सेट की जा सकती हैं, जैसे कि श्रेणी (सुरक्षा या डेटा सत्यापन) के अनुसार ऑडिट स्कोर, मुद्दों का गंभीरता स्तर, या यहाँ तक कि विशिष्ट मुद्दे, जो उनके issue ID द्वारा निर्दिष्ट हों। उन्नत उदाहरणों के लिए, यहाँ देखें।
इसके अतिरिक्त, प्लगइन प्लेटफ़ॉर्म स्तर पर परिभाषित security quality gates (डिफ़ॉल्ट या टैग-संचालित) लागू करता है। Security quality gates उद्यम के भीतर परिभाषित एप्लिकेशन सुरक्षा आवश्यकताओं को लागू करते हैं।
जब भी एक्शन चलता है, इसमें आपकी प्रत्येक OpenAPI फ़ाइल के लिए विस्तृत, प्राथमिकता-क्रमित कार्रवाई योग्य रिपोर्ट का लिंक शामिल होता है:
विस्तृत रिपोर्ट 42Crunch Platform में पढ़ने के लिए लिंक का अनुसरण करें:
आप 42Crunch ऑडिट द्वारा पाए गए मुद्दों को सीधे GitHub में, Code scanning alerts के अंतर्गत Security टैब पर ट्रैक कर सकते हैं।
इसे सक्षम करने के लिए, अपने GitHub वर्कफ़्लो में एक्शन के पैरामीटर में upload-to-code-scanning:true शामिल करें।
अपने कोड में इसका सटीक स्थान देखने और कमजोरी के विवरण तथा अनुशंसित सुधार चरणों को प्राप्त करने के लिए किसी भी अलर्ट पर क्लिक करें।
यह एक्शन 42Crunch API Security Audit सेवा का उपयोग करता है। एक्शन का उपयोग करने से पहले, आपके पास 42Crunch प्लेटफ़ॉर्म पर एक खाता होना आवश्यक है। यदि आप 42Crunch ग्राहक नहीं हैं, तो आप इस पृष्ठ से निःशुल्क खाते का अनुरोध कर सकते हैं: https://42crunch.com/get-started/।
फिर, 42Crunch Platform में प्रमाणित होने के लिए एक्शन हेतु API टोकन बनाने और उसे GitHub में एक secret के रूप में सहेजने हेतु दस्तावेज़ में वर्णित चरणों का पालन करें।
api-tokenआवश्यक वह API टोकन जिसका उपयोग GitHub एक्शन 42Crunch Platform में प्रमाणित होने के लिए करता है। अपना API टोकन सीधे वर्कफ़्लो फ़ाइल में न डालें! इसके बजाय, अपनी रिपॉज़िटरी सेटिंग्स में एक GitHub secret बनाएं और नीचे दिए गए उदाहरण के अनुसार उसका संदर्भ दें।
min-scoreन्यूनतम ऑडिट स्कोर जो OpenAPI फ़ाइलों को प्राप्त करना आवश्यक है, अन्यथा एक्शन विफल हो जाता है। डिफ़ॉल्ट 75 है।
upload-to-code-scanningऑडिट परिणामों को Github Code Scanning पर अपलोड करें। डिफ़ॉल्ट false है। ध्यान दें कि इस चरण के सफल होने के लिए वर्कफ़्लो के पास विशिष्ट अनुमतियाँ होनी चाहिए।
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failuresयदि true पर सेट किया जाता है, तो आपके द्वारा निर्धारित विफलता स्थितियाँ (जैसे min-score या SQG मानदंड) पूरी होने पर भी निष्पादन को सफलतापूर्वक पूरा करने के लिए बाध्य करता है। डिफ़ॉल्ट false है।
यह पैरामीटर उपयोगी हो सकता है यदि आप SQG विफलता परिदृश्यों का पता लगाना चाहते हैं बिना उन्हें लागू किए (अर्थात् डेवलपमेंट टीमों को बिल्ड तोड़ना शुरू करने से पहले एक अनुग्रह अवधि देना)।
ignore-network-errorsयदि true पर सेट किया जाता है, तो नेटवर्क त्रुटि होने पर भी (जैसे 42Crunch Platform से कनेक्ट करने में विफलता, आदि) निष्पादन को सफलतापूर्वक पूरा करने के लिए बाध्य करता है। डिफ़ॉल्ट false है।
skip-local-checksयदि true पर सेट किया जाता है, तो 42c-conf.yaml फ़ाइल में निर्धारित सभी विफलता स्थितियों (जैसे न्यूनतम स्कोर) को अक्षम कर देता है और केवल तभी निष्पादन विफल करता है जब SQGs में परिभाषित मानदंड पूरे नहीं होते हैं। डिफ़ॉल्ट false है।
platform-urlवह URL जहाँ आप 42Crunch Platform तक पहुँचते हैं। डिफ़ॉल्ट https://us.42crunch.cloud है।
यदि आप एक एंटरप्राइज़ ग्राहक हैं, तो वह URL दर्ज करें जिसका उपयोग आप अपने प्रोडक्शन प्लेटफ़ॉर्म तक पहुँचने के लिए करते हैं।
root-directoryवह रूट डायरेक्टरी जिसमें 42c-conf.yaml कॉन्फ़िगरेशन फ़ाइल होती है। यदि निर्दिष्ट नहीं है, तो इसके बजाय प्लगइन के लिए वर्तमान कार्यशील डायरेक्टरी का उपयोग किया जाता है, जो सामान्यतः चेकआउट की गई रिपॉज़िटरी के रूट से मेल खाती है।
default-collection-nameखोजे गए APIs के लिए कलेक्शन बनाते समय उपयोग किया जाने वाला डिफ़ॉल्ट कलेक्शन नाम। यदि कोई नाम नहीं दिया गया है, तो रिपॉज़िटरी और ब्रांच/PR जानकारी से एक डिफ़ॉल्ट नाम बनाया जाता है।
log-levelलॉग में विवरण का स्तर, इनमें से एक: FATAL, ERROR, WARN, INFO, DEBUG। डिफ़ॉल्ट INFO है।
share-everyoneCI/CD कार्य द्वारा बनाए गए API कलेक्शन को 42Crunch Platform पर आपके संगठन के सभी लोगों के साथ स्वचालित रूप से साझा करता है। स्वीकृत मान हैं: OFF, READ_ONLY, READ_WRITE। डिफ़ॉल्ट OFF है। ध्यान दें कि जिस पहचान के अंतर्गत एक्शन चलता है (API टोकन का स्वामी) के पास Share with Everyone अनुमति होनी चाहिए, अन्यथा कार्य 403 त्रुटि के साथ विफल हो जाएगा।
json-reportऑडिट निष्पादन रिपोर्ट को JSON प्रारूप में निर्दिष्ट फ़ाइल में लिखता है। एक निष्पादन रिपोर्ट में उन APIs की सूची का विवरण होता है जो बनाए, अद्यतन और हटाए गए थे। यह उपयोगी है यदि आप किसी बाद के पाइपलाइन चरण में ऑडिट निष्पादन के परिणामों का स्वचालित रूप से उपभोग करना चाहते हैं। डिफ़ॉल्ट रूप से, कोई रिपोर्ट नहीं लिखी जाती है।
api-tagsCI/CD कार्य नव निर्मित APIs को स्वचालित रूप से टैग निर्दिष्ट कर सकता है। टैग निम्नलिखित प्रारूप में निर्दिष्ट किए जाते हैं: category1:name1 category2:name2। यह फ़्लैग वैकल्पिक है।
sarif-reportऑडिट के कच्चे JSON प्रारूप को SARIF में परिवर्तित करता है और परिणामों को निर्दिष्ट फ़ाइल में सहेजता है। डिफ़ॉल्ट रूप से, कोई रिपोर्ट नहीं लिखी जाती है।
audit-timeoutऑडिट रिपोर्ट के लिए अधिकतम टाइमआउट (सेकंड में) सेट करता है। यदि परिणाम उस अंतराल के भीतर तैयार नहीं होता है तो कार्य विफल हो जाएगा। डिफ़ॉल्ट: 600
42Crunch Platform पर एक API टोकन बनाएं और उसका मान API_TOKEN नामक एक रिपॉज़िटरी सीक्रेट में कॉपी करें।
मौजूदा वर्कफ़्लो में एक विशिष्ट नया चरण इस प्रकार दिखेगा:
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
एक विशिष्ट वर्कफ़्लो जो रिपॉज़िटरी की सामग्री की जाँच करता है, प्रोजेक्ट में पाई गई प्रत्येक OpenAPI फ़ाइल पर Security Audit चलाता है और निष्पादन फ़ाइल को आर्टिफैक्ट के रूप में सहेजता है, इस प्रकार दिखेगा:
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
इस एक्शन का रखरखाव 42Crunch Ecosystems टीम द्वारा किया जाता है। यदि आपको कोई समस्या आती है, या यहाँ कोई प्रश्न अनुत्तरित है, तो आप support.42crunch.com पर एक सहायता टिकट बना सकते हैं।
समस्या की रिपोर्ट करते समय, इन्हें शामिल करें: