diff --git a/docs/config/_default/languages.toml b/docs/config/_default/languages.toml index 30e7deb539..b375ba9433 100644 --- a/docs/config/_default/languages.toml +++ b/docs/config/_default/languages.toml @@ -41,3 +41,24 @@ [ja.params] languageISO = "JA" languageTag = "ja" + +[pt-br] + languageName = "Português (Brasil)" + weight = 60 + [pt-br.params] + languageISO = "PT" + languageTag = "pt-br" + +[zh-hans] + languageName = "简体中文" + weight = 70 + [zh-hans.params] + languageISO = "ZH" + languageTag = "zh-hans" + +[it] + languageName = "Italiano" + weight = 80 + [it.params] + languageISO = "IT" + languageTag = "it" diff --git a/docs/config/_default/menus/menus.it.toml b/docs/config/_default/menus/menus.it.toml new file mode 100644 index 0000000000..ca9211fe59 --- /dev/null +++ b/docs/config/_default/menus/menus.it.toml @@ -0,0 +1,125 @@ +# Generated from menus.en.toml by regen_menus.py - do not hand-edit. +# Labels are translated; a URL is language-prefixed when that page exists +# in this language and left as the English URL when it does not, so no nav +# entry 404s. Hugo does not merge menus across languages, so this file must +# carry every entry menus.en.toml has. + +[[main]] + name = "Inizia" + url = "/it/get_started/about/about_defectdojo" + weight = 10 + +[[main]] + name = "Importa dati" + url = "/it/import_data/import_intro/comparison/" + weight = 12 + +[[main]] + name = "Triage dei riscontri" + url = "/it/triage_findings/findings_workflows/intro_to_findings/" + weight = 12 + +[[main]] + name = "Modellazione degli asset" + url = "/it/asset_modelling/engagements_tests/os__assets/" + weight = 13 + +[[main]] + name = "Connettori" + url = "/it/connectors/about/" + weight = 13 + +[[main]] + name = "Metriche e report" + url = "/it/metrics_reports/dashboards/introduction_dashboard/" + weight = 14 + +[[main]] + name = "Sensei" + url = "/it/sensei/os__sensei/" + weight = 14 + +[[main]] + name = "Amministrazione" + url = "/it/admin/admin_intro/intro/" + weight = 16 + +[[main]] + name = "Automazione" + url = "/it/automation/api/api-v2-docs/" + weight = 15 + +[[main]] + name = "Strumenti supportati" + url = "/supported_tools/" + weight = 16 + +[[sidebar_sensei]] + name = "Sensei" + pageRef = "/sensei/OS__sensei" + weight = 0 + +[[sidebar_sensei]] + name = "Informazioni su Sensei" + pageRef = "/sensei/about_sensei" + weight = 1 + +[[sidebar_sensei]] + name = "Configurazione di Sensei" + pageRef = "/sensei/setup_sensei" + weight = 2 + +[[sidebar_sensei]] + name = "Correzione dei riscontri con Sensei" + pageRef = "/sensei/fixing_findings" + weight = 3 + +[[sidebar_sensei]] + name = "Riferimento Sensei" + pageRef = "/sensei/sensei_reference" + weight = 4 + +[[social]] + name = "YouTube" + pre = '' + url = "https://www.youtube.com/@defectdojo" + weight = 9 + +[[social]] + name = "X" + pre = '' + url = "https://x.com/defectdojo" + weight = 10 + +[[social]] + name = 'Linkedin' + pre = '' + url = "https://www.linkedin.com/company/defectdojo/" + weight = 10 + +[[social]] + name = "GitHub" + pre = '' + url = "https://github.com/DefectDojo/django-DefectDojo" + post = "v0.1.0" + weight = 30 + +[[footer]] + name = "DefectDojo.com" + url = "https://defectdojo.com" + weight = 10 + +[[footer]] + name = "GitHub" + url = "https://github.com/DefectDojo/django-DefectDojo" + weight = 20 + +[[footer]] + name = "Community" + url = "https://defectdojo.com/open-source" + weight = 30 + +[[footer]] + name = "Support" + url = "mailto:support@defectdojo.com" + weight = 40 diff --git a/docs/config/_default/menus/menus.pt-br.toml b/docs/config/_default/menus/menus.pt-br.toml new file mode 100644 index 0000000000..5b74c33a38 --- /dev/null +++ b/docs/config/_default/menus/menus.pt-br.toml @@ -0,0 +1,125 @@ +# Generated from menus.en.toml by regen_menus.py - do not hand-edit. +# Labels are translated; a URL is language-prefixed when that page exists +# in this language and left as the English URL when it does not, so no nav +# entry 404s. Hugo does not merge menus across languages, so this file must +# carry every entry menus.en.toml has. + +[[main]] + name = "Primeiros passos" + url = "/pt-br/get_started/about/about_defectdojo" + weight = 10 + +[[main]] + name = "Importar dados" + url = "/pt-br/import_data/import_intro/comparison/" + weight = 12 + +[[main]] + name = "Triagem de achados" + url = "/pt-br/triage_findings/findings_workflows/intro_to_findings/" + weight = 12 + +[[main]] + name = "Modele seus ativos" + url = "/pt-br/asset_modelling/engagements_tests/os__assets/" + weight = 13 + +[[main]] + name = "Conectores" + url = "/pt-br/connectors/about/" + weight = 13 + +[[main]] + name = "Métricas e relatórios" + url = "/pt-br/metrics_reports/dashboards/introduction_dashboard/" + weight = 14 + +[[main]] + name = "Sensei" + url = "/pt-br/sensei/os__sensei/" + weight = 14 + +[[main]] + name = "Administração" + url = "/pt-br/admin/admin_intro/intro/" + weight = 16 + +[[main]] + name = "Automação" + url = "/pt-br/automation/api/api-v2-docs/" + weight = 15 + +[[main]] + name = "Ferramentas compatíveis" + url = "/supported_tools/" + weight = 16 + +[[sidebar_sensei]] + name = "Sensei" + pageRef = "/sensei/OS__sensei" + weight = 0 + +[[sidebar_sensei]] + name = "Sobre o Sensei" + pageRef = "/sensei/about_sensei" + weight = 1 + +[[sidebar_sensei]] + name = "Configurar o Sensei" + pageRef = "/sensei/setup_sensei" + weight = 2 + +[[sidebar_sensei]] + name = "Corrigindo achados com o Sensei" + pageRef = "/sensei/fixing_findings" + weight = 3 + +[[sidebar_sensei]] + name = "Referência do Sensei" + pageRef = "/sensei/sensei_reference" + weight = 4 + +[[social]] + name = "YouTube" + pre = '' + url = "https://www.youtube.com/@defectdojo" + weight = 9 + +[[social]] + name = "X" + pre = '' + url = "https://x.com/defectdojo" + weight = 10 + +[[social]] + name = 'Linkedin' + pre = '' + url = "https://www.linkedin.com/company/defectdojo/" + weight = 10 + +[[social]] + name = "GitHub" + pre = '' + url = "https://github.com/DefectDojo/django-DefectDojo" + post = "v0.1.0" + weight = 30 + +[[footer]] + name = "DefectDojo.com" + url = "https://defectdojo.com" + weight = 10 + +[[footer]] + name = "GitHub" + url = "https://github.com/DefectDojo/django-DefectDojo" + weight = 20 + +[[footer]] + name = "Community" + url = "https://defectdojo.com/open-source" + weight = 30 + +[[footer]] + name = "Support" + url = "mailto:support@defectdojo.com" + weight = 40 diff --git a/docs/config/_default/menus/menus.zh-hans.toml b/docs/config/_default/menus/menus.zh-hans.toml new file mode 100644 index 0000000000..9b4851f477 --- /dev/null +++ b/docs/config/_default/menus/menus.zh-hans.toml @@ -0,0 +1,125 @@ +# Generated from menus.en.toml by regen_menus.py - do not hand-edit. +# Labels are translated; a URL is language-prefixed when that page exists +# in this language and left as the English URL when it does not, so no nav +# entry 404s. Hugo does not merge menus across languages, so this file must +# carry every entry menus.en.toml has. + +[[main]] + name = "快速入门" + url = "/zh-hans/get_started/about/about_defectdojo" + weight = 10 + +[[main]] + name = "导入数据" + url = "/zh-hans/import_data/import_intro/comparison/" + weight = 12 + +[[main]] + name = "分级发现项" + url = "/zh-hans/triage_findings/findings_workflows/intro_to_findings/" + weight = 12 + +[[main]] + name = "建模资产" + url = "/zh-hans/asset_modelling/engagements_tests/os__assets/" + weight = 13 + +[[main]] + name = "连接器" + url = "/zh-hans/connectors/about/" + weight = 13 + +[[main]] + name = "指标与报告" + url = "/zh-hans/metrics_reports/dashboards/introduction_dashboard/" + weight = 14 + +[[main]] + name = "Sensei" + url = "/zh-hans/sensei/os__sensei/" + weight = 14 + +[[main]] + name = "管理" + url = "/zh-hans/admin/admin_intro/intro/" + weight = 16 + +[[main]] + name = "自动化" + url = "/zh-hans/automation/api/api-v2-docs/" + weight = 15 + +[[main]] + name = "支持的工具" + url = "/supported_tools/" + weight = 16 + +[[sidebar_sensei]] + name = "Sensei" + pageRef = "/sensei/OS__sensei" + weight = 0 + +[[sidebar_sensei]] + name = "关于 Sensei" + pageRef = "/sensei/about_sensei" + weight = 1 + +[[sidebar_sensei]] + name = "设置 Sensei" + pageRef = "/sensei/setup_sensei" + weight = 2 + +[[sidebar_sensei]] + name = "使用 Sensei 修复发现项" + pageRef = "/sensei/fixing_findings" + weight = 3 + +[[sidebar_sensei]] + name = "Sensei 参考" + pageRef = "/sensei/sensei_reference" + weight = 4 + +[[social]] + name = "YouTube" + pre = '' + url = "https://www.youtube.com/@defectdojo" + weight = 9 + +[[social]] + name = "X" + pre = '' + url = "https://x.com/defectdojo" + weight = 10 + +[[social]] + name = 'Linkedin' + pre = '' + url = "https://www.linkedin.com/company/defectdojo/" + weight = 10 + +[[social]] + name = "GitHub" + pre = '' + url = "https://github.com/DefectDojo/django-DefectDojo" + post = "v0.1.0" + weight = 30 + +[[footer]] + name = "DefectDojo.com" + url = "https://defectdojo.com" + weight = 10 + +[[footer]] + name = "GitHub" + url = "https://github.com/DefectDojo/django-DefectDojo" + weight = 20 + +[[footer]] + name = "Community" + url = "https://defectdojo.com/open-source" + weight = 30 + +[[footer]] + name = "Support" + url = "mailto:support@defectdojo.com" + weight = 40 diff --git a/docs/content/_index.it.md b/docs/content/_index.it.md new file mode 100644 index 0000000000..6f3a38413d --- /dev/null +++ b/docs/content/_index.it.md @@ -0,0 +1,5 @@ +--- +title: Documentazione DefectDojo +date: 2021-02-02 20:46:29+01:00 +draft: false +--- diff --git a/docs/content/_index.pt-br.md b/docs/content/_index.pt-br.md new file mode 100644 index 0000000000..f794dedc41 --- /dev/null +++ b/docs/content/_index.pt-br.md @@ -0,0 +1,5 @@ +--- +title: Documentação do DefectDojo +date: 2021-02-02 20:46:29+01:00 +draft: false +--- diff --git a/docs/content/_index.zh-hans.md b/docs/content/_index.zh-hans.md new file mode 100644 index 0000000000..7ee1e2f3d4 --- /dev/null +++ b/docs/content/_index.zh-hans.md @@ -0,0 +1,5 @@ +--- +title: DefectDojo 文档 +date: 2021-02-02 20:46:29+01:00 +draft: false +--- diff --git a/docs/content/admin/admin_intro/_index.it.md b/docs/content/admin/admin_intro/_index.it.md new file mode 100644 index 0000000000..3fccce7569 --- /dev/null +++ b/docs/content/admin/admin_intro/_index.it.md @@ -0,0 +1,16 @@ +--- +title: Introduzione +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- diff --git a/docs/content/admin/admin_intro/_index.pt-br.md b/docs/content/admin/admin_intro/_index.pt-br.md new file mode 100644 index 0000000000..39f86549de --- /dev/null +++ b/docs/content/admin/admin_intro/_index.pt-br.md @@ -0,0 +1,16 @@ +--- +title: Introdução +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- diff --git a/docs/content/admin/admin_intro/_index.zh-hans.md b/docs/content/admin/admin_intro/_index.zh-hans.md new file mode 100644 index 0000000000..2ba8b4692c --- /dev/null +++ b/docs/content/admin/admin_intro/_index.zh-hans.md @@ -0,0 +1,16 @@ +--- +title: 简介 +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- diff --git a/docs/content/admin/admin_intro/intro.it.md b/docs/content/admin/admin_intro/intro.it.md new file mode 100644 index 0000000000..65d1d4f3b3 --- /dev/null +++ b/docs/content/admin/admin_intro/intro.it.md @@ -0,0 +1,10 @@ +--- +title: Controlli di amministrazione di DefectDojo +description: Controlli amministrativi per configurare, proteggere e mantenere la tua + istanza DefectDojo. +weight: 0 +--- + +Le azioni di amministrazione in DefectDojo forniscono i controlli necessari per configurare e mantenere la piattaforma in tutta l'organizzazione. Queste azioni sono pensate per gli amministratori responsabili della gestione degli utenti, della configurazione del sistema e di garantire che DefectDojo funzioni in modo sicuro e affidabile su larga scala. + +Le azioni amministrative permettono di gestire gli aspetti fondamentali di DefectDojo, tra cui i metodi di autenticazione, l'accesso degli utenti, le impostazioni globali e le integrazioni. Dalla configurazione iniziale alla manutenzione continua, questi controlli definiscono il comportamento di DefectDojo e il modo in cui gli utenti vi interagiscono. diff --git a/docs/content/admin/admin_intro/intro.pt-br.md b/docs/content/admin/admin_intro/intro.pt-br.md new file mode 100644 index 0000000000..213ded39d2 --- /dev/null +++ b/docs/content/admin/admin_intro/intro.pt-br.md @@ -0,0 +1,16 @@ +--- +title: Controles de Administração do DefectDojo +description: Controles administrativos para configurar, proteger e manter sua instância + do DefectDojo. +weight: 0 +--- + +As ações administrativas do DefectDojo fornecem os controles necessários para configurar e manter a +plataforma em toda a sua organização. Essas ações são projetadas para administradores responsáveis pelo +gerenciamento de usuários, pela configuração do sistema e por garantir que o DefectDojo opere de forma segura +e confiável em escala. + +As ações administrativas permitem gerenciar aspectos essenciais do DefectDojo, incluindo métodos de +autenticação, acesso de usuários, configurações globais e integrações. Desde a configuração inicial até a +manutenção contínua, esses controles definem como o DefectDojo se comporta e como os usuários interagem com +ele. diff --git a/docs/content/admin/admin_intro/intro.zh-hans.md b/docs/content/admin/admin_intro/intro.zh-hans.md new file mode 100644 index 0000000000..ea92ba605b --- /dev/null +++ b/docs/content/admin/admin_intro/intro.zh-hans.md @@ -0,0 +1,9 @@ +--- +title: DefectDojo 管理员控制 +description: 用于配置、保护和维护您的 DefectDojo 实例的管理控制项。 +weight: 0 +--- + +DefectDojo 中的管理员操作提供了跨组织配置和维护平台所需的各项控制手段。这些操作专为负责用户管理、系统配置以及确保 DefectDojo 在规模化运行中保持安全可靠的管理员而设计。 + +管理操作使您能够管理 DefectDojo 的核心方面,包括身份验证方式、用户访问、全局设置和集成。从初始设置到日常维护,这些控制项定义了 DefectDojo 的行为方式以及用户与之交互的方式。 diff --git a/docs/content/admin/diagnostics/PRO__diagnostics.it.md b/docs/content/admin/diagnostics/PRO__diagnostics.it.md new file mode 100644 index 0000000000..73eca84a81 --- /dev/null +++ b/docs/content/admin/diagnostics/PRO__diagnostics.it.md @@ -0,0 +1,169 @@ +--- +title: Diagnostica +description: 'Consulta il registro trasversale ai sottosistemi dei tentativi di integrazione: + cosa viene registrato, come filtrarlo, come vengono escluse le credenziali e chi + può vedere i dettagli tecnici' +weight: 1 +audience: pro +--- + +Diagnostica è un registro unico di ogni tentativo che DefectDojo effettua per comunicare con qualcosa al di fuori di sé stesso — e dei tentativi che altri sistemi effettuano per comunicare con esso. Quando un ticket non è mai comparso, una scansione non è mai stata importata o un utente non è riuscito ad accedere, questa è la pagina che indica cosa è successo, quando, con quale configurazione e chi lo ha provocato. + +Diagnostica è una funzionalità di **DefectDojo Pro**. La trovi in **Connect > Diagnostics**. + +![Il registro di Diagnostica, vista Errors](images/diagnostics_errors.png) + +## Cosa viene registrato + +Viene scritta una riga per ogni tentativo, da ogni sottosistema che comunica con l'esterno di DefectDojo: + +| Origine | Cosa genera le righe | +| --- | --- | +| **Connector** | Esecuzioni di discovery e sincronizzazione dei connector in ingresso | +| **Integratore downstream** | Invii verso Jira, GitHub, GitLab, ServiceNow e gli altri connector downstream | +| **Jira** | L'integrazione Jira legacy: invii, commenti e anteprime | +| **SSO (OIDC/OAuth2)** | Tentativi di accesso tramite un provider OAuth | +| **SAML** | Asserzioni SAML, compresi gli errori di firma e di attributo | +| **LDAP** | Bind e ricerche LDAP | +| **Import / Reimport** | Caricamenti di scansioni, tramite UI, API o pianificazione | +| **Motore delle regole** | Valutazioni delle regole e le azioni che tentano di eseguire | +| **Pianificazione** | Esecuzioni pianificate, comprese quelle mai avviate | +| **Sensei** | Scansioni dei repository ed esecuzioni di fix | +| **Notifica** | Invio di notifiche in uscita | +| **Sistema** | Attività a livello di istanza che non appartiene a nessun prodotto | + +Le righe vengono scritte *insieme* al sottosistema, mai al suo posto. Ogni adapter è collegato al record di origine ed è deliberatamente fail-safe: se la scrittura di una riga diagnostica genera un errore, l'errore viene ignorato e l'operazione originale prosegue. Diagnostica non può quindi mai essere la causa del fallimento di un invio, di un'importazione o di un accesso. + +Poiché le righe sono associate al record che le ha generate, salvare di nuovo un record di origine aggiorna la riga diagnostica esistente invece di aggiungerne una duplicata. Un tentativo corrisponde a una riga per tutta la sua durata, da `Queued` a `Running` fino al suo esito. + +### Campi di una riga + +| Campo | Significato | +| --- | --- | +| **When** | Quando la riga è stata registrata; **Started**, **Finished** e **Duration** descrivono il tentativo stesso | +| **Source** | Il sottosistema, dalla tabella sopra | +| **Provider** | Lo strumento o il provider specifico all'interno di quell'origine (`jira`, `github`, `okta`, il nome di uno scanner) | +| **Operation** | Cosa è stato tentato (`push`, `sync`, `login`, `reimport`, `rule_run`) | +| **Status** | `Queued`, `Running`, `Success`, `Failed`, `Timed out`, `Skipped` o `Dry run` | +| **Severity** | `Info`, `Warning`, `Error` o `Critical` | +| **Summary** | Un esito in una riga, leggibile a colpo d'occhio | +| **Trigger** | Cosa ha fatto scattare il tentativo: `UI`, `API`, `Scheduled`, `Webhook`, `Automatic`, `Command line` o `System` | +| **Triggered by** | L'utente responsabile, oppure `System` per le operazioni non presidiate | +| **Asset** | Il prodotto a cui appartiene il tentativo; vuoto significa a livello di istanza | +| **Related object** | Il riscontro, l'engagement o l'altro record a cui si riferiva il tentativo | +| **Configuration** | Quale configurazione è stata usata, in base alla sua etichetta | +| **External reference** | L'identificativo restituito dall'altro sistema, ad esempio la chiave di un issue creato | +| **Correlation ID** | Collega tra loro le righe di una stessa operazione logica | +| **Reported detail** e **Context** | Il dettaglio tecnico completo (con restrizioni, vedi [Chi vede cosa](#who-sees-what)) | + +## Le quattro viste + +Le schede sopra la tabella sono punti di partenza salvati, non filtri da ricostruire ogni volta: + +* **Errors** — errori e timeout. La prima da aprire. +* **Successes** — la prova che un'integrazione funzionante sta funzionando, utile quando qualcuno segnala che "non si sta sincronizzando nulla". +* **Never completed** — tentativi ancora `Queued` o `Running` ben oltre il momento in cui avrebbero dovuto concludersi. Sono i casi silenziosi: nulla è fallito, quindi nulla è stato segnalato, ma nulla è nemmeno arrivato. +* **All events** — tutto, senza filtri. + +![Tutti gli eventi, con ogni origine mostrata](images/diagnostics_all_events.png) + +La vista attiva fa parte dell'URL della pagina, quindi una vista è collegabile tramite link e sopravvive a un aggiornamento. + +## Restringere l'elenco + +* **Time range** — 24 ore, 7 giorni, 30 giorni o 90 giorni, dai pulsanti nell'intestazione. +* **Conteggi per origine** — i conteggi colorati sotto le schede di riepilogo sono anche filtri rapidi. Fai clic su uno per mostrare solo quell'origine; fai clic di nuovo (oppure su **Clear source filter**) per tornare indietro. Ne è attivo uno o nessuno alla volta. +* **Filtri e ordinamento per colonna** — ogni colonna filtra e ordina, incluse Severity e Source. Severity ordina in base alla gravità (`Critical` → `Info`) anziché alfabeticamente, e Source ordina in base all'etichetta visualizzata anziché al valore memorizzato sottostante. +* **Keyword Search** — cerca contemporaneamente in tutti i campi di testo. +* **Preferenze di colonna** — il selettore di colonne e i suoi layout salvati si comportano come in ogni altro elenco di Pro. + +![Un conteggio per origine usato come filtro rapido](images/diagnostics_chip_filter.png) + +Fai clic sulla lente d'ingrandimento all'inizio di una riga per aprire l'intero tentativo: + +![Un singolo evento, con l'avviso di redazione](images/diagnostics_detail.png) + +## Le credenziali vengono rimosse prima che la riga venga scritta + +Gli errori di integrazione citano la richiesta che è fallita, e queste citazioni contengono segreti: un header `Authorization`, un token in una query string, una password all'interno di un URL di connessione. Diagnostica li elimina **in ingresso**, così il valore originale non raggiunge mai il database e nessun ripensamento successivo può esporlo. + +Vengono ripulite due cose: + +* **I valori sotto chiavi dalla forma di credenziale** — qualsiasi cosa la cui chiave assomigli a un segreto (`password`, `token`, `secret`, `api_key`, `authorization`, `private_key` e simili, in qualsiasi combinazione di maiuscole/minuscole o con trattini o spazi). Un piccolo insieme di chiavi è esente perché conta solo la loro *presenza*, mai il loro contenuto. +* **I valori che sembrano credenziali ovunque compaiano** — header di autorizzazione bearer e basic, JWT, credenziali incorporate negli URL (`https://user:pass@host`), prefissi di token dei vendor riconoscibili e blocchi PEM. + +Ognuno viene sostituito con `[redacted]`. Il messaggio circostante viene mantenuto, così l'errore resta leggibile: + +```text +401 Unauthorized: Authorization: [redacted] +upload rejected: https://svc:[redacted]@sftp.example/out/… +``` + +I valori lunghi vengono troncati e il contesto profondamente annidato viene appiattito, così un payload enorme non può gonfiare la tabella. + +Quando qualcosa è stato rimosso da una riga, la riga lo segnala, invece di lasciarti chiedere se il campo fosse vuoto o svuotato. + +> **La redazione è best-effort per design.** Il meccanismo di pulizia riconosce le *forme* delle credenziali. Un segreto che assomiglia a prosa comune, sotto una chiave che non sembra sensibile, può comunque essere registrato. Considera Diagnostica come un log operativo, non come un luogo in cui i segreti sono garantiti assenti — e mantieni il dettaglio tecnico riservato a chi ne ha bisogno. + +## Chi vede cosa + +Diagnostica è organizzata su livelli, perché il riepilogo di un errore è utile per il proprietario di un prodotto, mentre la richiesta grezza che ne sta dietro no. + +| | Superuser | Tutti gli altri | +| --- | --- | --- | +| Righe per i prodotti su cui sono autorizzati | Sì | Sì | +| Righe a livello di istanza (nessun prodotto) | Sì | No | +| Summary, source, status, severity, timing, configuration | Sì | Sì | +| **Reported detail**, **Context**, **Remote IP** | Sì | Nascosti, ed etichettati come tali | + +Un utente non superuser vede che un dettaglio esiste e viene nascosto, invece di un campo vuoto che sembra un dato mancante. Le righe a livello di istanza — SSO, SAML, LDAP e altre attività che non appartengono a nessun prodotto — sono riservate ai superuser, poiché non esiste alcuna appartenenza a un prodotto che potrebbe concedere l'accesso a esse. + +## Per quanto tempo vengono conservati i record + +Un'attività pianificata riduce il registro affinché non possa crescere senza limiti: + +| Severity | Conservato per | +| --- | --- | +| `Info` | 30 giorni | +| `Warning`, `Error`, `Critical` | 180 giorni | + +Entrambe le finestre sono configurabili con le impostazioni `DIAGNOSTIC_EVENT_INFO_RETENTION_DAYS` e `DIAGNOSTIC_EVENT_RETENTION_DAYS`. L'eliminazione viene eseguita a lotti, così una grande cancellazione non mantiene aperta una transazione lunga. + +## API + +Il registro è di sola lettura tramite API, all'indirizzo `/api/v2/diagnostic_events/`: + +| Endpoint | Restituisce | +| --- | --- | +| `GET /api/v2/diagnostic_events/` | L'elenco, con i filtri sottostanti | +| `GET /api/v2/diagnostic_events/{id}/` | Un evento | +| `GET /api/v2/diagnostic_events/summary/` | I conteggi dietro le schede di intestazione, compresi i totali per origine | +| `GET /api/v2/diagnostic_events/choices/` | I valori validi per `source`, `status`, `severity` e `trigger` | + +Parametri utili: + +| Parametro | Effetto | +| --- | --- | +| `source`, `status`, `severity`, `trigger` | Accettano più valori separati da virgola contemporaneamente | +| `failures_only=true` | Errori e timeout | +| `unresolved_only=true` | Tentativi ancora in coda o in esecuzione | +| `product_name` | Filtra per nome del prodotto | +| `object_model` | Filtra per il tipo di record a cui si riferiva il tentativo | +| `o=` | Ordinamento, con prefisso `-` per invertire (`o=-created_at`) | + +Si applicano le stesse regole di accesso: un utente non superuser ottiene righe limitate ai propri prodotti, con i campi riservati nascosti. + +## Capire cosa è andato storto + +* **Un ticket non è mai comparso.** Filtra Source sull'integratore (o su Jira), quindi leggi Status. `Failed` fornisce il motivo in Summary; `Queued` molto tempo dopo il fatto significa che il job non è mai stato eseguito, il che è un problema di worker o di pianificazione più che di credenziali. +* **Un utente non riesce ad accedere.** Filtra Source su SSO, SAML o LDAP e leggi l'errore per il suo tentativo — una firma di asserzione errata, un bind rifiutato, un attributo non corrispondente. Queste righe sono a livello di istanza, quindi sono riservate ai superuser. +* **Una scansione non è comparsa.** Filtra Source su Import / Reimport. Guarda Trigger per distinguere un caricamento pianificato non presidiato da uno manuale di qualcuno, e Triggered by per sapere a chi chiedere. +* **Qualcosa continua a riprovare all'infinito.** Ordina per Correlation ID, o filtra su uno specifico, per vedere insieme ogni tentativo della stessa operazione logica. +* **"Non funziona niente."** Apri prima Successes per la stessa finestra temporale. Un elenco sano lì trasforma un'interruzione vaga in una specifica. + +## Correlati + +* [Feature Flags](/admin/feature_flags/pro__feature_flags/) — attivare e disattivare le funzionalità Pro opzionali +* [Connectors](/connectors/upstream/about/) — importare i riscontri +* [Pro Integrations](/connectors/downstream/about/) — esportare i riscontri +* [Single Sign-On](/admin/sso/) — i provider di identità i cui tentativi di accesso compaiono qui diff --git a/docs/content/admin/diagnostics/PRO__diagnostics.pt-br.md b/docs/content/admin/diagnostics/PRO__diagnostics.pt-br.md new file mode 100644 index 0000000000..bcb041b811 --- /dev/null +++ b/docs/content/admin/diagnostics/PRO__diagnostics.pt-br.md @@ -0,0 +1,169 @@ +--- +title: Diagnósticos +description: 'Leia o registro entre subsistemas das tentativas de integração: o que + é registrado, como filtrá-lo, como as credenciais são mantidas fora dele e quem + pode ver o detalhe técnico' +weight: 1 +audience: pro +--- + +Diagnósticos é um único registro de todas as tentativas que o DefectDojo faz para se comunicar com algo fora dele — e das tentativas que outros sistemas fazem para se comunicar com ele. Quando um ticket nunca aparece, um scan nunca é importado, ou um usuário não consegue fazer login, esta é a página que mostra o que aconteceu, quando, com qual configuração, e quem disparou a tentativa. + +Diagnósticos é um recurso do **DefectDojo Pro**. Encontre-o em **Connect > Diagnostics**. + +![The Diagnostics ledger, Errors view](images/diagnostics_errors.png) + +## O que é registrado + +Uma linha é gravada por tentativa, vinda de todo subsistema que se comunica para fora do DefectDojo: + +| Fonte | O que gera linhas | +| --- | --- | +| **Connector** | Execuções de descoberta e sincronização dos conectores upstream | +| **Downstream integrator** | Envios (pushes) para Jira, GitHub, GitLab, ServiceNow e os demais conectores downstream | +| **Jira** | A integração legada do Jira: envios, comentários e pré-visualizações | +| **SSO (OIDC/OAuth2)** | Tentativas de login por meio de um provedor OAuth | +| **SAML** | Asserções SAML, incluindo falhas de assinatura e de atributos | +| **LDAP** | Binds e consultas (lookups) LDAP | +| **Import / Reimport** | Envios de scans, seja pela interface, pela API ou por agendamento | +| **Rules engine** | Avaliações de regras e as ações que elas tentam executar | +| **Scheduling** | Execuções agendadas, incluindo as que nunca chegaram a iniciar | +| **Sensei** | Varreduras de repositórios e execuções de correção | +| **Notification** | Envio de notificações de saída | +| **System** | Atividade em nível de instância que não pertence a nenhum produto | + +As linhas são gravadas *ao lado* do subsistema, nunca em seu lugar. Cada adaptador está vinculado ao registro de origem e é deliberadamente à prova de falhas: se a gravação de uma linha de diagnóstico gerar um erro, esse erro é engolido e a operação original continua normalmente. Por isso, o Diagnósticos nunca pode ser a causa de uma falha em um envio, importação ou login. + +Como as linhas são indexadas pelo registro que as originou, salvar novamente um registro de origem atualiza a linha de diagnóstico existente em vez de criar uma duplicata. Uma tentativa é uma linha durante toda a sua existência, desde `Queued`, passando por `Running`, até o resultado final. + +### Campos de uma linha + +| Campo | Significado | +| --- | --- | +| **Quando** | Quando a linha foi registrada; **Iniciado**, **Concluído** e **Duração** descrevem a própria tentativa | +| **Fonte** | O subsistema, conforme a tabela acima | +| **Provedor** | A ferramenta ou provedor específico dentro dessa fonte (`jira`, `github`, `okta`, o nome de um scanner) | +| **Operação** | O que foi tentado (`push`, `sync`, `login`, `reimport`, `rule_run`) | +| **Status** | `Queued`, `Running`, `Success`, `Failed`, `Timed out`, `Skipped` ou `Dry run` | +| **Severidade** | `Info`, `Warning`, `Error` ou `Critical` | +| **Resumo** | Um resultado em uma linha, seguro de ler rapidamente | +| **Gatilho** | O que disparou a tentativa: `UI`, `API`, `Scheduled`, `Webhook`, `Automatic`, `Command line` ou `System` | +| **Acionado por** | O usuário responsável, ou `System` para trabalho não supervisionado | +| **Ativo** | O produto ao qual a tentativa pertence; vazio significa nível de instância | +| **Objeto relacionado** | O achado, engajamento ou outro registro sobre o qual a tentativa tratava | +| **Configuração** | Qual configuração foi usada, por seu rótulo | +| **Referência externa** | O identificador retornado pelo outro sistema, como a chave de um issue criado | +| **ID de correlação** | Relaciona as linhas de uma mesma operação lógica | +| **Detalhe relatado** e **Contexto** | O detalhe técnico completo (restrito, veja [Quem vê o quê](#who-sees-what)) | + +## As quatro visualizações + +As abas acima da tabela são pontos de partida salvos, não filtros que você precisa reconstruir toda vez: + +* **Errors** — falhas e timeouts. A primeira que você deve abrir. +* **Successes** — prova de que uma integração que funciona está de fato funcionando, útil quando alguém relata que "nada está sincronizando". +* **Never completed** — tentativas ainda em `Queued` ou `Running` muito depois do momento em que deveriam ter terminado. São os casos silenciosos: nada falhou, então nada foi relatado, mas também nada chegou. +* **All events** — tudo, sem filtro. + +![All events, showing every source](images/diagnostics_all_events.png) + +A visualização ativa faz parte da URL da página, então uma visualização pode ser compartilhada por link e sobrevive a uma atualização da página. + +## Restringindo a lista + +* **Intervalo de tempo** — 24 horas, 7 dias, 30 dias ou 90 dias, pelos botões no cabeçalho. +* **Contagens por fonte** — as contagens coloridas abaixo dos cartões de resumo também funcionam como filtros rápidos. Clique em uma para mostrar apenas aquela fonte; clique novamente (ou em **Clear source filter**) para voltar. No máximo uma fica ativa por vez. +* **Filtros e ordenação por coluna** — cada coluna permite filtrar e ordenar, incluindo Severidade e Fonte. A Severidade ordena por gravidade (`Critical` → `Info`) em vez de ordem alfabética, e a Fonte ordena pelo rótulo exibido, não pelo valor armazenado internamente. +* **Keyword Search** — pesquisa em todos os campos de texto ao mesmo tempo. +* **Preferências de colunas** — o seletor de colunas e os layouts salvos funcionam da mesma forma que em qualquer outra lista do Pro. + +![A source count used as a quick filter](images/diagnostics_chip_filter.png) + +Clique na lupa no início de uma linha para abrir a tentativa completa: + +![A single event, including the redaction notice](images/diagnostics_detail.png) + +## As credenciais são removidas antes da linha ser gravada + +Erros de integração citam a requisição que falhou, e essas citações carregam segredos: um cabeçalho `Authorization`, um token em uma query string, uma senha dentro de uma URL de conexão. O Diagnósticos remove esses valores **na entrada**, de modo que o valor original nunca chega ao banco de dados e nenhuma mudança de ideia posterior pode expô-lo. + +Duas coisas são higienizadas: + +* **Valores sob chaves com formato de credencial** — qualquer coisa cuja chave pareça um segredo (`password`, `token`, `secret`, `api_key`, `authorization`, `private_key` e similares, em qualquer capitalização ou com traços ou espaços). Um pequeno conjunto de chaves é isento, porque só a *presença* delas importa, nunca o conteúdo. +* **Valores que parecem credenciais onde quer que apareçam** — cabeçalhos de autorização bearer e basic, JWTs, credenciais embutidas em URLs (`https://user:pass@host`), prefixos de token reconhecíveis de fornecedores e blocos PEM. + +Cada um é substituído por `[redacted]`. A mensagem ao redor é mantida, para que o erro continue legível: + +```text +401 Unauthorized: Authorization: [redacted] +upload rejected: https://svc:[redacted]@sftp.example/out/… +``` + +Valores longos são truncados, e contextos profundamente aninhados são achatados, para que um payload enorme não sobrecarregue a tabela. + +Quando algo é removido de uma linha, a própria linha indica isso, em vez de deixar você se perguntando se o campo estava vazio ou foi esvaziado. + +> **A redação é, por design, uma tentativa de melhor esforço.** O higienizador reconhece *formatos* de credenciais. Um segredo que se pareça com texto comum, sob uma chave que não pareça sensível, ainda pode ser registrado. Trate o Diagnósticos como um log operacional, não como um lugar onde a ausência de segredos é garantida — e mantenha o detalhe técnico restrito a quem realmente precisa dele. + +## Quem vê o quê + +O Diagnósticos é dividido por nível de acesso, porque o resumo de uma falha é útil para o dono de um produto, mas a requisição bruta por trás dela não é. + +| | Superuser | Everyone else | +| --- | --- | --- | +| Linhas dos produtos aos quais têm autorização | Sim | Sim | +| Linhas em nível de instância (sem produto) | Sim | Não | +| Resumo, fonte, status, severidade, tempos, configuração | Sim | Sim | +| **Detalhe relatado**, **Contexto**, **IP remoto** | Sim | Ocultado, e identificado como ocultado | + +Um usuário que não é superusuário vê que um detalhe existe e está sendo ocultado, em vez de um campo vazio que pareça um dado ausente. As linhas em nível de instância — SSO, SAML, LDAP e outras atividades que não pertencem a nenhum produto — são exclusivas para superusuários, já que não há associação a nenhum produto que pudesse conceder acesso a elas. + +## Por quanto tempo os registros são mantidos + +Uma tarefa agendada faz a limpeza do registro para que ele não cresça sem limite: + +| Severidade | Mantido por | +| --- | --- | +| `Info` | 30 dias | +| `Warning`, `Error`, `Critical` | 180 dias | + +Ambas as janelas são configuráveis com as configurações `DIAGNOSTIC_EVENT_INFO_RETENTION_DAYS` e `DIAGNOSTIC_EVENT_RETENTION_DAYS`. A exclusão é feita em lotes, para que uma purga grande não mantenha uma transação longa aberta. + +## API + +O registro é somente leitura pela API, em `/api/v2/diagnostic_events/`: + +| Endpoint | Retorna | +| --- | --- | +| `GET /api/v2/diagnostic_events/` | A lista, com os filtros abaixo | +| `GET /api/v2/diagnostic_events/{id}/` | Um evento | +| `GET /api/v2/diagnostic_events/summary/` | As contagens por trás dos cartões do cabeçalho, incluindo os totais por fonte | +| `GET /api/v2/diagnostic_events/choices/` | Os valores válidos para `source`, `status`, `severity` e `trigger` | + +Parâmetros úteis: + +| Parâmetro | Efeito | +| --- | --- | +| `source`, `status`, `severity`, `trigger` | Aceitam vários valores separados por vírgula de uma vez | +| `failures_only=true` | Falhas e timeouts | +| `unresolved_only=true` | Tentativas ainda em fila ou em execução | +| `product_name` | Filtra pelo nome do produto | +| `object_model` | Filtra pelo tipo de registro sobre o qual a tentativa tratava | +| `o=` | Ordenação, com o prefixo `-` para inverter (`o=-created_at`) | + +As mesmas regras de acesso se aplicam: um usuário que não é superusuário recebe linhas restritas aos seus produtos, com os campos restritos ocultados. + +## Descobrindo o que deu errado + +* **Um ticket nunca apareceu.** Filtre a Fonte pelo integrador (ou Jira) e leia o Status. `Failed` fornece o motivo no Resumo; `Queued` muito tempo depois do fato indica que o job nunca chegou a rodar, o que é um problema de worker ou de agendamento, e não de credencial. +* **Um usuário não consegue fazer login.** Filtre a Fonte por SSO, SAML ou LDAP, e leia a falha da tentativa dele — uma assinatura de asserção inválida, um bind rejeitado, um atributo incompatível. Essas linhas são em nível de instância, portanto exclusivas para superusuários. +* **Um scan não apareceu.** Filtre a Fonte por Import / Reimport. Observe o Gatilho para distinguir um envio agendado e não supervisionado de um envio manual de alguém, e o Acionado por para saber a quem perguntar. +* **Algo está tentando novamente sem parar.** Ordene por ID de correlação, ou filtre por um valor específico, para ver juntas todas as tentativas da mesma operação lógica. +* **"Nada está funcionando."** Abra primeiro o Successes para a mesma janela de tempo. Uma lista saudável ali transforma uma indisponibilidade vaga em algo específico. + +## Relacionados + +* [Feature Flags](/admin/feature_flags/pro__feature_flags/) — ativando e desativando recursos opcionais do Pro +* [Connectors](/connectors/upstream/about/) — trazendo achados para dentro +* [Pro Integrations](/connectors/downstream/about/) — enviando achados para fora +* [Single Sign-On](/admin/sso/) — os provedores de identidade cujas tentativas de login aparecem aqui diff --git a/docs/content/admin/diagnostics/PRO__diagnostics.zh-hans.md b/docs/content/admin/diagnostics/PRO__diagnostics.zh-hans.md new file mode 100644 index 0000000000..5fca3fa525 --- /dev/null +++ b/docs/content/admin/diagnostics/PRO__diagnostics.zh-hans.md @@ -0,0 +1,167 @@ +--- +title: 诊断 +description: 查阅跨子系统的集成尝试台账：记录了哪些内容、如何筛选、如何避免记录凭据，以及谁可以查看技术细节 +weight: 1 +audience: pro +--- + +诊断（Diagnostics）是一份统一台账，记录了 DefectDojo 与外部系统通信的每一次尝试，也记录了其他系统与它通信的尝试。当工单一直没有出现、扫描始终未导入，或用户无法登录时，这个页面会告诉你发生了什么、发生在何时、涉及哪项配置，以及是谁触发的。 + +诊断是 **DefectDojo Pro** 功能。可在 **Connect > Diagnostics** 下找到它。 + +![诊断台账，错误视图](images/diagnostics_errors.png) + +## 记录了哪些内容 + +每次尝试都会写入一行记录，涵盖所有会与 DefectDojo 外部通信的子系统： + +| 来源 | 产生记录的场景 | +| --- | --- | +| **连接器（Connector）** | 上游连接器的发现和同步运行 | +| **下游集成器（Downstream integrator）** | 推送到 Jira、GitHub、GitLab、ServiceNow 及其他下游连接器 | +| **Jira** | 旧版 Jira 集成：推送、评论和预览 | +| **SSO（OIDC/OAuth2）** | 通过 OAuth 提供商进行的登录尝试 | +| **SAML** | SAML 断言，包括签名和属性失败 | +| **LDAP** | LDAP 绑定和查找 | +| **导入 / 重新导入（Import / Reimport）** | 扫描上传，无论通过 UI、API 还是计划任务 | +| **规则引擎（Rules engine）** | 规则评估及其尝试执行的操作 | +| **计划任务（Scheduling）** | 计划运行，包括从未启动的运行 | +| **Sensei** | 代码仓库扫描和修复运行 | +| **通知（Notification）** | 出站通知投递 | +| **系统（System）** | 不属于任何产品的实例级活动 | + +记录是与子系统*并行*写入的，绝不会取代子系统本身。每个适配器都挂接在源记录上，并被刻意设计为故障安全（fail-safe）：如果写入诊断记录时出错，该错误会被吞掉，原始操作会继续进行。因此，诊断功能永远不会成为推送、导入或登录失败的原因。 + +由于记录是以产生它们的源记录为键的，重新保存某个源记录会更新其已有的诊断记录，而不会新增一条重复记录。一次尝试在其整个生命周期内始终对应一行记录，从 `Queued` 经过 `Running` 直到得出结果。 + +### 记录中的字段 + +| 字段 | 含义 | +| --- | --- | +| **When** | 记录写入的时间；**Started**、**Finished** 和 **Duration** 描述的是尝试本身的时间信息 | +| **Source** | 子系统，取自上表 | +| **Provider** | 该来源下具体的工具或提供商（如 `jira`、`github`、`okta`，或某个扫描器名称） | +| **Operation** | 所尝试执行的操作（`push`、`sync`、`login`、`reimport`、`rule_run`） | +| **Status** | `Queued`、`Running`、`Success`、`Failed`、`Timed out`、`Skipped` 或 `Dry run` | +| **Severity** | `Info`、`Warning`、`Error` 或 `Critical` | +| **Summary** | 一行结果摘要，可一目了然地安全查看 | +| **Trigger** | 触发该尝试的方式：`UI`、`API`、`Scheduled`、`Webhook`、`Automatic`、`Command line` 或 `System` | +| **Triggered by** | 负责该操作的用户，若为无人值守的操作则显示 `System` | +| **Asset** | 该尝试所属的产品；为空表示是实例级别的 | +| **Related object** | 该尝试所涉及的发现项、测试活动或其他记录 | +| **Configuration** | 使用的是哪一项配置，以其标签标识 | +| **External reference** | 另一系统返回的标识符，例如所创建工单的编号 | +| **Correlation ID** | 将同一逻辑操作产生的多条记录关联在一起 | +| **Reported detail** 和 **Context** | 完整的技术细节（受限查看，参见 [谁能看到什么](#who-sees-what)） | + +## 四种视图 + +表格上方的标签页是预先保存好的起点，而不是需要你重新搭建的筛选条件： + +* **Errors（错误）** — 失败和超时。应首先打开的视图。 +* **Successes（成功）** — 证明一项正常工作的集成确实在正常工作，当有人反馈"什么都没有同步"时很有用。 +* **Never completed（从未完成）** — 早已过了应完成时间、却仍处于 `Queued` 或 `Running` 状态的尝试。这些是"沉默"的问题：没有任何失败，因此也没有任何报错，但结果也始终没有到达。 +* **All events（所有事件）** — 全部内容，不做任何筛选。 + +![所有事件，显示全部来源](images/diagnostics_all_events.png) + +当前所选视图会体现在页面 URL 中，因此某个视图是可链接的，刷新页面后依然保留。 + +## 缩小列表范围 + +* **Time range（时间范围）** — 24 小时、7 天、30 天或 90 天，可在页头的按钮中选择。 +* **Source counts（来源计数）** — 汇总卡片下方的彩色计数同时也是快捷筛选器。点击其中一个即可只显示该来源；再次点击（或点击 **Clear source filter**）即可返回。同一时间只能激活一个或不激活任何一个。 +* **Per-column filters and sorting（按列筛选和排序）** — 每一列都支持筛选和排序，包括 Severity 和 Source。Severity 按严重程度排序（`Critical` → `Info`），而不是按字母顺序；Source 按你看到的标签排序，而不是按其底层存储的值排序。 +* **Keyword Search（关键字搜索）** — 同时搜索所有文本字段。 +* **Column preferences（列首选项）** — 列选择器及其已保存的布局，行为与其他所有 Pro 列表页面一致。 + +![用作快捷筛选器的来源计数](images/diagnostics_chip_filter.png) + +点击某一行开头的放大镜图标，即可打开该次尝试的完整详情： + +![单个事件，包含脱敏提示](images/diagnostics_detail.png) + +## 记录写入前会先移除凭据 + +集成错误会引用失败的请求内容，而这些引用中可能带有敏感信息：一个 `Authorization` 请求头、查询字符串中的令牌、连接 URL 中的密码。诊断功能会**在写入之前**先将其剥离，因此原始值永远不会进入数据库，日后也不会因为某个疏忽而泄露。 + +有两类内容会被清除： + +* **凭据形态键名下的值** — 任何键名看起来像是敏感信息的字段（`password`、`token`、`secret`、`api_key`、`authorization`、`private_key` 及类似名称，不区分大小写，也不论是否带连字符或空格）。有一小部分键名例外，因为重要的只是它们*是否存在*，而不是其内容。 +* **无论出现在何处、看起来像凭据的值** — bearer 和 basic 授权请求头、JWT、嵌入在 URL 中的凭据（`https://user:pass@host`）、可识别的厂商令牌前缀，以及 PEM 代码块。 + +这些内容都会被替换为 `[redacted]`。周围的信息会被保留，因此错误信息依然可读： + +```text +401 Unauthorized: Authorization: [redacted] +upload rejected: https://svc:[redacted]@sftp.example/out/… +``` + +过长的值会被截断，嵌套层级很深的上下文也会被展平，这样一个巨大的负载就不会把表格撑得过大。 + +只要某一行中的内容被移除过，该行就会明确标注这一点，而不会让你去猜测某个字段究竟是本来为空，还是被清空的。 + +> **脱敏处理设计上只是尽力而为。** 清除机制识别的是凭据的*形态*。如果某个敏感信息看起来像普通文字，且所在的键名也不像是敏感字段，它仍然可能被记录下来。请把诊断功能当作一份运维日志，而不要认为其中一定不含任何敏感信息——并且应将技术细节的可见范围限制在确实需要的人员范围内。 + +## 谁能看到什么 + +诊断功能的可见性是分层的，因为失败的摘要信息对产品负责人有用，而其背后的原始请求内容则不然。 + +| | 超级用户 | 其他所有人 | +| --- | --- | --- | +| 其被授权访问的产品所对应的记录 | 是 | 是 | +| 实例级记录（不属于任何产品） | 是 | 否 | +| 摘要、来源、状态、严重程度、时间信息、配置 | 是 | 是 | +| **Reported detail**、**Context**、**Remote IP** | 是 | 隐藏，并标注为已隐藏 | + +非超级用户会看到某项细节确实存在但被隐藏了，而不是一个看起来像数据缺失的空字段。实例级记录——SSO、SAML、LDAP 以及其他不属于任何产品的活动——仅限超级用户查看，因为没有任何产品成员身份能够授予对它们的访问权限。 + +## 记录保留多长时间 + +一项计划任务会定期清理台账，防止其无限增长： + +| 严重程度 | 保留时长 | +| --- | --- | +| `Info` | 30 天 | +| `Warning`、`Error`、`Critical` | 180 天 | + +这两个保留期都可以通过 `DIAGNOSTIC_EVENT_INFO_RETENTION_DAYS` 和 `DIAGNOSTIC_EVENT_RETENTION_DAYS` 设置项进行配置。删除操作分批执行，因此一次大规模清理不会长时间占用事务。 + +## API + +该台账通过 API 只能读取，路径为 `/api/v2/diagnostic_events/`： + +| 端点 | 返回内容 | +| --- | --- | +| `GET /api/v2/diagnostic_events/` | 列表，可结合下方的筛选条件 | +| `GET /api/v2/diagnostic_events/{id}/` | 单个事件 | +| `GET /api/v2/diagnostic_events/summary/` | 页头卡片背后的计数，包括按来源统计的数量 | +| `GET /api/v2/diagnostic_events/choices/` | `source`、`status`、`severity` 和 `trigger` 的有效取值 | + +常用参数： + +| 参数 | 作用 | +| --- | --- | +| `source`、`status`、`severity`、`trigger` | 可同时接受多个以逗号分隔的值 | +| `failures_only=true` | 失败和超时 | +| `unresolved_only=true` | 仍处于排队或运行中的尝试 | +| `product_name` | 按产品名称筛选 | +| `object_model` | 按尝试所涉及的记录类型筛选 | +| `o=` | 排序，前面加 `-` 表示逆序（`o=-created_at`） | + +同样的访问规则在此依然适用：非超级用户只能获取限定在其产品范围内的记录，且受限字段会被隐藏。 + +## 排查问题所在 + +* **工单一直没有出现。** 将 Source 筛选为对应的集成器（或 Jira），然后查看 Status。`Failed` 会在 Summary 中给出原因；如果早已过了预期时间却仍是 `Queued`，说明该任务根本没有运行，这是工作进程或调度方面的问题，而不是凭据问题。 +* **用户无法登录。** 将 Source 筛选为 SSO、SAML 或 LDAP，查看其登录尝试的失败原因——可能是断言签名有误、绑定被拒绝，或属性不匹配。这些记录属于实例级别，仅限超级用户查看。 +* **扫描没有出现。** 将 Source 筛选为 Import / Reimport。查看 Trigger 可以区分是无人值守的计划上传还是某人手动上传的，查看 Triggered by 可以知道该找谁询问。 +* **某件事似乎在无休止地重试。** 按 Correlation ID 排序，或按某个 Correlation ID 筛选，即可将同一逻辑操作的所有尝试集中查看。 +* **"什么都不工作了。"** 先打开同一时间范围内的 Successes 视图。如果那里的列表状况良好，就能把一次含糊的"故障"定位成具体的问题。 + +## 相关内容 + +* [功能开关（Feature Flags）](/admin/feature_flags/pro__feature_flags/) — 启用和关闭可选的 Pro 功能 +* [连接器（Connectors）](/connectors/upstream/about/) — 拉取发现项 +* [Pro 集成（Pro Integrations）](/connectors/downstream/about/) — 推送发现项 +* [单点登录（Single Sign-On）](/admin/sso/) — 其登录尝试会出现在此处的身份提供商 diff --git a/docs/content/admin/diagnostics/_index.it.md b/docs/content/admin/diagnostics/_index.it.md new file mode 100644 index 0000000000..6bc92e909f --- /dev/null +++ b/docs/content/admin/diagnostics/_index.it.md @@ -0,0 +1,24 @@ +--- +title: Diagnostica +description: Un unico posto per vedere perché un tentativo di integrazione non è riuscito, + in tutti i sottosistemi che comunicano con l'esterno di DefectDojo +summary: '' +date: 2026-07-30 00:00:00+00:00 +lastmod: 2026-07-30 00:00:00+00:00 +draft: false +weight: 6 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +pro-feature: true +--- + +Quando qualcosa non arriva — un ticket mai creato, una scansione mai importata, un utente che non riesce ad accedere — le prove si trovavano nel sottosistema che si trovava a possedere quel tentativo. Diagnostica registra ognuno di questi tentativi in un unico registro, così la domanda "perché non è successo?" diventa una sola pagina invece di otto. + +Diagnostica è una funzionalità di **DefectDojo Pro**. + +* [Diagnostica](./pro__diagnostics/) — cosa viene registrato, come leggere e filtrare il registro, come vengono escluse le credenziali, chi può vedere il dettaglio tecnico e per quanto tempo vengono conservati i record. diff --git a/docs/content/admin/diagnostics/_index.pt-br.md b/docs/content/admin/diagnostics/_index.pt-br.md new file mode 100644 index 0000000000..f74526f812 --- /dev/null +++ b/docs/content/admin/diagnostics/_index.pt-br.md @@ -0,0 +1,24 @@ +--- +title: Diagnósticos +description: Um único lugar para ver por que uma tentativa de integração falhou, em + todos os subsistemas que se comunicam com algo fora do DefectDojo +summary: '' +date: 2026-07-30 00:00:00+00:00 +lastmod: 2026-07-30 00:00:00+00:00 +draft: false +weight: 6 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +pro-feature: true +--- + +Quando algo não chega — um ticket que nunca foi criado, um scan que nunca foi importado, um usuário que não consegue fazer login — a evidência costumava estar em qualquer subsistema que por acaso fosse dono da tentativa. O Diagnósticos registra cada uma dessas tentativas em um único registro central, de modo que a pergunta "por que isso não aconteceu?" vira uma única página em vez de oito. + +Diagnósticos é um recurso do **DefectDojo Pro**. + +* [Diagnósticos](./pro__diagnostics/) — o que é registrado, como ler e filtrar o registro, como as credenciais são mantidas fora dele, quem pode ver o detalhe técnico e por quanto tempo os registros são mantidos. diff --git a/docs/content/admin/diagnostics/_index.zh-hans.md b/docs/content/admin/diagnostics/_index.zh-hans.md new file mode 100644 index 0000000000..84cae5a831 --- /dev/null +++ b/docs/content/admin/diagnostics/_index.zh-hans.md @@ -0,0 +1,23 @@ +--- +title: 诊断 +description: 一个统一的位置，可用于查看任何与 DefectDojo 外部通信的子系统中，某次集成尝试失败的原因 +summary: '' +date: 2026-07-30 00:00:00+00:00 +lastmod: 2026-07-30 00:00:00+00:00 +draft: false +weight: 6 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +pro-feature: true +--- + +当某件事没有发生——一张从未创建的工单、一次从未导入的扫描、一个无法登录的用户——过去要查证据，得去这次尝试恰好归属的那个子系统里找。诊断功能会将每一次这样的尝试都记录到同一份台账中，因此"为什么这件事没有发生？"这个问题只需要看一个页面，而不必翻查八个地方。 + +诊断是 **DefectDojo Pro** 功能。 + +* [诊断（Diagnostics）](./pro__diagnostics/) — 记录了哪些内容、如何读取和筛选该台账、如何避免其中出现凭据、谁可以查看技术细节，以及记录会保留多长时间。 diff --git a/docs/content/admin/feature_flags/PRO__feature_flags.it.md b/docs/content/admin/feature_flags/PRO__feature_flags.it.md new file mode 100644 index 0000000000..b7fd0c7394 --- /dev/null +++ b/docs/content/admin/feature_flags/PRO__feature_flags.it.md @@ -0,0 +1,143 @@ +--- +title: Feature Flags +description: Attiva e disattiva le funzionalità opzionali di DefectDojo Pro dall'interfaccia + di DefectDojo +weight: 1 +audience: pro +--- + +I Feature Flags ti permettono di attivare e disattivare le funzionalità opzionali di DefectDojo Pro per la tua istanza — le funzionalità che in precedenza potevano essere abilitate solo contattando il supporto DefectDojo ora possono essere gestite autonomamente dall'interfaccia. + +La pagina Feature Flags è visibile solo ai **superuser**. Gli altri utenti, inclusi i Global Owner, non la vedono. + +## Apertura della pagina Feature Flags + +Vai su **Settings > Feature Flags** nella barra laterale sinistra. + +La pagina elenca ogni funzionalità opzionale con: + +* **Name** — il nome della funzionalità, con un tag **BETA** se è ancora in beta +* **Description** — cosa fa la funzionalità +* **Documentation link** — il collegamento alla documentazione, se disponibile per quella funzionalità +* **Toggle** — se la funzionalità è attualmente attiva + +Usa la casella di ricerca per filtrare l'elenco per nome o descrizione della funzionalità. + +### Funzionalità non elencate + +La pagina elenca le funzionalità che puoi scegliere di adottare. Due tipi di funzionalità non vi compaiono. + +**Sempre attive.** Una volta che una funzionalità raggiunge la disponibilità generale, è attiva per ogni istanza e smette di essere elencata, perché non c'è più alcuna decisione da prendere: + +* **Downstream Connectors** — vedi [Downstream Connectors](/connectors/downstream/about/) +* **Universal Parser** — vedi [Universal Parser](/import_data/pro/specialized_import/universal_parser/) +* **Asset Hierarchy** — vedi [Asset Hierarchy](/asset_modelling/pro_hierarchy/asset_hierarchy/) +* **Appearance** e **Feature Flags** — le due pagine Settings con lo stesso nome + +Non cambia nulla per la tua istanza se una di queste era già attiva. Se invece era disattivata, ora è attiva: queste funzionalità fanno parte di DefectDojo Pro anziché essere opzionali. Contatta il [supporto DefectDojo](mailto:support@defectdojo.com) se questo rappresenta un problema per la tua istanza. + +**Abilitate da DefectDojo su richiesta.** Alcune funzionalità dipendono da infrastrutture fornite per singola istanza, quindi vengono attivate da DefectDojo anziché da questa pagina: + +* **Scheduling Service** — vedi [Scheduling Rules](/automation/rules_engine/scheduling/) + +Contatta il [supporto DefectDojo](mailto:support@defectdojo.com) per farne abilitare una. Se è già attiva sulla tua istanza, rimane attiva. + +## Attivare o disattivare una funzionalità + +1. Trova la funzionalità nell'elenco. +2. Fai clic sul relativo toggle. +3. La modifica ha effetto immediatamente. Gli altri utenti la vedranno al successivo caricamento della pagina. + +Alcune funzionalità mostrano una finestra di conferma prima che la modifica venga applicata. Questo accade quando si abilita una funzionalità che comporta un avviso (ad esempio una che richiede un riavvio o può influire sui dati esistenti), oppure una che non può più essere disattivata. + +Disattivare una funzionalità è normalmente l'operazione inversa di attivarla. Le eccezioni sono indicate in [Quando un toggle è bloccato](#when-a-toggle-is-locked). + +### Organization / Asset Relabeling + +**Organization / Asset Relabeling** rinomina "Product Type" in "Organization" e "Product" in "Asset". È attiva per impostazione predefinita e si attiva/disattiva da questa pagina come qualsiasi altra funzionalità, ma è utile sapere quali parti di DefectDojo governa: + +* La **Pro UI** segue questo toggle. Le nuove etichette compaiono al successivo caricamento della pagina. +* Le pagine della **Classic UI**, i loro URL e i report generati prendono la denominazione dall'impostazione di deployment `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` (anch'essa attiva per impostazione predefinita), che viene letta all'avvio di DefectDojo. Questo toggle non le modifica, e nemmeno un riavvio le fa cambiare. + +Il toggle memorizzato è stato inizializzato a partire da quell'impostazione di deployment, quindi i due valori coincidono finché non ne modifichi uno. Se disattivi la rietichettatura qui e usi anche la Classic UI, imposta `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL=False` sul tuo deployment e riavvia in modo che entrambe le interfacce corrispondano. Su [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), contatta il [supporto DefectDojo](mailto:support@defectdojo.com) per far modificare l'impostazione di deployment. + +Per questo motivo la funzionalità ha un tag **Restart Recommended** nella pagina Feature Flags: la denominazione usata al di fuori della Pro UI viene fissata all'avvio del processo. In ogni caso la rietichettatura è puramente estetica. I modelli del database, i nomi dei campi e gli endpoint API restano invariati, quindi le automazioni esistenti continuano a funzionare. Vedi [Asset Hierarchy](/asset_modelling/pro_hierarchy/asset_hierarchy/). + +## Quando un toggle è bloccato + +Una funzionalità che non puoi modificare viene mostrata con un badge di blocco che ne spiega il motivo: + +| Badge | Cosa significa | Cosa fare | +| --- | --- | --- | +| **Managed by DefectDojo** | DefectDojo ha impostato questa funzionalità a livello centrale per la tua istanza. La tua impostazione non può sovrascriverla. | Contatta il [supporto DefectDojo](mailto:support@defectdojo.com) se hai bisogno di modificarla. | +| **Unavailable on This Deployment** | La funzionalità non è offerta per il tuo tipo di installazione. Vedi [Disponibilità delle funzionalità](#feature-availability) più sotto. | Nessuna azione. La funzionalità non è applicabile alla tua istanza. | +| **Cannot Be Disabled** | La funzionalità è già attiva ed è irreversibile. Non esiste un meccanismo per disattivarla. | Nessuna azione. È previsto. | +| **Managed by deployment** | La funzionalità è controllata dalla configurazione di deployment anziché da questa pagina. | Vedi [DefectDojo Pro (On-Premise)](#defectdojo-pro-on-premise) più sotto. | + +## DefectDojo Pro (Cloud) + +Su [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), **Settings > Feature Flags** è l'unico punto di cui hai bisogno. Attiva una funzionalità ed è subito operativa. + +Due cose sono gestite da DefectDojo anziché da te: + +* **Managed by DefectDojo** — la funzionalità è fissata a livello centrale. Contatta il [supporto DefectDojo](mailto:support@defectdojo.com) per farla modificare. +* **Managed by deployment** — la funzionalità fa parte di come viene provisionata la tua istanza. Contatta il supporto anche per queste, poiché le istanze Cloud non espongono la configurazione di deployment ai clienti. + +Le istanze Cloud hanno inoltre accesso a funzionalità non offerte on-premise. Vedi [Disponibilità delle funzionalità](#feature-availability). + +## DefectDojo Pro (On-Premise) + +Su [DefectDojo Pro (On-Premise)](/get_started/pro/onprem/), la maggior parte delle funzionalità funziona esattamente come su Cloud: apri **Settings > Feature Flags** e attivale o disattivale. + +Un piccolo numero di funzionalità viene invece letto dalla configurazione di deployment. Queste modificano il modo in cui l'applicazione si avvia, quindi non possono essere commutate a runtime. Compaiono nella pagina come sola lettura, etichettate **Managed by deployment**, e indicano la variabile d'ambiente che le controlla, ad esempio `DD_V3_FEATURE_LOCATIONS` per [Locations](/asset_modelling/locations/pro__locations_overview/). + +Poiché queste funzionalità richiedono un riavvio, e alcune non possono essere annullate una volta abilitate, controlla la documentazione specifica della funzionalità prima di modificarne una. Per diverse di esse è consigliabile farsi aiutare dal [supporto DefectDojo](mailto:support@defectdojo.com). + +Per modificare una di queste funzionalità: + +1. Imposta la variabile d'ambiente sul tuo deployment DefectDojo. La pagina indica quale variabile impostare. +2. Riavvia DefectDojo in modo che il nuovo valore venga letto all'avvio. +3. Ricarica la pagina Feature Flags per confermare il nuovo stato. + +Poiché questi valori vengono letti all'avvio, non è possibile modificarli dall'interfaccia, e commutarli nel tuo ambiente senza un riavvio non ha alcun effetto. + +Le funzionalità offerte solo su Cloud compaiono come **Unavailable on This Deployment** su un'istanza on-premise. È previsto e non è un problema di licenza. + +## Disponibilità delle funzionalità + +La maggior parte delle funzionalità è disponibile su entrambi i tipi di installazione. Le eccezioni sono: + +| Funzionalità | Disponibilità | Come viene controllata | +| --- | --- | --- | +| Request a New Connector | Solo [DefectDojo Pro (Cloud)](/get_started/pro/cloud/) | Pagina Feature Flags. Mostrata come **Unavailable on This Deployment** on-premise. | +| Locations | Entrambe | Pagina Feature Flags. Nota che Locations non può essere disattivata una volta abilitata. Vedi [Locations Overview](/asset_modelling/locations/pro__locations_overview/). | +| Organization / Asset Relabeling | Entrambe | Pagina Feature Flags per la Pro UI; la Classic UI, i suoi URL e i report generati seguono l'impostazione di deployment `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL`. Vedi [sopra](#organization--asset-relabeling). | + +Ogni altra funzionalità opzionale si attiva o disattiva direttamente dalla pagina Feature Flags sia sulle istanze Cloud che On-Premise. + +## Leggere i feature flag al di fuori dell'interfaccia + +Non è necessario aprire la pagina Feature Flags per scoprire quali funzionalità sono abilitate — lo stato dei flag può anche essere letto in modo programmatico, il che è utile quando un'automazione deve verificare che una funzionalità sia disponibile prima di farvi affidamento. + +``` +GET /api/v2/defectdojo_information/feature_flags/ +``` + +Questo restituisce un array JSON con un oggetto per ogni feature flag. Oltre a `key`, `title` e `description` del flag, ogni oggetto riporta i valori che di solito servono all'automazione: `effective` (se la funzionalità è effettivamente attiva per questa istanza), `default`, `application_value` (l'impostazione specifica dell'istanza, o `null` se non impostata), `editable` e `locked_reason` per i flag che non possono essere modificati. I flag ritirati dal prodotto vengono omessi. + +Qualsiasi utente **autenticato** può leggerlo — non è richiesto il ruolo di superuser. Per lo schema esatto della risposta nella tua versione, consulta la documentazione API interattiva della tua istanza all'indirizzo `/api/v2/oa3/swagger-ui/`, generata a partire dalla build in esecuzione. Vedi anche la [documentazione API v2](/automation/api/api-v2-docs/). + +Lo stesso elenco in sola lettura viene pubblicato anche sulla superficie `/api/mcp/` dell'istanza, all'indirizzo `/api/mcp/defectdojo_information/feature_flags/`. + +Questo endpoint è di **sola lettura**. Attivare o disattivare una funzionalità si fa comunque dalla pagina Feature Flags, oppure — per le funzionalità configurate a livello di deployment indicate sopra — nelle impostazioni di deployment. + +## Domande frequenti + +**Una funzionalità che cerco non è nell'elenco.** +L'elenco mostra solo le funzionalità opzionali. Le funzionalità sempre attive non compaiono. Se ti aspettavi una funzionalità che manca, verifica che la tua licenza la includa, quindi contatta il [supporto DefectDojo](mailto:support@defectdojo.com). + +**Ho attivato una funzionalità ma non la vedo.** +Ricarica la pagina — le voci di menu e i percorsi vengono valutati al caricamento della pagina, quindi una funzionalità appena abilitata compare al caricamento successivo anziché istantaneamente nella vista corrente. + +**L'aggiornamento modificherà le mie impostazioni?** +No. L'aggiornamento mantiene invariate sia le funzionalità che hai attivato sia quelle che hai disattivato. diff --git a/docs/content/admin/feature_flags/PRO__feature_flags.pt-br.md b/docs/content/admin/feature_flags/PRO__feature_flags.pt-br.md new file mode 100644 index 0000000000..478725bb77 --- /dev/null +++ b/docs/content/admin/feature_flags/PRO__feature_flags.pt-br.md @@ -0,0 +1,195 @@ +--- +title: Feature Flags +description: Ative e desative recursos opcionais do DefectDojo Pro pela interface + do DefectDojo +weight: 1 +audience: pro +--- + +Os Feature Flags permitem ativar e desativar recursos opcionais do DefectDojo Pro na sua própria +instância — recursos que antes só podiam ser habilitados entrando em contato com o Suporte da DefectDojo agora +podem ser autoatendidos pela interface. + +A página Feature Flags é visível apenas para **superusuários**. Outros usuários, incluindo Global Owners, não +a veem. + +## Abrindo a página Feature Flags + +Acesse **Settings > Feature Flags** na barra lateral esquerda. + +A página lista todos os recursos opcionais com: + +* **Name** — o recurso, com uma tag **BETA** quando ainda está em beta +* **Description** — o que o recurso faz +* **Documentation link** — onde existe documentação para aquele recurso +* **Toggle** — se o recurso está ativado no momento + +Use a caixa de pesquisa para filtrar a lista pelo nome ou pela descrição do recurso. + +### Recursos que não aparecem na lista + +A página lista os recursos que você pode optar por adotar. Dois tipos de recurso estão ausentes dela. + +**Sempre ativos.** Quando um recurso atinge disponibilidade geral, ele fica ativo em todas as instâncias e +deixa de ser listado, pois não há mais decisão a tomar: + +* **Downstream Connectors** — consulte [Downstream Connectors](/connectors/downstream/about/) +* **Universal Parser** — consulte [Universal Parser](/import_data/pro/specialized_import/universal_parser/) +* **Asset Hierarchy** — consulte [Asset Hierarchy](/asset_modelling/pro_hierarchy/asset_hierarchy/) +* **Appearance** e **Feature Flags** — as duas páginas de Settings com o mesmo nome + +Nada muda na sua instância se você já tinha um desses recursos ativado. Se você tinha algum desativado, ele +agora está ativo: esses recursos fazem parte do DefectDojo Pro em vez de serem opcionais. Entre em contato +com o [Suporte da DefectDojo](mailto:support@defectdojo.com) se isso for um problema para a sua instância. + +**Habilitados pela DefectDojo mediante solicitação.** Alguns recursos dependem de infraestrutura provisionada +por instância, portanto são ativados pela DefectDojo em vez de por esta página: + +* **Scheduling Service** — consulte [Scheduling Rules](/automation/rules_engine/scheduling/) + +Entre em contato com o [Suporte da DefectDojo](mailto:support@defectdojo.com) para ativar um desses recursos. +Se já estiver ativo na sua instância, ele permanece ativo. + +## Ativando ou desativando um recurso + +1. Encontre o recurso na lista. +2. Clique no toggle dele. +3. A alteração entra em vigor imediatamente. Outros usuários recebem a alteração no próximo carregamento da + página. + +Alguns recursos exibem uma caixa de diálogo de confirmação antes que a alteração seja aplicada. Isso acontece +ao ativar um recurso que traz um aviso (por exemplo, um que exige reinicialização ou pode afetar dados +existentes), ou um que não pode ser desativado novamente. + +Desativar um recurso normalmente é apenas o inverso de ativá-lo. As exceções são indicadas em +[Quando um toggle está bloqueado](#when-a-toggle-is-locked). + +### Organization / Asset Relabeling + +**Organization / Asset Relabeling** renomeia "Product Type" para "Organization" e "Product" para "Asset". Ele +vem ativado por padrão e é alternado nesta página como qualquer outro recurso, mas vale a pena saber quais +partes do DefectDojo ele governa: + +* A **Pro UI** segue este toggle. Os novos rótulos aparecem no próximo carregamento da página. +* As páginas da **Classic UI**, suas URLs e os relatórios gerados obtêm sua nomenclatura da configuração de + deployment `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` (também ativada por padrão), que é lida quando o + DefectDojo é iniciado. Este toggle não as altera, e reiniciar também não faz com que ele as altere. + +O toggle armazenado foi inicializado a partir dessa configuração de deployment, portanto os dois permanecem +alinhados até que você altere um deles. Se você desativar o relabeling aqui e também usar a Classic UI, +defina `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL=False` no seu deployment e reinicie para que as duas +superfícies fiquem alinhadas. No [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), entre em contato com o +[Suporte da DefectDojo](mailto:support@defectdojo.com) para que a configuração de deployment seja alterada. + +Por esse motivo, o recurso traz uma tag **Restart Recommended** na página Feature Flags: a nomenclatura usada +fora da Pro UI é fixada quando o processo é iniciado. De qualquer forma, o relabeling é apenas cosmético. Os +modelos de banco de dados, nomes de campos e endpoints da API permanecem inalterados, portanto a automação +existente continua funcionando. Consulte [Asset Hierarchy](/asset_modelling/pro_hierarchy/asset_hierarchy/). + +## Quando um toggle está bloqueado + +Um recurso que você não pode alterar é exibido com um selo de bloqueio explicando o motivo: + +| Badge | O que significa | O que fazer | +| --- | --- | --- | +| **Managed by DefectDojo** | A DefectDojo definiu este recurso de forma centralizada para a sua instância. Sua configuração não pode substituí-lo. | Entre em contato com o [Suporte da DefectDojo](mailto:support@defectdojo.com) se precisar alterá-lo. | +| **Unavailable on This Deployment** | O recurso não é oferecido no seu tipo de instalação. Veja [Disponibilidade de recursos](#feature-availability) abaixo. | Nada a fazer. O recurso não se aplica à sua instância. | +| **Cannot Be Disabled** | O recurso já está ativo e é de mão única. Não há mecanismo para revertê-lo. | Nada a fazer. Isso é esperado. | +| **Managed by deployment** | O recurso é controlado pela sua configuração de deployment, e não por esta página. | Veja [DefectDojo Pro (On-Premise)](#defectdojo-pro-on-premise) abaixo. | + +## DefectDojo Pro (Cloud) + +No [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), **Settings > Feature Flags** é o único lugar que você +precisa. Ative um recurso e ele já estará em produção. + +Duas coisas são tratadas pela DefectDojo, e não por você: + +* **Managed by DefectDojo** — o recurso é fixado de forma centralizada. Entre em contato com o + [Suporte da DefectDojo](mailto:support@defectdojo.com) para alterá-lo. +* **Managed by deployment** — o recurso faz parte de como sua instância é provisionada. Entre em contato com + o Suporte também para esses casos, já que as instâncias Cloud não expõem a configuração de deployment aos + clientes. + +As instâncias Cloud também têm acesso a recursos que não são oferecidos on-premise. Veja +[Disponibilidade de recursos](#feature-availability). + +## DefectDojo Pro (On-Premise) + +No [DefectDojo Pro (On-Premise)](/get_started/pro/onprem/), a maioria dos recursos funciona exatamente como +no Cloud: abra **Settings > Feature Flags** e ative-os ou desative-os. + +Um pequeno número de recursos, em vez disso, é lido a partir da sua configuração de deployment. Eles alteram +a forma como a aplicação é iniciada, portanto não podem ser alternados em tempo de execução. Esses recursos +aparecem na página como somente leitura, rotulados como **Managed by deployment**, e indicam a variável de +ambiente que os controla, por exemplo `DD_V3_FEATURE_LOCATIONS` para +[Locations](/asset_modelling/locations/pro__locations_overview/). + +Como esses recursos exigem uma reinicialização, e alguns deles não podem ser revertidos depois de ativados, +consulte a documentação específica do recurso antes de alterá-lo. Vários são melhor ativados com a ajuda do +[Suporte da DefectDojo](mailto:support@defectdojo.com). + +Para alterar um desses recursos: + +1. Defina a variável de ambiente no seu deployment do DefectDojo. A página indica qual variável definir. +2. Reinicie o DefectDojo para que o novo valor seja lido na inicialização. +3. Recarregue a página Feature Flags para confirmar o novo estado. + +Como esses valores são lidos na inicialização, não é possível alterá-los pela interface, e alterná-los no +seu ambiente sem uma reinicialização não tem efeito. + +Recursos oferecidos apenas no Cloud aparecem como **Unavailable on This Deployment** em uma instância +on-premise. Isso é esperado e não é um problema de licenciamento. + +## Disponibilidade de recursos + +A maioria dos recursos está disponível nos dois tipos de instalação. As exceções são: + +| Feature | Availability | How it is controlled | +| --- | --- | --- | +| Request a New Connector | Somente [DefectDojo Pro (Cloud)](/get_started/pro/cloud/) | Página Feature Flags. Exibido como **Unavailable on This Deployment** on-premise. | +| Locations | Ambos | Página Feature Flags. Observe que Locations não pode ser desativado novamente depois de ativado. Veja [Locations Overview](/asset_modelling/locations/pro__locations_overview/). | +| Organization / Asset Relabeling | Ambos | Página Feature Flags para a Pro UI; a Classic UI, suas URLs e os relatórios gerados seguem a configuração de deployment `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL`. Veja [acima](#organization--asset-relabeling). | + +Todos os demais recursos opcionais são alternados diretamente na página Feature Flags, tanto em instâncias +Cloud quanto On-Premise. + +## Lendo feature flags fora da interface + +Não é necessário abrir a página Feature Flags para saber quais recursos estão ativados — o estado das flags +também pode ser lido de forma programática, o que é útil quando uma automação precisa verificar se um +recurso está disponível antes de depender dele. + +``` +GET /api/v2/defectdojo_information/feature_flags/ +``` + +Isso retorna um array JSON com um objeto por feature flag. Além de `key`, `title` e `description` da flag, +cada objeto informa os valores que a automação geralmente precisa: `effective` (se o recurso está de fato +ativo nesta instância), `default`, `application_value` (a configuração própria da instância, ou `null` se +não definida), `editable`, e `locked_reason` quando uma flag não pode ser alterada. Flags removidas do +produto são omitidas. + +Qualquer usuário **autenticado** pode lê-lo — não é necessária função de superusuário. Para o schema exato +de resposta na sua versão, consulte a documentação interativa da API da sua instância em +`/api/v2/oa3/swagger-ui/`, gerada a partir do build em execução. Veja também a +[documentação da API v2](/automation/api/api-v2-docs/). + +A mesma listagem somente leitura também é publicada na superfície `/api/mcp/` da instância, em +`/api/mcp/defectdojo_information/feature_flags/`. + +Este endpoint é **somente leitura**. Ativar ou desativar um recurso ainda é feito na página Feature Flags +ou — para os recursos configurados por deployment mencionados acima — nas configurações do seu deployment. + +## Perguntas frequentes + +**Um recurso que eu quero não está na lista.** +A lista mostra apenas recursos opcionais. Recursos que estão sempre ativos não aparecem. Se você esperava +encontrar um recurso que está faltando, confirme se a sua licença o inclui e, em seguida, entre em contato +com o [Suporte da DefectDojo](mailto:support@defectdojo.com). + +**Ativei um recurso, mas não o vejo.** +Recarregue a página — entradas de menu e rotas são avaliadas quando a página carrega, portanto um recurso +recém-ativado aparece no próximo carregamento, e não instantaneamente na visualização atual. + +**Uma atualização vai alterar minhas configurações?** +Não. A atualização preserva os recursos que você ativou e os que você desativou. diff --git a/docs/content/admin/feature_flags/PRO__feature_flags.zh-hans.md b/docs/content/admin/feature_flags/PRO__feature_flags.zh-hans.md new file mode 100644 index 0000000000..7cb981711b --- /dev/null +++ b/docs/content/admin/feature_flags/PRO__feature_flags.zh-hans.md @@ -0,0 +1,142 @@ +--- +title: 功能标志 +description: 在 DefectDojo UI 中打开或关闭可选的 DefectDojo Pro 功能 +weight: 1 +audience: pro +--- + +功能标志(Feature Flags)让您可以在自己的实例上打开或关闭可选的 DefectDojo Pro 功能——以前只能通过联系 DefectDojo 支持才能启用的功能,现在可以在 UI 中自助完成。 + +功能标志页面仅对**超级用户**可见。其他用户(包括全局所有者)看不到该页面。 + +## 打开功能标志页面 + +在左侧边栏中前往**设置 > 功能标志**。 + +该页面列出了每一项可选功能,包含: + +* **名称**——功能名称,若仍处于测试阶段则带有 **BETA** 标签 +* **说明**——该功能的作用 +* **文档链接**——该功能对应文档所在位置 +* **开关**——该功能当前是否处于开启状态 + +使用搜索框可按功能名称或说明筛选列表。 + +### 未列出的功能 + +该页面列出的是您可以选择采用的功能。有两类功能不会出现在其中。 + +**始终开启。** 一旦某项功能进入正式发布(GA)阶段,它就会对所有实例保持开启,并不再列出,因为已经没有需要决定的事项: + +* **下游连接器**——参见[下游连接器](/connectors/downstream/about/) +* **通用解析器**——参见[通用解析器](/import_data/pro/specialized_import/universal_parser/) +* **资产层级结构**——参见[资产层级结构](/asset_modelling/pro_hierarchy/asset_hierarchy/) +* **外观**和**功能标志**——两个同名的设置页面 + +如果您之前已经开启了其中某项功能,对您的实例不会有任何变化。如果您之前将其关闭,那么现在它已被开启:这些功能属于 DefectDojo Pro 的固有部分,而非可选启用项。如果这会给您的实例带来问题,请联系 [DefectDojo 支持](mailto:support@defectdojo.com)。 + +**由 DefectDojo 应请求启用。** 少数功能依赖于按实例预配置的基础设施,因此由 DefectDojo(而非在本页面)负责开启: + +* **调度服务**——参见[调度规则](/automation/rules_engine/scheduling/) + +如需启用上述功能,请联系 [DefectDojo 支持](mailto:support@defectdojo.com)。如果您的实例已经开启了该功能,它将保持开启状态。 + +## 开启或关闭某项功能 + +1. 在列表中找到该功能。 +2. 点击其开关。 +3. 更改会立即生效。其他用户会在下次加载页面时看到变化。 + +某些功能在应用更改前会显示确认对话框。这种情况出现在启用带有警告的功能时(例如需要重启,或可能影响现有数据的功能),或该功能一旦启用便无法再关闭时。 + +关闭某项功能通常只是开启操作的逆过程。例外情况见[开关被锁定时](#when-a-toggle-is-locked)。 + +### 组织/资产重命名 + +**组织/资产重命名**会将“产品类型”重命名为“组织”,将“产品”重命名为“资产”。该功能默认开启,并像其他功能一样可在本页面切换,但值得了解它所管辖的 DefectDojo 范围: + +* **Pro UI** 会跟随该开关。新名称会在您下次加载页面时生效。 +* **经典 UI** 页面及其 URL,以及生成的报告,其命名取自 `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` 部署设置(同样默认开启),该设置在 DefectDojo 启动时读取。本开关不会改变它们,重启也不会使其发生变化。 + +存储的开关状态最初是从该部署设置初始化的,因此两者在您更改其中任意一个之前是一致的。如果您在此处关闭重命名功能,同时又使用经典 UI,请在您的部署上将 `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL=False` 设置好并重启,以使两个界面保持一致。在 [DefectDojo Pro(云版)](/get_started/pro/cloud/)上,请联系 [DefectDojo 支持](mailto:support@defectdojo.com)以更改该部署设置。 + +正因如此,该功能在功能标志页面上带有**建议重启**标签:Pro UI 之外的命名在进程启动时就已固定。无论哪种情况,重命名都只是外观层面的变化。数据库模型、字段名称和 API 端点均不受影响,因此现有自动化流程不会受到影响。参见[资产层级结构](/asset_modelling/pro_hierarchy/asset_hierarchy/)。 + +## 开关被锁定时 + +无法更改的功能会显示一个锁定徽章,说明原因: + +| 徽章 | 含义 | 应采取的操作 | +| --- | --- | --- | +| **由 DefectDojo 管理** | DefectDojo 已为您的实例集中设置了该功能。您的设置无法覆盖它。 | 如需更改,请联系 [DefectDojo 支持](mailto:support@defectdojo.com)。 | +| **此部署不可用** | 您的安装类型不提供该功能。请参见下方[功能可用性](#feature-availability)。 | 无需操作。该功能不适用于您的实例。 | +| **无法禁用** | 该功能已经开启,且是单向的。没有机制可以将其还原。 | 无需操作,这是预期行为。 | +| **由部署管理** | 该功能由您的部署配置控制,而非本页面。 | 参见下方 [DefectDojo Pro(本地部署)](#defectdojo-pro-on-premise)。 | + +## DefectDojo Pro(云版) + +在 [DefectDojo Pro(云版)](/get_started/pro/cloud/)上,您只需要**设置 > 功能标志**这一处即可。开启某项功能,它便立即生效。 + +以下两种情况由 DefectDojo 而非您本人处理: + +* **由 DefectDojo 管理**——该功能被集中固定。如需更改,请联系 [DefectDojo 支持](mailto:support@defectdojo.com)。 +* **由部署管理**——该功能属于您实例配置方式的一部分。这类情况也请联系支持,因为云端实例不向客户开放部署配置。 + +云端实例还可使用本地部署未提供的功能。请参见[功能可用性](#feature-availability)。 + +## DefectDojo Pro(本地部署) + +在 [DefectDojo Pro(本地部署)](/get_started/pro/onprem/)上,大多数功能与云版完全相同:打开**设置 > 功能标志**并切换开关即可。 + +少数功能则改为从您的部署配置中读取。它们会影响应用程序的启动方式,因此无法在运行时切换。这类功能会在页面上显示为只读,标注为**由部署管理**,并注明控制它们的环境变量,例如 [位置](/asset_modelling/locations/pro__locations_overview/) 对应的 `DD_V3_FEATURE_LOCATIONS`。 + +由于这些功能需要重启,且其中一些一旦启用便无法还原,请在更改前查阅该功能自身的文档。其中多项功能最好在 [DefectDojo 支持](mailto:support@defectdojo.com)的协助下启用。 + +如需更改上述某项功能: + +1. 在您的 DefectDojo 部署上设置相应的环境变量。页面会告诉您需要设置哪个变量。 +2. 重启 DefectDojo,使新值在启动时被读取。 +3. 重新加载功能标志页面以确认新状态。 + +由于这些值是在启动时读取的,因此无法通过 UI 更改;在您的环境中切换它们而不重启也不会产生任何效果。 + +仅在云端提供的功能,在本地部署实例上会显示为**此部署不可用**。这是预期行为,并非许可问题。 + +## 功能可用性 + +大多数功能在两种安装类型上都可用。例外情况如下: + +| 功能 | 可用性 | 控制方式 | +| --- | --- | --- | +| 请求新连接器 | 仅 [DefectDojo Pro(云版)](/get_started/pro/cloud/) | 功能标志页面。本地部署会显示为**此部署不可用**。 | +| 位置 | 两者均可 | 功能标志页面。请注意,位置功能一旦启用便无法再关闭。参见[位置概述](/asset_modelling/locations/pro__locations_overview/)。 | +| 组织/资产重命名 | 两者均可 | Pro UI 通过功能标志页面控制;经典 UI 及其 URL 与生成的报告则跟随 `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` 部署设置。参见[上文](#organization--asset-relabeling)。 | + +其他所有可选功能在云端和本地部署实例上都可直接在功能标志页面切换。 + +## 在 UI 之外读取功能标志 + +您不必打开功能标志页面才能知道哪些功能已启用——标志状态也可以通过编程方式读取,这在自动化流程需要在依赖某项能力之前先确认其是否可用时很有用。 + +``` +GET /api/v2/defectdojo_information/feature_flags/ +``` + +该接口会返回一个 JSON 数组,每个功能标志对应一个对象。除了标志的 `key`、`title` 和 `description` 之外,每个对象还会报告自动化流程通常需要的取值:`effective`(该功能对本实例是否实际开启)、`default`、`application_value`(该实例自身的设置,未设置时为 `null`)、`editable`,以及标志无法更改时的 `locked_reason`。已从产品中退役的标志不会出现在结果中。 + +任何**已通过身份验证**的用户都可以读取该接口——不需要超级用户角色。关于您所用版本的确切响应结构,请参见您实例上由当前构建生成的交互式 API 文档,地址为 `/api/v2/oa3/swagger-ui/`。另请参见 [API v2 文档](/automation/api/api-v2-docs/)。 + +同样的只读列表也发布在实例的 `/api/mcp/` 接口上,地址为 `/api/mcp/defectdojo_information/feature_flags/`。 + +该端点是**只读**的。开启或关闭某项功能仍需在功能标志页面完成,或者——对于上文提到的由部署配置的功能——在您的部署设置中完成。 + +## 常见问题 + +**我想要的功能不在列表中。** +该列表仅展示可选功能。始终开启的能力不会出现在其中。如果您认为缺少的某项功能应该存在,请先确认您的许可证是否包含该功能,然后联系 [DefectDojo 支持](mailto:support@defectdojo.com)。 + +**我开启了某项功能,但没有看到它。** +请重新加载页面——菜单项和路由是在页面加载时评估的,因此新启用的功能会在下次加载时出现,而不会立即出现在当前视图中。 + +**升级会改变我的设置吗?** +不会。升级会保留您已开启和已关闭的功能设置。 diff --git a/docs/content/admin/feature_flags/_index.it.md b/docs/content/admin/feature_flags/_index.it.md new file mode 100644 index 0000000000..4995eeb10f --- /dev/null +++ b/docs/content/admin/feature_flags/_index.it.md @@ -0,0 +1,23 @@ +--- +title: Feature Flags +description: Attiva e disattiva le funzionalità opzionali di DefectDojo Pro per la + tua istanza +summary: '' +date: 2026-07-20 00:00:00+00:00 +lastmod: 2026-07-20 00:00:00+00:00 +draft: false +weight: 4 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- + +Molte funzionalità di DefectDojo Pro vengono rilasciate dietro un feature flag, così puoi adottarle quando sei pronto anziché nella release che le introduce. + +I Feature Flags sono una funzionalità di DefectDojo Pro. La versione open source di DefectDojo non dispone di una superficie di feature flag. + +* [Feature Flags](./pro__feature_flags/) — visualizza ogni funzionalità opzionale, attiva e disattiva le funzionalità e scopri perché una funzionalità potrebbe non essere disponibile sulla tua istanza. diff --git a/docs/content/admin/feature_flags/_index.pt-br.md b/docs/content/admin/feature_flags/_index.pt-br.md new file mode 100644 index 0000000000..781395089d --- /dev/null +++ b/docs/content/admin/feature_flags/_index.pt-br.md @@ -0,0 +1,25 @@ +--- +title: Feature Flags +description: Ative e desative recursos opcionais do DefectDojo Pro para a sua instância +summary: '' +date: 2026-07-20 00:00:00+00:00 +lastmod: 2026-07-20 00:00:00+00:00 +draft: false +weight: 4 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- + +Muitos recursos do DefectDojo Pro são lançados atrás de uma feature flag, para que você possa +adotá-los quando estiver pronto, em vez de na versão em que são introduzidos. + +Feature Flags é um recurso do DefectDojo Pro. O DefectDojo open-source não possui uma superfície de feature +flags. + +* [Feature Flags](./pro__feature_flags/) — veja todos os recursos opcionais, ative e desative recursos, e + entenda por que um recurso pode estar indisponível na sua instância. diff --git a/docs/content/admin/feature_flags/_index.zh-hans.md b/docs/content/admin/feature_flags/_index.zh-hans.md new file mode 100644 index 0000000000..ef2f5cf2ba --- /dev/null +++ b/docs/content/admin/feature_flags/_index.zh-hans.md @@ -0,0 +1,22 @@ +--- +title: 功能标志 +description: 为您的实例打开或关闭可选的 DefectDojo Pro 功能 +summary: '' +date: 2026-07-20 00:00:00+00:00 +lastmod: 2026-07-20 00:00:00+00:00 +draft: false +weight: 4 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- + +许多 DefectDojo Pro 功能都以功能标志的形式发布,以便您可以在自己准备好时再采用它们,而不必在引入该功能的版本上就立即使用。 + +功能标志是 DefectDojo Pro 的功能。开源版 DefectDojo 没有功能标志界面。 + +* [功能标志](./pro__feature_flags/)——查看每一项可选功能,开启或关闭功能,并了解某项功能在您的实例上不可用的原因。 diff --git a/docs/content/admin/notifications/_index.it.md b/docs/content/admin/notifications/_index.it.md new file mode 100644 index 0000000000..43725a40bb --- /dev/null +++ b/docs/content/admin/notifications/_index.it.md @@ -0,0 +1,16 @@ +--- +title: Notifiche +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 7 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +pro-feature: true +exclude_search: true +--- diff --git a/docs/content/admin/notifications/_index.pt-br.md b/docs/content/admin/notifications/_index.pt-br.md new file mode 100644 index 0000000000..cd00d1971c --- /dev/null +++ b/docs/content/admin/notifications/_index.pt-br.md @@ -0,0 +1,16 @@ +--- +title: Notificações +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 7 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +pro-feature: true +exclude_search: true +--- diff --git a/docs/content/admin/notifications/_index.zh-hans.md b/docs/content/admin/notifications/_index.zh-hans.md new file mode 100644 index 0000000000..5d158df114 --- /dev/null +++ b/docs/content/admin/notifications/_index.zh-hans.md @@ -0,0 +1,16 @@ +--- +title: 通知 +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 7 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +pro-feature: true +exclude_search: true +--- diff --git a/docs/content/admin/notifications/about_notifications.it.md b/docs/content/admin/notifications/about_notifications.it.md new file mode 100644 index 0000000000..aa84d0f83d --- /dev/null +++ b/docs/content/admin/notifications/about_notifications.it.md @@ -0,0 +1,103 @@ +--- +title: Informazioni su Notifiche e 🔔 Alert +description: Informazioni su notifiche e alert in-app +aliases: +- /it/en/customize_dojo/notifications/about_notifications +--- + +DefectDojo ti tiene aggiornato in diversi modi. Le notifiche possono essere inviate per Engagement imminenti, [menzioni utente](/triage_findings/findings_workflows/intro_to_findings/#notes-and-mentions), scadenza SLA e altri eventi nel software. + +Questo articolo fornisce una panoramica delle notifiche sia a livello di Sistema che Personale. + +## Tipi di notifica + +DefectDojo gestisce le notifiche in due modi diversi: + +* Le **Notifiche a livello di sistema** vengono inviate a tutti gli utenti. +* **Le Notifiche personali vengono impostate dai singoli utenti e vengono ricevute in aggiunta a eventuali Notifiche a livello di sistema.** + +In entrambi i casi, si applicano le regole del [controllo degli accessi basato sui ruoli](../../user_management/about_perms_and_roles/), quindi gli utenti non riceveranno notifiche di attività per Prodotti o Tipi di prodotto (o i relativi oggetti correlati) a cui non hanno accesso. + +## Metodi di consegna delle notifiche + +Esistono quattro metodi di consegna per le notifiche di DefectDojo: + +* DefectDojo può condividere **🔔 Alert,** memorizzati come elenco nell'interfaccia di DefectDojo +* DefectDojo può inviare notifiche a un indirizzo **Email** +* DefectDojo può inviare notifiche a **Slack,** in un canale condiviso o individuale +* DefectDojo può inoltre inviare notifiche a **Microsoft Teams** in un canale condiviso + +Le notifiche possono essere inviate contemporaneamente a più destinazioni. + +Per ricevere notifiche su Slack e Teams è necessaria un'integrazione funzionante. Per maggiori informazioni su come configurare questa integrazione, consulta la nostra [Guida](../email_slack_teams). + +## Avvisi in-app + +Il sistema di Alert di DefectDojo ti tiene aggiornato su tutte le attività relative a Prodotti o al sistema. + +### L'elenco degli Alert + +L'elenco degli Alert è sempre visibile nell'angolo in alto a destra di DefectDojo e contiene un elenco compatto delle notifiche. Facendo clic su ciascun Alert verrai indirizzato direttamente alla pagina pertinente in DefectDojo. + +Puoi aprire il tuo elenco degli Alert facendo clic sull'**icona 🔔▼** nell'angolo in alto a destra: + +![image](images/About_In-App_Alerts.png) + +Per visualizzare tutte le tue notifiche, con ulteriori dettagli, puoi fare clic sul pulsante **See All Alerts \>**, che aprirà la **pagina degli Alert**. + +Puoi anche selezionare **Clear All Alerts \>** dall'elenco degli Alert. + +### La pagina degli Alert + +La pagina degli Alert memorizza tutti i tuoi Alert in DefectDojo con ulteriori dettagli. In questa pagina puoi leggere le descrizioni di ciascun Alert in DefectDojo e rimuoverli dalla coda degli Alert quando non ti servono più. + +![image](images/About_In-App_Alerts_2.png) + +Per rimuovere uno o più Alert dalla pagina degli Alert, seleziona la casella vuota accanto ad esso, quindi fai clic sul pulsante **Remove selected** nell'angolo in basso a destra della pagina. + +### Note sugli Alert + +* Leggere un Alert o aprire la pagina degli Alert non rimuoverà alcun Alert dal conteggio accanto all'icona a forma di campana. Questo ti consente di accedere facilmente agli Alert passati per usarli come promemoria o come registro di attività personale. +* L'uso della funzione **Clear All Alerts \>** nel menu degli Alert cancellerà completamente anche la **pagina degli Alert**, quindi usa questa funzione con cautela. +* La rimozione di un Alert influisce solo sul tuo elenco degli Alert: non avrà effetto sugli Alert di altri utenti. +* La rimozione di un Alert non elimina alcuna cronologia di importazione o registro di attività da DefectDojo. + +## Restringere le notifiche di richiesta di revisione (Pro) + +Se una revisione viene richiesta a tutti i revisori idonei, tutti coloro che sono idonei su quell'asset vengono notificati. Si tratta di molte email per un revisore che si occupa solo di una parte del tuo parco asset. + +Nell'interfaccia di DefectDojo Pro puoi restringere le tue notifiche di richiesta di revisione. Nella pagina delle impostazioni delle notifiche, in **Review Requests**: + +* **Review Request Scope** — *All* (l'impostazione predefinita) ti notifica su tutto ciò che puoi vedere. *Selected* ti limita agli asset e ai tipi di asset che scegli. +* **Review Request Assets** / **Review Request Asset Types** — la porzione del parco asset su cui vuoi essere informato. Una richiesta corrisponde se riguarda uno degli asset selezionati *oppure* uno dei tipi di asset selezionati. + +Due cose da chiarire: + +* Scegliere *Selected* e non selezionare nulla significa **nessuno**, non tutti. +* Il restringimento sopprime la notifica, **non la richiesta**. Rimani un revisore richiesto e la richiesta continua a comparire nella tua coda [My Work](/metrics_reports/dashboards/pro__my_work/) in **Awaiting My Review** — semplicemente non ricevi un messaggio al riguardo. Questo è intenzionale: la coda è il registro permanente, le notifiche sono il promemoria. + +Questo restringimento ha inoltre la precedenza sull'override a livello di sistema descritto di seguito, quindi un revisore che si è escluso non viene notificato anche quando `review_requested` è configurato per avere la precedenza sulle preferenze personali. + +Il restringimento può anche essere impostato tramite API sull'endpoint delle notifiche, il che è l'approccio pratico se stai configurando molti revisori contemporaneamente. + +## Notifiche di assegnazione del lavoro (Pro) + +Quando i Riscontri ti vengono assegnati, la notifica **Work Assigned** ti indica quanti sono e include un link alla tua coda My Work. + +È aggregata per persona anziché per Riscontro: assegnare cento Riscontri invia un solo messaggio, non cento. Come per le richieste di revisione, l'assegnazione è visibile nella tua coda indipendentemente dal fatto che la notifica ti raggiunga o meno. + +## Considerazioni per la versione open source + +### Override specifici + +Le impostazioni delle notifiche di sistema (scope: system) descrivono l'invio di notifiche ai superadmin. Le impostazioni delle notifiche utente (scope: personal) descrivono l'invio di notifiche allo specifico utente. + +Tuttavia, esiste un caso d'uso specifico in cui l'utente decide di disabilitare le notifiche (per ridurre il rumore) ma l'impostazione di sistema viene usata per sovrascrivere questo comportamento. Questi override si applicano per impostazione predefinita solo a `user_mentioned` e `review_requested`. + +L'ambito di questa impostazione è personalizzabile (vedi la variabile d'ambiente `DD_NOTIFICATIONS_SYSTEM_LEVEL_TRUMP`). + +Per maggiori informazioni su questo comportamento, consulta la [pull request correlata #9699](https://github.com/DefectDojo/django-DefectDojo/pull/9699/) + +### Webhook (sperimentale) + +DefectDojo supporta anche webhook che seguono gli stessi eventi delle altre notifiche (puoi essere notificato nelle stesse situazioni). I dettagli sulla configurazione sono descritti nella [pagina correlata](/automation/api/notification_webhooks/). diff --git a/docs/content/admin/notifications/about_notifications.pt-br.md b/docs/content/admin/notifications/about_notifications.pt-br.md new file mode 100644 index 0000000000..93dfeb54a0 --- /dev/null +++ b/docs/content/admin/notifications/about_notifications.pt-br.md @@ -0,0 +1,103 @@ +--- +title: Sobre Notificações e 🔔 Alertas +description: Saiba mais sobre notificações e alertas no aplicativo +aliases: +- /pt-br/en/customize_dojo/notifications/about_notifications +--- + +DefectDojo mantém você atualizado de diversas formas. Notificações podem ser enviadas para Engajamentos futuros, [Menções a usuários](/triage_findings/findings_workflows/intro_to_findings/#notes-and-mentions), expiração de SLA e outros eventos no sistema. + +Este artigo apresenta uma visão geral das notificações, tanto no nível de Sistema quanto no nível Pessoal. + +## Tipos de Notificação + +O DefectDojo trata as notificações de duas formas diferentes:: + +* **Notificações do Sistema** são enviadas a todos os usuários. +* **As Notificações Pessoais são definidas por usuários individuais e são recebidas além de quaisquer Notificações do Sistema.** + +Em ambos os casos, as regras de [Controle de Acesso Baseado em Função](../../user_management/about_perms_and_roles/) se aplicam, portanto os usuários não receberão notificações de atividade de Produtos ou Tipos de Produto (ou seus objetos relacionados) aos quais não têm acesso. + +## Métodos de Entrega de Notificação + +Existem quatro métodos de entrega para as notificações do DefectDojo: + +* O DefectDojo pode compartilhar **🔔 Alertas,** armazenados como uma lista na interface do DefectDojo +* O DefectDojo pode enviar notificações para um endereço de **E-mail** +* O DefectDojo pode enviar notificações para o **Slack,** em um canal compartilhado ou individual +* O DefectDojo também pode enviar notificações para o **Microsoft Teams** em um canal compartilhado + +As notificações podem ser enviadas para vários destinos simultaneamente. + +Para receber notificações do Slack e do Teams, é necessário ter uma integração funcionando. Para mais informações sobre como configurar essa integração, consulte nosso [Guia](../email_slack_teams). + +## Alertas no Aplicativo + +O sistema de Alertas do DefectDojo mantém você atualizado sobre toda a atividade de Produto ou do sistema. + +### A Lista de Alertas + +A Lista de Alertas fica sempre visível no canto superior direito do DefectDojo e contém uma lista compacta de notificações. Clicar em cada Alerta o levará diretamente à página relevante no DefectDojo. + +Você pode abrir sua Lista de Alertas clicando no **ícone 🔔▼** no canto superior direito: + +![image](images/About_In-App_Alerts.png) + +Para ver todas as suas notificações, com detalhes adicionais, você pode clicar no botão **See All Alerts \>**, que abrirá a **Alerts Page**. + +Você também pode **Clear All Alerts \>** a partir da Lista de Alertas. + +### A Página de Alertas + +A Página de Alertas armazena todos os seus Alertas no DefectDojo com detalhes adicionais. Nesta página, você pode ler as descrições de cada Alerta no DefectDojo e removê-los da fila de Alertas quando não precisar mais deles. + +![image](images/About_In-App_Alerts_2.png) + +Para remover um ou mais Alertas da Página de Alertas, marque a caixa vazia ao lado dele e clique no botão **Remove selected** no canto inferior direito da Página. + +### Observações Sobre Alertas + +* Ler um Alerta, ou abrir a Página de Alertas, não removerá nenhum Alerta da contagem ao lado do ícone de sino. Isso permite que você acesse facilmente alertas anteriores para usá-los como lembretes ou como um registro de atividade pessoal. +* Usar a função **Clear All Alerts \>** no Menu de Alertas também limpará completamente a **Alerts Page**, portanto use esse recurso com cuidado. +* Remover um Alerta afeta apenas a sua própria Lista de Alertas \- isso não afetará os Alertas de nenhum outro usuário. +* Remover um Alerta não remove nenhum histórico de importação ou registro de atividade do DefectDojo. + +## Restringindo Notificações de Solicitação de Revisão (Pro) + +Se uma revisão for solicitada a todos os revisores elegíveis, todos os elegíveis para esse ativo são notificados. Isso representa muito e-mail para um revisor que cuida apenas de parte do seu ambiente. + +Na interface do DefectDojo Pro, você pode restringir suas próprias notificações de solicitação de revisão. Na sua página de configurações de notificação, em **Review Requests**: + +* **Review Request Scope** — *All* (o padrão) notifica você sobre tudo o que você pode visualizar. *Selected* restringe você aos ativos e tipos de ativo que você escolher. +* **Review Request Assets** / **Review Request Asset Types** — a parte do ambiente sobre a qual você quer ser avisado. Uma solicitação corresponde se estiver em um dos seus ativos selecionados *ou* em um dos seus tipos de ativo selecionados. + +Duas coisas devem ficar claras: + +* Escolher *Selected* e não selecionar nada significa **nenhum**, não todos. +* Restringir suprime a notificação, **não a solicitação**. Você continua sendo um revisor solicitado, e a solicitação ainda aparece na sua fila [My Work](/metrics_reports/dashboards/pro__my_work/), em **Awaiting My Review** — você simplesmente não é avisado por mensagem. Isso é proposital: a fila é o registro duradouro, as notificações são apenas o lembrete. + +Essa restrição também tem precedência sobre a substituição em nível de sistema descrita abaixo, portanto um revisor que se excluiu do escopo não é notificado mesmo quando `review_requested` está configurado para prevalecer sobre as preferências pessoais. + +A restrição também pode ser definida pela API, no endpoint de notificações, o que é a forma mais prática se você estiver configurando muitos revisores de uma vez. + +## Notificações de Atribuição de Trabalho (Pro) + +Quando Achados são atribuídos a você, a notificação **Work Assigned** informa quantos foram atribuídos e traz um link para sua fila My Work. + +Ela é agregada por pessoa, e não por Achado: atribuir cem Achados envia uma única mensagem, não cem. Assim como nas solicitações de revisão, a atribuição fica visível na sua fila independentemente de a notificação chegar até você. + +## Considerações sobre Código Aberto + +### Substituições específicas + +As configurações de notificação do sistema (scope: system) descrevem o envio de notificações a superadmins. As configurações de notificação do usuário (scope: personal) descrevem o envio de notificações ao usuário específico. + +No entanto, há um caso de uso específico em que o usuário decide desativar as notificações (para reduzir o ruído), mas a configuração do sistema é usada para substituir esse comportamento. Por padrão, essas substituições se aplicam apenas a `user_mentioned` e `review_requested`. + +O escopo dessa configuração é personalizável (veja a variável de ambiente `DD_NOTIFICATIONS_SYSTEM_LEVEL_TRUMP`). + +Para mais informações sobre esse comportamento, consulte o [pull request relacionado #9699](https://github.com/DefectDojo/django-DefectDojo/pull/9699/) + +### Webhooks (experimental) + +O DefectDojo também suporta webhooks que seguem os mesmos eventos que as demais notificações (você pode ser notificado nas mesmas situações). Detalhes sobre a configuração são descritos na [página relacionada](/automation/api/notification_webhooks/). diff --git a/docs/content/admin/notifications/about_notifications.zh-hans.md b/docs/content/admin/notifications/about_notifications.zh-hans.md new file mode 100644 index 0000000000..c5474b21ad --- /dev/null +++ b/docs/content/admin/notifications/about_notifications.zh-hans.md @@ -0,0 +1,103 @@ +--- +title: 关于通知和 🔔 提醒 +description: 了解通知和应用内提醒 +aliases: +- /zh-hans/en/customize_dojo/notifications/about_notifications +--- + +DefectDojo 通过多种方式让您随时掌握最新情况。系统可针对即将到来的测试活动、[用户提及](/triage_findings/findings_workflows/intro_to_findings/#notes-and-mentions)、SLA 到期以及软件中的其他事件发送通知。 + +本文概述了系统级和个人级两种层面的通知。 + +## 通知类型 + +DefectDojo 通过两种不同的方式处理通知： + +* **系统级通知**会发送给所有用户。 +* **个人通知由各用户自行设置,会在系统级通知之外额外接收。** + +无论哪种情况,[基于角色的访问控制](../../user_management/about_perms_and_roles/)规则都会生效,因此用户不会收到其无权访问的产品或产品类型(或其相关对象)的活动通知。 + +## 通知发送方式 + +DefectDojo 通知共有四种发送方式： + +* DefectDojo 可以发送**🔔 提醒**,以列表形式保存在 DefectDojo 界面中 +* DefectDojo 可以将通知发送到**电子邮件**地址 +* DefectDojo 可以将通知发送到 **Slack**的共享或个人频道 +* DefectDojo 还可以将通知发送到 **Microsoft Teams** 的共享频道 + +通知可以同时发送到多个目的地。 + +接收 Slack 和 Teams 通知需要您拥有可正常工作的集成。有关设置该集成的更多信息,请参阅我们的[指南](../email_slack_teams)。 + +## 应用内提醒 + +DefectDojo 的提醒系统可让您随时了解所有产品或系统活动。 + +### 提醒列表 + +提醒列表始终显示在 DefectDojo 右上角,以紧凑列表的形式展示通知。点击每条提醒都会直接带您进入 DefectDojo 中的相关页面。 + +您可以点击右上角的 **🔔▼ 图标**打开提醒列表： + +![image](images/About_In-App_Alerts.png) + +如需查看所有通知及更多详细信息,可以点击**查看所有提醒 >** 按钮,打开**提醒页面**。 + +您也可以在提醒列表中点击**清除所有提醒 >**。 + +### 提醒页面 + +提醒页面保存了您在 DefectDojo 中的所有提醒及更多详细信息。在此页面上,您可以查看 DefectDojo 中每条提醒的描述,并在不再需要时将其从提醒队列中移除。 + +![image](images/About_In-App_Alerts_2.png) + +要从提醒页面中移除一条或多条提醒,请勾选其旁边的空复选框,然后点击页面右下角的**移除所选**按钮。 + +### 关于提醒的说明 + +* 阅读某条提醒或打开提醒页面,都不会从铃铛图标旁的计数中移除任何提醒。这样您就可以方便地查看过去的提醒,将其用作提醒事项或个人活动日志。 +* 使用提醒菜单中的**清除所有提醒 >** 功能也会完全清空**提醒页面**,因此请谨慎使用此功能。 +* 移除一条提醒只会影响您自己的提醒列表,不会影响其他用户的提醒。 +* 移除一条提醒不会删除 DefectDojo 中的任何导入历史或活动日志。 + +## 缩小审核请求通知的范围(Pro) + +如果向所有符合条件的审核者发起审核请求,该资产上所有符合条件的人都会收到通知。对于只负责您部分资产的审核者来说,这意味着大量邮件。 + +在 DefectDojo Pro 界面中,您可以缩小自己接收审核请求通知的范围。在您的通知设置页面的**审核请求**下： + +* **审核请求范围**——*全部*(默认)会就您可见的所有内容通知您。*已选择*则将范围缩小到您所选的资产和资产类型。 +* **审核请求资产** / **审核请求资产类型**——您希望收到通知的那部分资产范围。只要请求所涉及的资产或资产类型属于您所选范围之一,即视为匹配。 + +有两点需要明确： + +* 选择*已选择*但不选取任何内容,表示**不通知任何内容**,而不是通知全部。 +* 缩小范围只是抑制了通知,**而不是抑制请求本身**。您仍然是被请求的审核者,该请求仍会出现在您[我的工作](/metrics_reports/dashboards/pro__my_work/)队列的**等待我审核**下——只是您不会收到相关消息提醒。这是有意为之的设计:队列是持久记录,通知只是提醒。 + +这种范围缩小的优先级也高于下文所述的系统级覆盖设置,因此即使 `review_requested` 被配置为优先于个人偏好,已将自己排除在范围之外的审核者仍不会收到通知。 + +范围缩小也可以通过通知端点的 API 进行设置,如果您需要一次性为多名审核者进行配置,这是更实用的方式。 + +## 工作分配通知(Pro) + +当发现项被分配给您时,**已分配工作**通知会告诉您分配了多少项,并附有指向您“我的工作”队列的链接。 + +该通知是按人汇总的,而不是按发现项逐条发送:分配一百个发现项只会发送一条消息,而不是一百条。与审核请求一样,无论通知是否送达,分配情况都会显示在您的队列中。 + +## 开源版注意事项 + +### 特定覆盖设置 + +系统通知设置(scope: system)描述向超级管理员发送通知的方式。用户通知设置(scope: personal)描述向特定用户发送通知的方式。 + +但是,存在一种特定场景:用户决定禁用某些通知(以减少干扰),但系统设置会覆盖此行为。默认情况下,这些覆盖仅适用于 `user_mentioned` 和 `review_requested`。 + +此设置的作用范围可自定义(参见环境变量 `DD_NOTIFICATIONS_SYSTEM_LEVEL_TRUMP`)。 + +有关此行为的更多信息,请参阅[相关的拉取请求 #9699](https://github.com/DefectDojo/django-DefectDojo/pull/9699/) + +### Webhook(实验性) + +DefectDojo 还支持 webhook,其触发事件与其他通知相同(可以在相同情况下收到通知)。有关设置的详细信息,请参阅[相关页面](/automation/api/notification_webhooks/)。 diff --git a/docs/content/admin/notifications/configure_personal_notifs.it.md b/docs/content/admin/notifications/configure_personal_notifs.it.md new file mode 100644 index 0000000000..5006458b64 --- /dev/null +++ b/docs/content/admin/notifications/configure_personal_notifs.it.md @@ -0,0 +1,35 @@ +--- +title: Impostare le notifiche personali +description: Configurare le notifiche per un account personale +aliases: +- /it/en/customize_dojo/notifications/configure_personal_notifs +--- + +## Configurare le notifiche personali + +Le Notifiche personali vengono inviate in aggiunta alle Notifiche a livello di sistema e si applicano a qualsiasi Prodotto, Tipo di prodotto o altro tipo di dati a cui hai accesso. Le preferenze delle Notifiche personali si applicano solo a un singolo utente e possono essere impostate solo sull'account che le sta configurando. + +![image](images/Configure_System_&_Personal_Notifications.png) + +Le notifiche di sistema vengono impostate da un Superuser di DefectDojo e non possono essere disattivate dal singolo utente. + +1. Parti dalla pagina Notifications (⚙️**Configuration \> Notifications** nella barra laterale). +2. Dal menu a discesa **Scope**, puoi selezionare quale insieme di notifiche desideri modificare. +3. Seleziona Personal Notifications. +4. Seleziona il metodo di notifica che desideri usare per ciascun tipo di notifica. Puoi selezionarne più di uno. + +Le Notifiche personali non possono essere inviate tramite Microsoft Teams, poiché Teams consente solo di pubblicare notifiche globali in un unico canale. + +### Ricevere notifiche personali per uno specifico Prodotto + +Oltre alle notifiche personali standard, gli Utenti di DefectDojo possono anche ricevere notifiche per l'attività su uno specifico Prodotto. Questo è utile quando ci sono determinati Prodotti che un utente deve monitorare più da vicino. + +![image](images/Configure_System_&_Personal_Notifications_3.png) + +Questa configurazione può essere modificata dalla sezione **Notifications** nella pagina **Product**: ad esempio `your-instance.defectdojo.com/product/{id}`. + +Da qui puoi impostare se desideri ricevere notifiche **🔔 Alert**, **Mail** o **Slack** per le azioni intraprese su questo particolare Prodotto. Queste notifiche si applicano in aggiunta a qualsiasi notifica a livello di sistema che già ricevi. + +Microsoft Teams non può inviare notifiche personali di alcun tipo, quindi le notifiche Teams non possono essere selezionate da questo menu. + +Le notifiche email personali verranno sempre inviate all'indirizzo email associato al tuo login DefectDojo. Per configurare un account Slack personale per ricevere le notifiche, consulta la nostra [Guida](../email_slack_teams/#send-personal-notifications-to-slack). diff --git a/docs/content/admin/notifications/configure_personal_notifs.pt-br.md b/docs/content/admin/notifications/configure_personal_notifs.pt-br.md new file mode 100644 index 0000000000..d70b7a06aa --- /dev/null +++ b/docs/content/admin/notifications/configure_personal_notifs.pt-br.md @@ -0,0 +1,35 @@ +--- +title: Definir Notificações Pessoais +description: Configure notificações para uma conta pessoal +aliases: +- /pt-br/en/customize_dojo/notifications/configure_personal_notifs +--- + +## Configurar Notificações Pessoais + +As Notificações Pessoais são enviadas além das Notificações do Sistema e se aplicam a qualquer Produto, Tipo de Produto ou outro tipo de dado ao qual você tenha acesso. As preferências de Notificação Pessoal se aplicam apenas a um único usuário e só podem ser definidas na conta que está configurando-as. + +![image](images/Configure_System_&_Personal_Notifications.png) + +As notificações do sistema são definidas por um Superuser do DefectDojo e não podem ser desativadas por um usuário individual. + +1. Comece pela página de Notificações (⚙️**Configuração \> Notifications** na barra lateral). +2. No menu suspenso **Escopo**, você pode selecionar qual conjunto de notificações deseja editar. +3. Selecione Notificações Pessoais. +4. Marque o método de notificação que deseja usar para cada tipo de notificação. Você pode selecionar mais de um. + +As Notificações Pessoais não podem ser enviadas pelo Microsoft Teams, já que o Teams só permite publicar notificações Globais em um único canal. + +### Receber Notificações Pessoais para um Produto específico + +Além das notificações pessoais padrão, os Usuários do DefectDojo também podem receber notificações sobre atividades em um Produto específico. Isso é útil quando há determinados Produtos que um usuário precisa monitorar mais de perto. + +![image](images/Configure_System_&_Personal_Notifications_3.png) + +Essa configuração pode ser alterada na seção **Notifications** da página do **Produto**: por exemplo, `your-instance.defectdojo.com/product/{id}`. + +A partir daí, você pode definir se deseja receber notificações de **🔔 Alert**, **Mail** ou **Slack** para ações realizadas nesse Produto específico. Essas notificações se aplicam além de quaisquer notificações do sistema que você já esteja recebendo. + +O Microsoft Teams não pode enviar notificações pessoais de nenhum tipo, portanto as notificações do Teams não podem ser escolhidas nesse menu. + +As notificações pessoais por e-mail sempre serão enviadas ao e-mail associado ao seu login do DefectDojo. Para configurar uma conta pessoal do Slack e receber notificações, consulte nosso [Guia](../email_slack_teams/#send-personal-notifications-to-slack). diff --git a/docs/content/admin/notifications/configure_personal_notifs.zh-hans.md b/docs/content/admin/notifications/configure_personal_notifs.zh-hans.md new file mode 100644 index 0000000000..baa5b207ae --- /dev/null +++ b/docs/content/admin/notifications/configure_personal_notifs.zh-hans.md @@ -0,0 +1,35 @@ +--- +title: 设置个人通知 +description: 为个人账户配置通知 +aliases: +- /zh-hans/en/customize_dojo/notifications/configure_personal_notifs +--- + +## 配置个人通知 + +个人通知会在系统级通知之外额外发送,适用于您有权访问的任何产品、产品类型或其他数据类型。个人通知偏好设置仅适用于单个用户,且只能在正在配置的账户上进行设置。 + +![image](images/Configure_System_&_Personal_Notifications.png) + +系统通知由 DefectDojo 超级用户设置,个人用户无法选择退出。 + +1. 从通知页面开始(侧边栏中的⚙️**配置 > 通知**)。 +2. 从**范围**下拉菜单中,您可以选择想要编辑的通知集合。 +3. 选择个人通知。 +4. 勾选您希望为每种通知类型使用的通知方式。您可以选择多种方式。 + +个人通知无法通过 Microsoft Teams 发送,因为 Teams 只允许在单个频道中发布全局通知。 + +### 接收特定产品的个人通知 + +除标准个人通知外,DefectDojo 用户还可以接收特定产品上活动的通知。当用户需要更密切地监控某些产品时,此功能会很有帮助。 + +![image](images/Configure_System_&_Personal_Notifications_3.png) + +此配置可以在**产品**页面的**通知**部分进行更改,例如:`your-instance.defectdojo.com/product/{id}`。 + +在此处,您可以设置是否希望针对该特定产品上发生的操作接收**🔔 提醒**、**邮件**或 **Slack** 通知。这些通知会在您已经接收的任何系统级通知之外额外生效。 + +Microsoft Teams 无法发送任何类型的个人通知,因此无法从此菜单中选择 Teams 通知。 + +个人邮件通知始终会发送到与您的 DefectDojo 登录账户关联的邮箱。要设置个人 Slack 账户以接收通知,请参阅我们的[指南](../email_slack_teams/#send-personal-notifications-to-slack)。 diff --git a/docs/content/admin/notifications/configure_system_notifs.it.md b/docs/content/admin/notifications/configure_system_notifs.it.md new file mode 100644 index 0000000000..3a465868f7 --- /dev/null +++ b/docs/content/admin/notifications/configure_system_notifs.it.md @@ -0,0 +1,44 @@ +--- +title: Impostare le notifiche a livello di sistema +description: Come configurare le notifiche personali e di sistema +aliases: +- /it/en/customize_dojo/notifications/configure_system_notifs +--- + +DefectDojo dispone di due diversi tipi di notifiche: **Personal** (inviate a un singolo account) e **System** (inviate a tutti gli utenti). + +Sia le Notifiche personali di un account che le Notifiche di sistema globali possono essere configurate dalla stessa pagina: **⚙️Configuration \> Notifications** nella barra laterale. + +![image](images/Configure_System_&_Personal_Notifications.png) + +## Configurare le notifiche di sistema (interfaccia classica) + +**Per modificare le notifiche a livello di sistema è necessario l'accesso da Superuser.** + +1. Parti dalla pagina Notifications (⚙️ **Configuration \> Notifications** nella barra laterale). +2. Dal menu a discesa Scope, puoi selezionare quale insieme di notifiche desideri modificare. +3. Seleziona System Notifications. +4. Seleziona il metodo di consegna della notifica che desideri usare per ciascun tipo di notifica. Puoi selezionarne più di uno. + +![image](images/Configure_System_&_Personal_Notifications_2.png) + +Per impostare le destinazioni per le notifiche email a livello di sistema (Email, Slack o MS Teams), consulta la nostra [Guida](../email_slack_teams). + +## Notifiche modello + +I Superuser hanno anche accesso a un modulo "Template". Il modulo Template consente di impostare le Notifiche personali predefinite abilitate per ogni nuovo utente. + +## Dove vengono inviate le notifiche di sistema + +Le notifiche di sistema verranno inviate a: +- l'unico indirizzo email specificato nelle System Settings (se abilitato) +- qualsiasi utente DefectDojo con un account e le autorizzazioni RBAC appropriate +- l'account Slack o Teams a livello di sistema. + +Come per qualsiasi notifica in DefectDojo, le Notifiche di sistema verranno inviate solo agli utenti che hanno accesso ai dati pertinenti. Quindi, anche se le Notifiche sui Prodotti sono impostate a livello di sistema, gli utenti riceveranno notifiche solo per i Prodotti che hanno accesso a visualizzare. + +Questa restrizione non si applica alle Notifiche di sistema inviate a uno specifico indirizzo Email o canale Slack. + +Consulta la nostra guida sul [controllo degli accessi basato sui ruoli](../../user_management/about_perms_and_roles/) per maggiori informazioni su RBAC e sull'impostazione delle autorizzazioni. + +Tuttavia, gli account System Email, Slack e Teams collegati non possono applicare RBAC poiché non sono associati a uno specifico utente DefectDojo. **Tutte le notifiche a livello di sistema selezionate verranno inviate a queste destinazioni, quindi dovresti assicurarti che questi canali siano accessibili solo a persone specifiche della tua organizzazione.** diff --git a/docs/content/admin/notifications/configure_system_notifs.pt-br.md b/docs/content/admin/notifications/configure_system_notifs.pt-br.md new file mode 100644 index 0000000000..811b611317 --- /dev/null +++ b/docs/content/admin/notifications/configure_system_notifs.pt-br.md @@ -0,0 +1,44 @@ +--- +title: Definir Notificações do Sistema +description: Como configurar notificações Pessoais e do Sistema +aliases: +- /pt-br/en/customize_dojo/notifications/configure_system_notifs +--- + +O DefectDojo possui dois tipos diferentes de notificação: **Pessoal** (enviada a uma única conta) e **do Sistema** (enviada a todos os usuários). + +Tanto as Notificações Pessoais de uma conta quanto as Notificações do Sistema globais podem ser configuradas na mesma página: **⚙️Configuração \> Notifications** na barra lateral. + +![image](images/Configure_System_&_Personal_Notifications.png) + +## Configurar notificações do Sistema (Interface Clássica) + +**Você precisará de acesso de Superuser para alterar as notificações do Sistema.** + +1. Comece pela página de Notificações (⚙️ **Configuração \> Notifications** na barra lateral). +2. No menu suspenso Escopo, você pode selecionar qual conjunto de notificações deseja editar. +3. Selecione Notificações do Sistema. +4. Marque o método de entrega de notificação que deseja usar para cada tipo de notificação. Você pode selecionar mais de um. + +![image](images/Configure_System_&_Personal_Notifications_2.png) + +Para definir os destinos das notificações de e-mail do sistema (Email, Slack ou MS Teams), consulte nosso [Guia](../email_slack_teams). + +## Notificações de Modelo + +Os Superusers também têm acesso a um formulário de "Modelo". O Formulário de Modelo permite definir as Notificações Pessoais padrão que ficam ativadas para qualquer novo usuário. + +## Para Onde as Notificações do Sistema São Enviadas + +As notificações do sistema serão enviadas para: +- o único endereço de e-mail especificado em System Settings (se ativado) +- quaisquer usuários do DefectDojo com contas e permissões de RBAC apropriadas +- a conta do Slack ou Teams em nível de Sistema. + +Assim como qualquer notificação no DefectDojo, as Notificações do Sistema só serão enviadas a usuários que tenham acesso aos dados relevantes. Portanto, mesmo que as Notificações de Produto sejam configuradas em nível de Sistema, os usuários só receberão notificações dos Produtos aos quais têm acesso para visualizar. + +Essa restrição não se aplica a Notificações do Sistema enviadas para um canal específico de E-mail ou Slack. + +Consulte nosso guia sobre [Controle de Acesso Baseado em Função](../../user_management/about_perms_and_roles/) para mais informações sobre RBAC e a definição de permissões. + +No entanto, as contas conectadas de E-mail, Slack e Teams do Sistema não podem aplicar RBAC, pois não estão associadas a um usuário específico do DefectDojo. **Todas as notificações selecionadas em nível de sistema serão enviadas para esses destinos, portanto você deve garantir que esses canais só possam ser acessados por pessoas específicas da sua organização.** diff --git a/docs/content/admin/notifications/configure_system_notifs.zh-hans.md b/docs/content/admin/notifications/configure_system_notifs.zh-hans.md new file mode 100644 index 0000000000..6e9ce3aee0 --- /dev/null +++ b/docs/content/admin/notifications/configure_system_notifs.zh-hans.md @@ -0,0 +1,44 @@ +--- +title: 设置系统级通知 +description: 如何配置个人通知与系统通知 +aliases: +- /zh-hans/en/customize_dojo/notifications/configure_system_notifs +--- + +DefectDojo 有两种不同类型的通知:**个人通知**(发送给单个账户)和**系统通知**(发送给所有用户)。 + +账户的个人通知和全局系统通知都可以在同一个页面进行配置:侧边栏中的**⚙️配置 > 通知**。 + +![image](images/Configure_System_&_Personal_Notifications.png) + +## 配置系统通知(经典界面) + +**您需要拥有超级用户权限才能更改系统级通知。** + +1. 从通知页面开始(侧边栏中的⚙️ **配置 > 通知**)。 +2. 从范围下拉菜单中,您可以选择想要编辑的通知集合。 +3. 选择系统通知。 +4. 勾选您希望为每种通知类型使用的发送方式。您可以选择多种方式。 + +![image](images/Configure_System_&_Personal_Notifications_2.png) + +要设置系统级邮件通知的目标地址(电子邮件、Slack 或 MS Teams),请参阅我们的[指南](../email_slack_teams)。 + +## 模板通知 + +超级用户还可以访问"模板"表单。模板表单可用于设置为任何新用户默认启用的个人通知。 + +## 系统通知的发送对象 + +系统通知将发送给: +- 在系统设置中指定的单一电子邮件地址(如已启用) +- 拥有账户且具备相应 RBAC 权限的任何 DefectDojo 用户 +- 系统级的 Slack 或 Teams 账户。 + +与 DefectDojo 中的任何通知一样,系统通知只会发送给有权访问相关数据的用户。因此,即使产品通知已在系统级设置,用户也只会收到其有权查看的产品的通知。 + +此限制不适用于发送到特定电子邮件地址或 Slack 频道的系统通知。 + +有关 RBAC 及权限设置的更多信息,请参阅我们关于[基于角色的访问控制](../../user_management/about_perms_and_roles/)的指南。 + +但是,所连接的系统电子邮件、Slack 和 Teams 账户无法应用 RBAC,因为它们并未与特定的 DefectDojo 用户关联。**所有已选择的系统级通知都会发送到这些位置,因此您应确保这些渠道只能被您组织内的特定人员访问。** diff --git a/docs/content/admin/notifications/email_slack_teams.it.md b/docs/content/admin/notifications/email_slack_teams.it.md new file mode 100644 index 0000000000..f30286cd77 --- /dev/null +++ b/docs/content/admin/notifications/email_slack_teams.it.md @@ -0,0 +1,144 @@ +--- +title: Configurare le notifiche Email, Slack o Teams +description: Configura Microsoft Teams per ricevere le notifiche +aliases: +- /it/en/customize_dojo/notifications/email_slack_teams +--- + +**Sarà necessario l'accesso Superuser per utilizzare la pagina System Settings, indispensabile per completare questa procedura.** + +Le notifiche possono essere inviate a Slack o Teams quando in DefectDojo si verificano determinati eventi. + +## Configurazione delle notifiche Slack + +DefectDojo può pubblicare notifiche su Slack in due modi diversi: + +* Notifiche a livello di sistema, che verranno inviate a un singolo canale Slack +* Notifiche personali, che verranno inviate solo a utenti specifici. + +Ecco un esempio di notifica Slack inviata da DefectDojo: +​ +![image](images/Configure_a_Slack_Integration.png) + +DefectDojo non dispone di un'app Slack dedicata, ma è possibile crearne facilmente una per il proprio workspace seguendo questa guida. Un'app Slack è necessaria per l'invio corretto sia delle notifiche di sistema sia di quelle personali. + +### Creare un'applicazione Slack + +Per configurare una connessione Slack con DefectDojo, è necessario creare un'app Slack personalizzata. + +1. Avviare questa procedura dalla pagina Slack Apps: . +2. Fare clic su ‘**Create New App**’. +3. Selezionare ‘**From App Manifest**’. +4. Selezionare il proprio workspace Slack dal menu. +5. Inserire il proprio App Manifest \- è possibile copiare e incollare questo file JSON, che include tutte le impostazioni dei permessi necessarie per consentire il funzionamento dell'integrazione Slack. +​ +``` +{ + "_metadata": { + "major_version": 1, + "minor_version": 1 + }, + "display_information": { + "name": "DefectDojo", + "description": "Notifications from DefectDojo. See https://docs.defectdojo.com/en/notifications/configure-a-slack-integration/ for configuration steps.", + "background_color": "#0000AA" + }, + "features": { + "bot_user": { + "display_name": "DefectDojo Notifications" + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "chat:write", + "chat:write.customize", + "chat:write.public", + "incoming-webhook", + "users:read", + "users:read.email" + ] + }, + "redirect_urls": [ + "https://slack.com/oauth/v2/authorize" + ] + } + } +``` + +Rivedere l'App Summary e fare clic su Create App al termine. Completare l'installazione facendo clic sul pulsante **Install To Workplace**. + +### Configurare l'integrazione Slack in DefectDojo + +A questo punto è necessario configurare l'integrazione Slack su DefectDojo per completare l'integrazione. + +**Sarà necessario l'accesso Superuser per accedere alla pagina System Settings di DefectDojo.** + +1. Accedere alla pagina App Information della propria app Slack da . Si tratta dell'app creata nella prima sezione \- **Creare un'applicazione Slack**. +​ + +2. Individuare il proprio OAuth Access Token, reperibile nella barra laterale di Slack in **Features / OAuth \& Permissions**. Copiare il **Bot User OAuth Token. +​** + +![image](images/Configure_a_Slack_Integration_2.png) + +3. Aprire DefectDojo in una nuova scheda e accedere a **Configuration \> System Settings** dalla barra laterale. (Nella UI Pro, questo modulo si trova in **Enterprise Settings > System Settings**.) +4. Selezionare la casella **Enable Slack notifications**. +5. Incollare il **Bot User OAuth Token** ottenuto al passaggio 1 nel campo **Slack token**. +6. Il campo **Slack Channel** deve corrispondere al canale del workspace in cui si desidera che il bot di DefectDojo scriva le notifiche. +7. Per modificare il nome del bot di DefectDojo, è possibile inserire qui un nome personalizzato. In caso contrario, verrà utilizzato **DefectDojo Notifications**, come definito nell'App Manifest di Slack. + +Una volta completata questa procedura, DefectDojo può inviare notifiche a livello di sistema a questo canale. Selezionare le notifiche che si desidera inviare dalla [pagina System Notifications](). + +![image](images/Configure_a_Slack_Integration_3.png) + +#### Note sulle notifiche a livello di sistema in Slack: + +Slack non può applicare alcuna regola RBAC al canale Slack che si sta creando, e quindi condividerà le notifiche per l'intero sistema DefectDojo. In DefectDojo non esiste alcun metodo per filtrare le notifiche Slack a livello di sistema per Product Type, Prodotto o Engagement. + +Per applicare un filtraggio basato su RBAC ai propri messaggi Slack, è preferibile abilitare le notifiche personali di Slack. + +### Inviare notifiche personali a Slack + +Se il proprio team ha abilitato un'integrazione Slack (tramite la procedura sopra descritta), i singoli utenti possono anche configurare le notifiche da inviare direttamente al proprio canale Slackbot personale. + +1. Iniziare accedendo alla propria pagina Profile personale su DefectDojo. È possibile trovarla facendo clic sull'**icona** 👤 nell'angolo in alto a destra. Selezionare il proprio Username di DefectDojo dall'elenco. (👤 **paul** nel nostro esempio) +​ + +![image](images/Configure_a_Slack_Integration_4.png) + +2. Impostare il proprio **Slack Email Address** nel menu. Questo campo si trova all'interno di **Additional Contact Information** in DefectDojo. + +A questo punto è possibile [impostare notifiche specifiche](../about_notifications/) da inviare al proprio canale Slackbot personale. Gli altri utenti del canale Slack non riceveranno questi messaggi. + +## Configurazione delle notifiche Microsoft Teams + +Microsoft Teams può ricevere notifiche su un canale specifico. Per farlo, è necessario **configurare un incoming webhook** sul canale in cui si desidera ricevere i messaggi. + +Da notare che i vecchi [webhook Office Connector](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet) verranno dismessi da Microsoft: utilizzare un nuovo webhook basato su Power Automate Workflow, come descritto di seguito. + +1. Completare la procedura descritta nella **[documentazione Microsoft Teams](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498)** per creare un nuovo Incoming Webhook. Tenere a portata di mano il proprio link univoco logic.azure.com, poiché servirà nei passaggi successivi. È possibile creare un webhook per un canale o per una chat specifica. +​ +![image](images/Configure_a_Microsoft_Teams_Integration.png) +2. In DefectDojo, accedere a **Configuration \> System Settings** dalla barra laterale. (Nella UI Pro, questo modulo si trova in **Enterprise Settings > System Settings**.) +3. Selezionare la casella **Enable Microsoft Teams notifications**. Questo aprirà una sezione nascosta del modulo, denominata ‘**Msteams url**’. +​ +![image](images/Configure_a_Microsoft_Teams_Integration_2.png) +4. Incollare l'URL logic.azure.com (creato al passaggio 1\) nel campo **Msteams url**. L'app Teams sarà ora in ascolto delle notifiche in arrivo da DefectDojo e le pubblicherà nel canale selezionato. + +### Note sull'integrazione con Teams + +* Slack non può applicare alcuna regola RBAC al canale Teams che si sta creando, e quindi condividerà le notifiche per l'intero sistema DefectDojo. In DefectDojo non esiste alcun metodo per filtrare le notifiche Teams a livello di sistema per Product Type, Prodotto o Engagement. +* DefectDojo non può inviare notifiche personali agli utenti su Microsoft Teams. + +## Configurazione delle notifiche email a livello di sistema + +Le notifiche di DefectDojo possono anche essere inviate a un indirizzo email specifico. + +1. Dalla pagina System Settings (**Configuration > System Settings** nella UI Classic, oppure **Enterprise Settings > System Settings** nella UI Pro) accedere a Enable Mail (email) Notifications. + +2. Selezionare la casella **Enable mail notifications**, quindi inserire l'indirizzo email a cui inviare queste notifiche (mail notifications to). + +![image](images/notifs_email.png) + +Da notare che DefectDojo non può applicare un filtraggio RBAC a queste email - verranno inviate per tutte le attività in DefectDojo. Se si preferisce inviare un insieme più personalizzato di notifiche email, è meglio configurare le [notifiche personali](../configure_personal_notifs) con un utente o un account di servizio collegato all'indirizzo appropriato. diff --git a/docs/content/admin/notifications/email_slack_teams.pt-br.md b/docs/content/admin/notifications/email_slack_teams.pt-br.md new file mode 100644 index 0000000000..1c91ce836c --- /dev/null +++ b/docs/content/admin/notifications/email_slack_teams.pt-br.md @@ -0,0 +1,142 @@ +--- +title: Configurar notificações por e-mail, Slack ou Teams +description: Configure o Microsoft Teams para receber notificações +aliases: +- /pt-br/en/customize_dojo/notifications/email_slack_teams +--- + +**Você precisará de acesso de Superusuário para usar a página de Configurações do Sistema, que é necessária para concluir este processo.** + +As notificações podem ser enviadas para o Slack ou o Teams quando determinados eventos são disparados no DefectDojo. + +## Configuração das notificações do Slack + +O DefectDojo pode publicar notificações no Slack de duas formas diferentes: + +* Notificações de todo o sistema, que serão enviadas para um único canal do Slack +* Notificações pessoais, que serão enviadas apenas para usuários específicos. + +Veja um exemplo de uma notificação do Slack enviada pelo DefectDojo: +​ +![image](images/Configure_a_Slack_Integration.png) + +O DefectDojo não possui um aplicativo dedicado do Slack, mas é possível criar um facilmente para o seu workspace seguindo este guia. Um aplicativo do Slack é necessário para que tanto as notificações de sistema quanto as pessoais sejam enviadas corretamente. + +### Criar um aplicativo do Slack + +Para configurar uma conexão do Slack com o DefectDojo, você precisará criar um aplicativo Slack personalizado. + +1. Comece esse processo pela página de Apps do Slack: . +2. Clique em "**Create New App**". +3. Selecione "**From App Manifest**". +4. Selecione seu workspace do Slack no menu. +5. Insira seu App Manifest - você pode copiar e colar este arquivo JSON, que inclui todas as configurações de permissão necessárias para que a integração com o Slack funcione. +​ +``` +{ + "_metadata": { + "major_version": 1, + "minor_version": 1 + }, + "display_information": { + "name": "DefectDojo", + "description": "Notifications from DefectDojo. See https://docs.defectdojo.com/en/notifications/configure-a-slack-integration/ for configuration steps.", + "background_color": "#0000AA" + }, + "features": { + "bot_user": { + "display_name": "DefectDojo Notifications" + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "chat:write", + "chat:write.customize", + "chat:write.public", + "incoming-webhook", + "users:read", + "users:read.email" + ] + }, + "redirect_urls": [ + "https://slack.com/oauth/v2/authorize" + ] + } + } +``` + +Revise o resumo do aplicativo (App Summary) e clique em Create App quando terminar. Conclua a instalação clicando no botão **Install To Workplace**. + +### Configurar sua integração do Slack no DefectDojo + +Agora você precisará configurar a integração do Slack no DefectDojo para concluir a integração. + +**Você precisará de acesso de Superusuário para acessar a página de Configurações do Sistema do DefectDojo.** + +1. Navegue até a página App Information do seu aplicativo Slack, em . Este será o aplicativo criado na primeira seção - **Criar um aplicativo do Slack**. +​ +2. Localize seu OAuth Access Token. Ele pode ser encontrado na barra lateral do Slack - **Features / OAuth & Permissions**. Copie o **Bot User OAuth Token. +​** + +![image](images/Configure_a_Slack_Integration_2.png) + +3. Abra o DefectDojo em uma nova aba e navegue até **Configuration > System Settings** na barra lateral. (Na interface Pro, este formulário está localizado em **Enterprise Settings > System Settings**.) +4. Marque a caixa **Enable Slack notifications**. +5. Cole o **Bot User OAuth Token** obtido no Passo 1 no campo **Slack token**. +6. O campo **Slack Channel** deve corresponder ao canal do seu workspace onde você deseja que as notificações sejam publicadas por um bot do DefectDojo. +7. Se quiser alterar o nome do bot do DefectDojo, você pode inserir um nome personalizado aqui. Caso contrário, será usado **DefectDojo Notifications**, conforme definido no App Manifest do Slack. + +Ao concluir esse processo, o DefectDojo poderá enviar notificações de todo o sistema para esse canal. Selecione as notificações que deseja enviar na [página de Notificações do Sistema](). + +![image](images/Configure_a_Slack_Integration_3.png) + +#### Observações sobre notificações de todo o sistema no Slack: + +O Slack não pode aplicar regras de RBAC ao canal do Slack que você está criando, portanto as notificações serão compartilhadas para todo o sistema DefectDojo. Não há como filtrar as notificações de todo o sistema no Slack por Tipo de Produto, Produto ou Engajamento. + +Se você deseja aplicar filtragem baseada em RBAC às suas mensagens do Slack, habilitar notificações pessoais do Slack é uma opção melhor. + +### Enviar notificações pessoais para o Slack + +Se sua equipe tiver uma integração do Slack habilitada (pelo processo acima), usuários individuais também podem configurar notificações para serem enviadas diretamente ao seu canal pessoal do Slackbot. + +1. Comece navegando até sua página de Perfil pessoal no DefectDojo. Encontre-a clicando no ícone 👤 no canto superior direito. Selecione seu nome de usuário do DefectDojo na lista. (👤 **paul** em nosso exemplo) +​ +![image](images/Configure_a_Slack_Integration_4.png) + +2. Defina seu **Slack Email Address** no menu. Esse campo está aninhado em **Additional Contact Information** no DefectDojo. + +Agora você pode [definir notificações específicas](../about_notifications/) para serem enviadas ao seu canal pessoal do Slackbot. Outros usuários do seu canal do Slack não receberão essas mensagens. + +## Configuração das notificações do Microsoft Teams + +O Microsoft Teams pode receber notificações em um canal específico. Para isso, você precisará **configurar um webhook de entrada** no canal onde deseja receber as mensagens. + +Observe que os antigos [webhooks do Office Connector](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet) serão descontinuados pela Microsoft; use um novo webhook baseado em Power Automate Workflow, conforme documentado abaixo. + +1. Conclua o processo descrito na **[documentação do Microsoft Teams](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498)** para criar um novo Incoming Webhook. Mantenha seu link exclusivo logic.azure.com à mão, pois você vai precisar dele nas próximas etapas. Você pode criar o webhook para um canal ou para um chat específico. +​ +![image](images/Configure_a_Microsoft_Teams_Integration.png) +2. No DefectDojo, navegue até **Configuration > System Settings** na barra lateral. (Na interface Pro, este formulário está localizado em **Enterprise Settings > System Settings**.) +3. Marque a caixa **Enable Microsoft Teams notifications**. Isso abrirá uma seção oculta do formulário, chamada "**Msteams url**". +​ +![image](images/Configure_a_Microsoft_Teams_Integration_2.png) +4. Cole a URL logic.azure.com (criada no Passo 1) na caixa **Msteams url**. Seu aplicativo do Teams passará a escutar as notificações recebidas do DefectDojo e a publicá-las no canal selecionado. + +### Observações sobre a integração com o Teams + +* O Slack não pode aplicar regras de RBAC ao canal do Teams que você está criando, portanto as notificações serão compartilhadas para todo o sistema DefectDojo. Não há como filtrar as notificações de todo o sistema no Teams por Tipo de Produto, Produto ou Engajamento. +* O DefectDojo não pode enviar notificações pessoais a usuários no Microsoft Teams. + +## Configuração das notificações por e-mail de todo o sistema + +As notificações do DefectDojo também podem ser enviadas para um endereço de e-mail específico. + +1. Na página de Configurações do Sistema (**Configuration > System Settings** na interface Clássica, ou **Enterprise Settings > System Settings** na interface Pro), navegue até Enable Mail (email) Notifications. + +2. Marque a caixa **Enable mail notifications** e, em seguida, insira o endereço de e-mail para o qual deseja que essas notificações sejam enviadas (mail notifications to). + +![image](images/notifs_email.png) + +Observe que o DefectDojo não pode aplicar filtragem de RBAC a esses e-mails - eles serão enviados para toda a atividade no DefectDojo. Se preferir enviar um conjunto mais personalizado de notificações por e-mail, é melhor configurar [Notificações Pessoais](../configure_personal_notifs) com um usuário ou conta de serviço vinculada ao endereço apropriado. diff --git a/docs/content/admin/notifications/email_slack_teams.zh-hans.md b/docs/content/admin/notifications/email_slack_teams.zh-hans.md new file mode 100644 index 0000000000..dab838dce9 --- /dev/null +++ b/docs/content/admin/notifications/email_slack_teams.zh-hans.md @@ -0,0 +1,142 @@ +--- +title: 设置电子邮件、Slack 或 Teams 通知 +description: 设置 Microsoft Teams 以接收通知 +aliases: +- /zh-hans/en/customize_dojo/notifications/email_slack_teams +--- + +**您需要拥有超级用户权限才能访问系统设置页面,完成此过程需要该权限。** + +当 DefectDojo 中触发某些事件时,通知可以推送到 Slack 或 Teams。 + +## Slack 通知设置 + +DefectDojo 可以通过两种不同的方式发布 Slack 通知: + +* 系统级通知,将发送到单个 Slack 频道 +* 个人通知,仅发送给特定用户。 + +以下是从 DefectDojo 发送的 Slack 通知示例: +​ +![image](images/Configure_a_Slack_Integration.png) + +DefectDojo 没有专用的 Slack 应用程序,但您可以按照本指南轻松为您的工作区创建一个。无论是系统通知还是个人通知,都需要一个 Slack 应用程序才能正确发送。 + +### 创建 Slack 应用程序 + +要设置 DefectDojo 与 Slack 的连接,您需要创建一个自定义 Slack 应用程序。 + +1. 从 Slack 应用程序页面开始此过程: 。 +2. 点击“**Create New App**”。 +3. 选择“**From App Manifest**”。 +4. 从菜单中选择您的 Slack 工作区。 +5. 输入您的 App Manifest——您可以复制并粘贴此 JSON 文件,其中包含允许 Slack 集成运行所需的所有权限设置。 +​ +``` +{ + "_metadata": { + "major_version": 1, + "minor_version": 1 + }, + "display_information": { + "name": "DefectDojo", + "description": "Notifications from DefectDojo. See https://docs.defectdojo.com/en/notifications/configure-a-slack-integration/ for configuration steps.", + "background_color": "#0000AA" + }, + "features": { + "bot_user": { + "display_name": "DefectDojo Notifications" + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "chat:write", + "chat:write.customize", + "chat:write.public", + "incoming-webhook", + "users:read", + "users:read.email" + ] + }, + "redirect_urls": [ + "https://slack.com/oauth/v2/authorize" + ] + } + } +``` + +查看 App Summary,完成后点击 Create App。点击 **Install To Workplace** 按钮完成安装。 + +### 在 DefectDojo 中配置您的 Slack 集成 + +现在,您需要在 DefectDojo 上配置 Slack 集成以完成整合。 + +**您需要拥有超级用户权限才能访问 DefectDojo 的系统设置页面。** + +1. 从 导航到您的 Slack 应用程序的 App Information 页面。这是您在第一部分“**创建 Slack 应用程序**”中创建的应用程序。 +​ +2. 找到您的 OAuth Access Token。可以在 Slack 侧边栏的 **Features / OAuth & Permissions** 中找到。复制 **Bot User OAuth Token。 +​** + +![image](images/Configure_a_Slack_Integration_2.png) + +3. 在新标签页中打开 DefectDojo,并从侧边栏导航到 **Configuration > System Settings**。(在 Pro UI 中,此表单位于 **Enterprise Settings > System Settings** 下。) +4. 勾选 **Enable Slack notifications** 复选框。 +5. 将步骤 1 中的 **Bot User OAuth Token** 粘贴到 **Slack token** 字段中。 +6. **Slack Channel** 字段应对应您希望 DefectDojo 机器人在您的工作区中发布通知的频道。 +7. 如果您想更改 DefectDojo 机器人的名称,可以在此处输入自定义名称。如果不更改,将使用 Slack App Manifest 中确定的 **DefectDojo Notifications**。 + +完成此过程后,DefectDojo 便可以向该频道发送系统级通知。请从 [System Notifications page]() 中选择您想要发送的通知。 + +![image](images/Configure_a_Slack_Integration_3.png) + +#### 关于 Slack 系统级通知的说明: + +Slack 无法对您创建的 Slack 频道应用任何 RBAC 规则,因此该频道将共享整个 DefectDojo 系统的通知。DefectDojo 没有提供按产品类型、产品或测试活动筛选系统级 Slack 通知的方法。 + +如果您想对 Slack 消息应用基于 RBAC 的筛选,启用 Slack 个人通知是更好的选择。 + +### 向 Slack 发送个人通知 + +如果您的团队已启用 Slack 集成(通过上述过程),各个用户还可以配置通知,使其直接发送到您的个人 Slackbot 频道。 + +1. 首先导航到您在 DefectDojo 上的个人 Profile 页面。点击右上角的 👤 **图标** 即可找到该页面。从列表中选择您的 DefectDojo 用户名。(在我们的示例中为 👤 **paul**) +​ +![image](images/Configure_a_Slack_Integration_4.png) + +2. 在菜单中设置您的 **Slack Email Address**。此字段嵌套在 DefectDojo 的 **Additional Contact Information** 下。 + +现在您可以[设置特定通知](../about_notifications/)发送到您的个人 Slackbot 频道。您 Slack 频道中的其他用户不会收到这些消息。 + +## Microsoft Teams 通知设置 + +Microsoft Teams 可以在特定频道中接收通知。为此,您需要在希望接收消息的频道上**设置传入 Webhook**。 + +请注意,旧版 [Office Connector webhooks](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet) 即将被 Microsoft 淘汰,请按照下文说明使用基于 Power Automate Workflow 的新版 Webhook。 + +1. 按照 **[Microsoft Teams Documentation](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498)** 中列出的流程创建一个新的 Incoming Webhook。请妥善保管您独有的 logic.azure.com 链接,后续步骤中会用到。您可以为某个频道或特定聊天创建 Webhook。 +​ +![image](images/Configure_a_Microsoft_Teams_Integration.png) +2. 在 DefectDojo 中,从侧边栏导航到 **Configuration > System Settings**。(在 Pro UI 中,此表单位于 **Enterprise Settings > System Settings** 下。) +3. 勾选 **Enable Microsoft Teams notifications** 复选框。这将展开表单中一个隐藏的部分,标记为“**Msteams url**”。 +​ +![image](images/Configure_a_Microsoft_Teams_Integration_2.png) +4. 将(在步骤 1 中创建的)logic.azure.com URL 粘贴到 **Msteams url** 框中。您的 Teams 应用程序现在将侦听来自 DefectDojo 的传入通知,并将其发布到您选择的频道。 + +### 关于 Teams 集成的说明 + +* Slack 无法对您创建的 Teams 频道应用任何 RBAC 规则,因此该频道将共享整个 DefectDojo 系统的通知。DefectDojo 没有提供按产品类型、产品或测试活动筛选系统级 Teams 通知的方法。 +* DefectDojo 无法向 Microsoft Teams 上的用户发送个人通知。 + +## 系统级电子邮件通知设置 + +DefectDojo 的通知也可以发送到特定的电子邮件地址。 + +1. 从系统设置页面(在 Classic UI 中为 **Configuration > System Settings**,在 Pro UI 中为 **Enterprise Settings > System Settings**)导航到 Enable Mail (email) Notifications。 + +2. 勾选 **Enable mail notifications** 复选框,然后输入您希望接收这些通知的电子邮件地址(mail notifications to)。 + +![image](images/notifs_email.png) + +请注意,DefectDojo 无法对这些电子邮件应用 RBAC 筛选——它们将针对 DefectDojo 中的所有活动发送。如果您希望发送更加定制化的电子邮件通知,最好使用与相应地址关联的用户或服务账户设置[个人通知](../configure_personal_notifs)。 diff --git a/docs/content/admin/sso/PRO__auth0.it.md b/docs/content/admin/sso/PRO__auth0.it.md new file mode 100644 index 0000000000..9c3f2bd257 --- /dev/null +++ b/docs/content/admin/sso/PRO__auth0.it.md @@ -0,0 +1,33 @@ +--- +title: Auth0 +description: Configura l'SSO Auth0 in DefectDojo Pro +weight: 3 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite Auth0. La versione open source di DefectDojo non include l'SSO — vedi [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Prerequisiti + +Completa i seguenti passaggi nella dashboard di Auth0 prima di configurare DefectDojo: + +1. Crea una nuova applicazione: **Applications > Create Application > Single Page Web Application**. + +2. Configura l'applicazione: + - **Name:** `DefectDojo` + - **Allowed Callback URLs:** `https://your-instance.cloud.defectdojo.com/complete/auth0/` + +3. Annota i seguenti valori — ti serviranno in DefectDojo: + - **Domain** + - **Client ID** + - **Client Secret** + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **Auth0** e compila il modulo: + +- **Auth0 OAuth Key** — inserisci il tuo **Client ID** +- **Auth0 OAuth Secret** — inserisci il tuo **Client Secret** +- **Auth0 Domain** — inserisci il tuo **Domain** + +Seleziona **Enable Auth0 OAuth** per aggiungere un pulsante **Login With Auth0** alla pagina di accesso di DefectDojo. diff --git a/docs/content/admin/sso/PRO__auth0.pt-br.md b/docs/content/admin/sso/PRO__auth0.pt-br.md new file mode 100644 index 0000000000..59123fcd3d --- /dev/null +++ b/docs/content/admin/sso/PRO__auth0.pt-br.md @@ -0,0 +1,34 @@ +--- +title: Auth0 +description: Configure o SSO do Auth0 no DefectDojo Pro +weight: 3 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via Auth0. O DefectDojo open-source não inclui SSO — consulte +[Usuários Autorizados](/admin/user_management/os__authorized_users/) para controle de acesso no open-source. + +## Pré-requisitos + +Conclua as etapas a seguir no seu painel do Auth0 antes de configurar o DefectDojo: + +1. Crie uma nova aplicação: **Applications > Create Application > Single Page Web Application**. + +2. Configure a aplicação: + - **Name:** `DefectDojo` + - **Allowed Callback URLs:** `https://your-instance.cloud.defectdojo.com/complete/auth0/` + +3. Anote os seguintes valores — você vai precisar deles no DefectDojo: + - **Domain** + - **Client ID** + - **Client Secret** + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **Auth0** e preencha o formulário: + +- **Auth0 OAuth Key** — insira seu **Client ID** +- **Auth0 OAuth Secret** — insira seu **Client Secret** +- **Auth0 Domain** — insira seu **Domain** + +Marque **Enable Auth0 OAuth** para adicionar um botão **Login With Auth0** à página de login do DefectDojo. diff --git a/docs/content/admin/sso/PRO__auth0.zh-hans.md b/docs/content/admin/sso/PRO__auth0.zh-hans.md new file mode 100644 index 0000000000..8d1e0b68a2 --- /dev/null +++ b/docs/content/admin/sso/PRO__auth0.zh-hans.md @@ -0,0 +1,33 @@ +--- +title: Auth0 +description: 在 DefectDojo Pro 中配置 Auth0 单点登录 +weight: 3 +audience: pro +--- + +DefectDojo Pro 支持通过 Auth0 登录。开源版 DefectDojo 不包含 SSO——开源版的访问控制请参见[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 前提条件 + +在配置 DefectDojo 之前,请先在您的 Auth0 控制台中完成以下步骤: + +1. 创建新应用:**Applications > Create Application > Single Page Web Application**。 + +2. 配置应用: + - **Name:** `DefectDojo` + - **Allowed Callback URLs:** `https://your-instance.cloud.defectdojo.com/complete/auth0/` + +3. 记录以下值——您在 DefectDojo 中会用到它们: + - **Domain** + - **Client ID** + - **Client Secret** + +## 配置 + +在 DefectDojo 中,前往**企业设置 > OAuth 设置**,选择 **Auth0**,然后填写表单: + +- **Auth0 OAuth Key**——输入您的 **Client ID** +- **Auth0 OAuth Secret**——输入您的 **Client Secret** +- **Auth0 Domain**——输入您的 **Domain** + +勾选**启用 Auth0 OAuth**,即可在 DefectDojo 登录页面添加一个**使用 Auth0 登录**按钮。 diff --git a/docs/content/admin/sso/PRO__authorization_connectors.it.md b/docs/content/admin/sso/PRO__authorization_connectors.it.md new file mode 100644 index 0000000000..9ed585520b --- /dev/null +++ b/docs/content/admin/sso/PRO__authorization_connectors.it.md @@ -0,0 +1,79 @@ +--- +title: Authorization Connectors +description: 'Visualizza tutti i provider di identità in un''unica pagina: quali sono + configurati, quali sono abilitati e quale protocollo utilizza ciascuno' +weight: 1 +audience: pro +--- + +Authorization Connectors è un'unica pagina che elenca tutti i provider di identità supportati da DefectDojo Pro, in quale stato si trova ciascuno e quale protocollo utilizza. Prima che esistesse, ogni provider risiedeva nel proprio modulo di impostazioni e non c'era modo di rispondere alla domanda "cosa è configurato su questa istanza?" senza aprirli tutti. + +Authorization Connectors è una funzionalità di **DefectDojo Pro**. La trovi in **Connect > Authorization**. Solo un **Superuser** può visualizzare o modificare la configurazione dei provider di identità. + +![Connettori di autorizzazione](images/authorization_connectors.png) + +## Come è organizzata la pagina + +I provider sono suddivisi in due sezioni, e ciascuna sezione è elencata in ordine alfabetico con un conteggio accanto al titolo: + +* **Configured Providers** — i provider che sono stati configurati su questa istanza, che siano o meno attualmente attivi. +* **Available Providers** — i provider supportati ma non ancora configurati. + +La suddivisione si basa deliberatamente su *configurato*, non su *abilitato*. Un provider che è stato configurato e poi disattivato resta in Configured Providers, perché è lì che la persona che lo ha configurato andrà a cercarlo. Il suo stato è invece indicato sulla scheda. + +| | | +| --- | --- | +| **Logo and name** | Il provider, indicato senza il suo protocollo | +| **Protocol tag** | `SAML 2.0`, `OAuth 2.0`, `OpenID Connect`, o `LDAP` | +| **Status tag** | `Enabled`, `Disabled`, o `Not configured` | +| **`BETA` tag** | Presente sui provider ancora in beta | +| **Action** | **Manage Configuration** per un provider configurato, **Configure** per uno disponibile | + +Entrambe le sezioni hanno una casella di ricerca che effettua la corrispondenza sul nome del provider e sul protocollo, quindi cercando `oauth` la pagina si restringe ai provider OAuth. + +![Provider disponibili](images/authorization_available.png) + +## Una configurazione per provider + +Le impostazioni del provider di identità sono un unico insieme di valori per provider per istanza — un'applicazione Okta, un provider di identità SAML, una directory LDAP. Le schede lo indicano chiaramente, e non esiste un "aggiungine un altro": per cambiare come un provider è configurato, si modifica la configurazione già esistente. + +Questo è ciò che rende Authorization Connectors diverso dalle [gallerie dei connettori](/connectors/upstream/about/), dove uno strumento può avere molte configurazioni fianco a fianco. + +## I tre stati e il loro significato + +| Status | Significato | Cosa fare | +| --- | --- | --- | +| **Enabled** | Configurato e accetta gli accessi | Nessuna azione | +| **Disabled** | Configurato, ma disattivato — il suo pulsante non comparirà nella pagina di accesso | Riabilitalo dalla sua configurazione quando vuoi ripristinarlo | +| **Not configured** | Supportato, ma non ancora compilato | **Configure** per impostarlo | + +Selezionando un provider si apre direttamente il modulo delle sue impostazioni. Non esiste un selettore di provider intermedio. + +## Provider supportati + +| Provider | Protocollo | Guida alla configurazione | +| --- | --- | --- | +| Auth0 | OAuth 2.0 | [Auth0](/admin/sso/pro__auth0/) | +| GitHub Enterprise | OAuth 2.0 | [GitHub Enterprise](/admin/sso/pro__github_enterprise/) | +| GitLab | OAuth 2.0 | [GitLab](/admin/sso/pro__gitlab/) | +| Google | OAuth 2.0 | [Google](/admin/sso/pro__google/) | +| Keycloak | OAuth 2.0 | [KeyCloak](/admin/sso/pro__keycloak/) | +| LDAP | LDAP | [LDAP](/admin/sso/pro__ldap/) | +| Microsoft Entra ID | OAuth 2.0 | [Azure Active Directory](/admin/sso/pro__azure_ad/) | +| Okta | OAuth 2.0 | [Okta](/admin/sso/pro__okta/) | +| OpenID Connect | OpenID Connect | [OIDC](/admin/sso/pro__oidc/) | +| SAML | SAML 2.0 | [SAML](/admin/sso/pro__saml/) | + +La pagina riporta quale sia lo *stato* della configurazione di un provider. Non restituisce mai i segreti della configurazione — client secret, password di bind e certificati non fanno parte dei dati alla base di questa pagina e non possono esserne estratti. + +## Quando un provider non si connette + +Authorization Connectors indica cosa è configurato; non mostra i tentativi di accesso falliti. Questi vengono registrati in [Diagnostics](/admin/diagnostics/pro__diagnostics/), dove SSO, SAML e LDAP riportano ciascuno i propri tentativi con il motivo del rifiuto — una firma dell'asserzione non valida, un bind rifiutato, un attributo non corrispondente. Queste righe sono a livello di istanza e quindi riservate ai superuser. + +Mantieni almeno un account superuser con nome utente e password come soluzione di riserva, e ricorda che `/login?force_login_form` restituisce il modulo di accesso standard se un provider di identità smette di funzionare. Vedi [Single Sign-On](/admin/sso/) per entrambi. + +## Correlati + +* [Single Sign-On](/admin/sso/) — le guide alla configurazione per singolo provider e le impostazioni di accesso +* [Diagnostics](/admin/diagnostics/pro__diagnostics/) — perché un tentativo di accesso è fallito +* [Connectors](/connectors/upstream/about/) — la galleria upstream a cui questa pagina si ispira diff --git a/docs/content/admin/sso/PRO__authorization_connectors.pt-br.md b/docs/content/admin/sso/PRO__authorization_connectors.pt-br.md new file mode 100644 index 0000000000..998fad2367 --- /dev/null +++ b/docs/content/admin/sso/PRO__authorization_connectors.pt-br.md @@ -0,0 +1,103 @@ +--- +title: Authorization Connectors +description: 'Veja todos os provedores de identidade em uma única página: quais estão + configurados, quais estão ativados e qual protocolo cada um utiliza' +weight: 1 +audience: pro +--- + +Authorization Connectors é uma única página que lista todos os provedores de identidade compatíveis com +o DefectDojo Pro, o estado em que cada um se encontra e qual protocolo utiliza. Antes de essa página existir, +cada provedor tinha seu próprio formulário de configurações, e não havia como responder "o que está +configurado nesta instância?" sem abrir todos eles. + +Authorization Connectors é um recurso do **DefectDojo Pro**. Encontre-o em **Connect > Authorization**. +Somente um **Superuser** pode visualizar ou alterar a configuração dos provedores de identidade. + +![Authorization Connectors](images/authorization_connectors.png) + +## Como a página está organizada + +Os provedores são divididos em duas seções, e cada seção é listada em ordem alfabética com uma contagem ao +lado do título: + +* **Configured Providers** — provedores que já foram configurados nesta instância, estejam ativados ou não + no momento. +* **Available Providers** — provedores que são compatíveis, mas ainda não foram configurados. + +A divisão é feita propositalmente por *configurado*, e não por *ativado*. Um provedor que foi configurado e +depois desativado permanece em Configured Providers, porque é ali que a pessoa que o configurou vai +procurá-lo. O estado dele fica indicado no card. + +Cada card mostra: + +| | | +| --- | --- | +| **Logo and name** | O provedor, nomeado sem o seu protocolo | +| **Protocol tag** | `SAML 2.0`, `OAuth 2.0`, `OpenID Connect`, ou `LDAP` | +| **Status tag** | `Enabled`, `Disabled`, ou `Not configured` | +| **`BETA` tag** | Presente em provedores que ainda estão em beta | +| **Action** | **Manage Configuration** para um provedor configurado, **Configure** para um disponível | + +Ambas as seções têm uma caixa de pesquisa que corresponde ao nome do provedor e ao protocolo, então +pesquisar `oauth` restringe a página aos provedores OAuth. + +![Available providers](images/authorization_available.png) + +## Uma configuração por provedor + +As configurações de provedor de identidade são um único conjunto de valores por provedor por instância — +uma aplicação Okta, um provedor de identidade SAML, um diretório LDAP. Os cards deixam isso claro, e não +existe a opção "adicionar outro": para alterar como um provedor está configurado, você edita a configuração +que já existe. + +É isso que diferencia o Authorization Connectors das [galerias de conectores](/connectors/upstream/about/), +onde uma ferramenta pode ter várias configurações lado a lado. + +## Os três estados, e o que significam + +| Status | Significado | O que fazer em seguida | +| --- | --- | --- | +| **Enabled** | Configurado e aceitando logins | Nada a fazer | +| **Disabled** | Configurado, mas desativado — seu botão não aparecerá na página de login | Reative-o a partir da sua configuração quando quiser tê-lo de volta | +| **Not configured** | Compatível, mas nada foi preenchido ainda | **Configure** para configurá-lo | + +Selecionar um provedor abre diretamente o formulário de configurações daquele provedor. Não há um seletor +intermediário de provedores. + +## Provedores compatíveis + +| Provider | Protocol | Setup guide | +| --- | --- | --- | +| Auth0 | OAuth 2.0 | [Auth0](/admin/sso/pro__auth0/) | +| GitHub Enterprise | OAuth 2.0 | [GitHub Enterprise](/admin/sso/pro__github_enterprise/) | +| GitLab | OAuth 2.0 | [GitLab](/admin/sso/pro__gitlab/) | +| Google | OAuth 2.0 | [Google](/admin/sso/pro__google/) | +| Keycloak | OAuth 2.0 | [KeyCloak](/admin/sso/pro__keycloak/) | +| LDAP | LDAP | [LDAP](/admin/sso/pro__ldap/) | +| Microsoft Entra ID | OAuth 2.0 | [Azure Active Directory](/admin/sso/pro__azure_ad/) | +| Okta | OAuth 2.0 | [Okta](/admin/sso/pro__okta/) | +| OpenID Connect | OpenID Connect | [OIDC](/admin/sso/pro__oidc/) | +| SAML | SAML 2.0 | [SAML](/admin/sso/pro__saml/) | + +A página informa qual é o *estado* da configuração de um provedor. Ela nunca retorna os segredos da +configuração — client secrets, bind passwords e certificados não fazem parte dos dados por trás desta +página, e não podem ser lidos a partir dela. + +## Quando um provedor não consegue se conectar + +Authorization Connectors informa o que está configurado; ele não mostra tentativas de login que falharam. +Essas são registradas em [Diagnostics](/admin/diagnostics/pro__diagnostics/), onde SSO, SAML e LDAP relatam +cada um suas próprias tentativas com o motivo da rejeição — uma assinatura de assertion inválida, um bind +rejeitado, um atributo incompatível. Essas linhas são de nível de instância e, portanto, exclusivas para +superusuários. + +Mantenha pelo menos uma conta de superusuário com nome de usuário e senha como alternativa, e lembre-se de +que `/login?force_login_form` retorna o formulário de login padrão caso um provedor de identidade pare de +funcionar. Veja [Single Sign-On](/admin/sso/) para ambos. + +## Conteúdo relacionado + +* [Single Sign-On](/admin/sso/) — os guias de configuração por provedor e as configurações de login +* [Diagnostics](/admin/diagnostics/pro__diagnostics/) — por que uma tentativa de login falhou +* [Connectors](/connectors/upstream/about/) — a galeria upstream na qual esta página é baseada diff --git a/docs/content/admin/sso/PRO__authorization_connectors.zh-hans.md b/docs/content/admin/sso/PRO__authorization_connectors.zh-hans.md new file mode 100644 index 0000000000..e8157915bb --- /dev/null +++ b/docs/content/admin/sso/PRO__authorization_connectors.zh-hans.md @@ -0,0 +1,80 @@ +--- +title: 授权连接器 +description: 在一个页面中查看所有身份提供商:哪些已配置、哪些已启用,以及各自使用的协议 +weight: 1 +audience: pro +--- + +授权连接器(Authorization Connectors)是一个页面,列出了 DefectDojo Pro 支持的每一个身份提供商、各自当前所处的状态,以及所使用的协议。在该页面出现之前,每个提供商都有各自独立的设置表单,无法在不逐一打开的情况下回答“这个实例上都配置了什么”这个问题。 + +授权连接器是 **DefectDojo Pro** 功能。可在**连接 > 授权**下找到该页面。只有**超级用户**才能查看或更改身份提供商配置。 + +![Authorization Connectors](images/authorization_connectors.png) + +## 页面结构 + +提供商被分为两个部分,每个部分按字母顺序列出,标题旁标有数量: + +* **已配置的提供商**——已在本实例上设置好的提供商,无论其当前是否处于开启状态。 +* **可用的提供商**——受支持但尚未配置的提供商。 + +这里刻意按“是否已配置”而非“是否已启用”来划分。一个曾被配置、随后又被关闭的提供商仍会留在“已配置的提供商”中,因为设置它的人会在那里查找它。其状态则显示在卡片上。 + +每张卡片显示: + +| | | +| --- | --- | +| **图标和名称** | 提供商名称,不含协议 | +| **协议标签** | `SAML 2.0`、`OAuth 2.0`、`OpenID Connect` 或 `LDAP` | +| **状态标签** | `Enabled`、`Disabled` 或 `Not configured` | +| **`BETA` 标签** | 出现在仍处于测试阶段的提供商上 | +| **操作** | 已配置的提供商显示**管理配置**,可用的提供商显示**配置** | + +两个部分都设有搜索框,可按提供商名称和协议匹配,因此搜索 `oauth` 会将页面缩小到仅显示 OAuth 类提供商。 + +![Available providers](images/authorization_available.png) + +## 每个提供商仅有一份配置 + +身份提供商的设置在每个实例上、每个提供商只有一组值——一个 Okta 应用、一个 SAML 身份提供商、一个 LDAP 目录。卡片上也是这样体现的,没有“新增一个”的选项:要更改某个提供商的设置方式,您需要编辑已经存在的那份配置。 + +这正是授权连接器与[连接器库](/connectors/upstream/about/)的不同之处,在连接器库中,一个工具可以并列拥有多份配置。 + +## 三种状态及其含义 + +| 状态 | 含义 | 下一步操作 | +| --- | --- | --- | +| **Enabled** | 已配置且正在接受登录 | 无需操作 | +| **Disabled** | 已配置,但已关闭——其按钮不会出现在登录页面上 | 如需重新启用,请在其配置中重新开启 | +| **Not configured** | 受支持,但尚未填写任何内容 | 点击**配置**进行设置 | + +选择某个提供商会直接打开该提供商自身的设置表单,中间没有额外的提供商选择步骤。 + +## 受支持的提供商 + +| 提供商 | 协议 | 设置指南 | +| --- | --- | --- | +| Auth0 | OAuth 2.0 | [Auth0](/admin/sso/pro__auth0/) | +| GitHub Enterprise | OAuth 2.0 | [GitHub Enterprise](/admin/sso/pro__github_enterprise/) | +| GitLab | OAuth 2.0 | [GitLab](/admin/sso/pro__gitlab/) | +| Google | OAuth 2.0 | [Google](/admin/sso/pro__google/) | +| Keycloak | OAuth 2.0 | [KeyCloak](/admin/sso/pro__keycloak/) | +| LDAP | LDAP | [LDAP](/admin/sso/pro__ldap/) | +| Microsoft Entra ID | OAuth 2.0 | [Azure Active Directory](/admin/sso/pro__azure_ad/) | +| Okta | OAuth 2.0 | [Okta](/admin/sso/pro__okta/) | +| OpenID Connect | OpenID Connect | [OIDC](/admin/sso/pro__oidc/) | +| SAML | SAML 2.0 | [SAML](/admin/sso/pro__saml/) | + +该页面报告的是提供商配置的*状态*。它绝不会返回配置中的机密信息——客户端密钥、绑定密码和证书都不属于该页面背后的数据,也无法从中读取出来。 + +## 当某个提供商无法连接时 + +授权连接器告诉您已配置了什么,但不会显示登录失败的记录。这些记录保存在[诊断](/admin/diagnostics/pro__diagnostics/)中,SSO、SAML 和 LDAP 各自会报告自己的尝试记录以及被拒绝的原因——错误的断言签名、被拒绝的绑定、不匹配的属性等。这些记录属于实例级别,因此仅超级用户可见。 + +请始终保留至少一个使用用户名和密码登录的超级用户账户作为后备,并记住 `/login?force_login_form` 会在身份提供商出现故障时返回标准登录表单。两者都参见[单点登录](/admin/sso/)。 + +## 相关内容 + +* [单点登录](/admin/sso/)——各提供商的设置指南和登录设置 +* [诊断](/admin/diagnostics/pro__diagnostics/)——登录尝试失败的原因 +* [连接器](/connectors/upstream/about/)——本页面所参照的上游库 diff --git a/docs/content/admin/sso/PRO__azure_ad.it.md b/docs/content/admin/sso/PRO__azure_ad.it.md new file mode 100644 index 0000000000..26dfc51448 --- /dev/null +++ b/docs/content/admin/sso/PRO__azure_ad.it.md @@ -0,0 +1,58 @@ +--- +title: Azure Active Directory +description: Configura l'SSO di Azure AD e il mapping dei gruppi in DefectDojo Pro +weight: 5 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite Azure Active Directory (Azure AD), inclusa la sincronizzazione automatica dei gruppi utente. La versione open source di DefectDojo non include l'SSO — vedi [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Prerequisiti + +Completa i seguenti passaggi nel portale Azure prima di configurare DefectDojo: + +1. [Registra una nuova app](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) in Azure Active Directory. + +2. Annota i seguenti valori dall'app registrata: + - **Application (client) ID** + - **Directory (tenant) ID** + - In **Certificates & Secrets**, crea un nuovo **Client Secret** e annotane il valore + - **Application ID URI** + +3. In **Authentication > Redirect URIs**, aggiungi un URI di tipo **Web**: + `https://your-instance.cloud.defectdojo.com/complete/azuread-tenant-oauth2/` + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **Azure AD** e compila il modulo: + +- **Azure AD OAuth Key** — inserisci il tuo **Application (client) ID** +- **Azure AD OAuth Secret** — inserisci il tuo **Client Secret** +- **Azure AD Resource** — per impostazione predefinita è `https://graph.microsoft.com/`. È l'URI che DefectDojo utilizza per leggere informazioni aggiuntive (come i nomi dei gruppi) dalla [Microsoft Graph Web API](https://docs.azure.cn/en-us/entra/identity-platform/security-best-practices-for-app-registration#application-id-uri). Modificalo solo se i nomi dei tuoi gruppi sono memorizzati su una risorsa API diversa. +- **Azure AD Tenant ID** — inserisci il tuo **Directory (tenant) ID** +- **Azure AD Groups Filter** — inserisci facoltativamente una stringa regex per limitare quali Gruppi utente vengono importati (vedi [Mapping dei gruppi](#group-mapping) più sotto) + +Seleziona **Enable Azure AD OAuth** e invia il modulo. Un pulsante **Login With Azure AD** comparirà nella pagina di accesso. + +## Mapping dei gruppi + +Il mapping dei gruppi consente a DefectDojo di importare l'appartenenza ai [Gruppi utente](../../user_management/create_user_group/) da Azure AD. I Gruppi utente in DefectDojo regolano l'accesso a prodotti e tipi di prodotto tramite [RBAC](../../user_management/set_user_permissions/). + +Seleziona **Enable Azure AD OAuth Grouping** per attivare questa funzionalità. All'accesso, DefectDojo farà corrispondere i gruppi Azure AD dell'utente ai gruppi DefectDojo esistenti. Eventuali gruppi non trovati in DefectDojo verranno creati automaticamente. + +Per importare solo un sottoinsieme di gruppi, inserisci una regex nel campo **Azure AD Groups Filter**. Ad esempio: +- `^team-.*` — corrisponde a qualsiasi gruppo che inizia con `team-` +- `teamA|teamB|groupC` — corrisponde a gruppi specifici con nome + +### Configurare Azure AD per inviare i gruppi + +Il token di Azure AD deve essere configurato per includere gli ID dei gruppi. Senza questo, nel token non sarà presente alcuna informazione sui gruppi. + +Per configurarlo: +1. Aggiungi un [Group Claim](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims) nella configurazione del token di Azure AD. Se non sei sicuro di quale tipo di gruppo selezionare, scegli **All Groups**. +2. **Non** abilitare **Emit groups as role claims**. +3. Aggiorna le autorizzazioni API dell'applicazione includendo `GroupMember.Read.All` o `Group.Read.All`. `GroupMember.Read.All` è consigliato perché concede meno permessi. + +### Pulizia dei gruppi + +Se **Enable Azure AD OAuth Group Cleaning** è abilitato, i gruppi DefectDojo creati tramite la sincronizzazione con Azure AD verranno rimossi automaticamente quando non hanno più membri. Quando un utente viene rimosso da un gruppo in Azure AD, viene rimosso anche dal gruppo corrispondente in DefectDojo. diff --git a/docs/content/admin/sso/PRO__azure_ad.pt-br.md b/docs/content/admin/sso/PRO__azure_ad.pt-br.md new file mode 100644 index 0000000000..b6cd7fb39b --- /dev/null +++ b/docs/content/admin/sso/PRO__azure_ad.pt-br.md @@ -0,0 +1,78 @@ +--- +title: Azure Active Directory +description: Configure o SSO do Azure AD e o mapeamento de grupos no DefectDojo Pro +weight: 5 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via Azure Active Directory (Azure AD), incluindo sincronização +automática de User Group. O DefectDojo open-source não inclui SSO — consulte +[Usuários Autorizados](/admin/user_management/os__authorized_users/) para controle de acesso no open-source. + +## Pré-requisitos + +Conclua as etapas a seguir no portal do Azure antes de configurar o DefectDojo: + +1. [Registre uma nova aplicação](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) + no Azure Active Directory. + +2. Anote os seguintes valores da aplicação registrada: + - **Application (client) ID** + - **Directory (tenant) ID** + - Em **Certificates & Secrets**, crie um novo **Client Secret** e anote o valor + - **Application ID URI** + +3. Em **Authentication > Redirect URIs**, adicione uma URI do tipo **Web**: + `https://your-instance.cloud.defectdojo.com/complete/azuread-tenant-oauth2/` + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **Azure AD** e preencha o +formulário: + +- **Azure AD OAuth Key** — insira seu **Application (client) ID** +- **Azure AD OAuth Secret** — insira seu **Client Secret** +- **Azure AD Resource** — o padrão é `https://graph.microsoft.com/`. Esta é a URI que o DefectDojo usa para + ler informações adicionais (como nomes de grupos) da + [Microsoft Graph Web API](https://docs.azure.cn/en-us/entra/identity-platform/security-best-practices-for-app-registration#application-id-uri). + Altere isso apenas se os nomes dos seus grupos estiverem armazenados em outro recurso de API. +- **Azure AD Tenant ID** — insira seu **Directory (tenant) ID** +- **Azure AD Groups Filter** — opcionalmente, insira uma expressão regular para restringir quais User + Groups são importados (veja [Group Mapping](#group-mapping) abaixo) + +Marque **Enable Azure AD OAuth** e envie o formulário. Um botão **Login With Azure AD** aparecerá na página +de login. + +## Group Mapping + +O group mapping permite que o DefectDojo importe a associação a +[User Group](../../user_management/create_user_group/) do Azure AD. Os User Groups no DefectDojo controlam +o acesso a produtos e tipos de produto por meio do [RBAC](../../user_management/set_user_permissions/). + +Marque **Enable Azure AD OAuth Grouping** para ativar este recurso. No login, o DefectDojo vai corresponder +os grupos do Azure AD do usuário aos grupos já existentes no DefectDojo. Quaisquer grupos não encontrados no +DefectDojo serão criados automaticamente. + +Para importar apenas um subconjunto de grupos, insira uma expressão regular no campo **Azure AD Groups +Filter**. Por exemplo: +- `^team-.*` — corresponde a qualquer grupo que comece com `team-` +- `teamA|teamB|groupC` — corresponde a grupos específicos nomeados + +### Configurando o Azure AD para enviar grupos + +O token do Azure AD deve ser configurado para incluir IDs de grupo. Sem isso, nenhuma informação de grupo +estará presente no token. + +Para configurar isso: +1. Adicione um [Group Claim](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims) + na configuração do token do Azure AD. Se não tiver certeza de qual tipo de grupo selecionar, escolha + **All Groups**. +2. **Não** habilite **Emit groups as role claims**. +3. Atualize as permissões de API da aplicação para incluir `GroupMember.Read.All` ou `Group.Read.All`. + `GroupMember.Read.All` é recomendado, pois concede menos permissões. + +### Group Cleaning + +Se **Enable Azure AD OAuth Group Cleaning** estiver ativado, os grupos do DefectDojo criados pela +sincronização com o Azure AD serão removidos automaticamente quando não tiverem mais membros. Quando um +usuário é removido de um grupo no Azure AD, ele também é removido do grupo correspondente no DefectDojo. diff --git a/docs/content/admin/sso/PRO__azure_ad.zh-hans.md b/docs/content/admin/sso/PRO__azure_ad.zh-hans.md new file mode 100644 index 0000000000..6d2e078b99 --- /dev/null +++ b/docs/content/admin/sso/PRO__azure_ad.zh-hans.md @@ -0,0 +1,58 @@ +--- +title: Azure Active Directory +description: 在 DefectDojo Pro 中配置 Azure AD 单点登录和组映射 +weight: 5 +audience: pro +--- + +DefectDojo Pro 支持通过 Azure Active Directory(Azure AD)登录,包括自动的用户组同步。开源版 DefectDojo 不包含 SSO——开源版的访问控制请参见[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 前提条件 + +在配置 DefectDojo 之前,请先在 Azure 门户中完成以下步骤: + +1. 在 Azure Active Directory 中[注册一个新应用](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)。 + +2. 记录已注册应用中的以下值: + - **Application (client) ID** + - **Directory (tenant) ID** + - 在 **Certificates & Secrets** 下,创建一个新的 **Client Secret** 并记录其值 + - **Application ID URI** + +3. 在 **Authentication > Redirect URIs** 下,添加一个 **Web** 类型的 URI: + `https://your-instance.cloud.defectdojo.com/complete/azuread-tenant-oauth2/` + +## 配置 + +在 DefectDojo 中,前往**企业设置 > OAuth 设置**,选择 **Azure AD**,然后填写表单: + +- **Azure AD OAuth Key**——输入您的 **Application (client) ID** +- **Azure AD OAuth Secret**——输入您的 **Client Secret** +- **Azure AD Resource**——默认值为 `https://graph.microsoft.com/`。这是 DefectDojo 用来从 [Microsoft Graph Web API](https://docs.azure.cn/en-us/entra/identity-platform/security-best-practices-for-app-registration#application-id-uri) 读取附加信息(例如组名称)的 URI。仅当您的组名称存储在不同的 API 资源上时才需要更改此项。 +- **Azure AD Tenant ID**——输入您的 **Directory (tenant) ID** +- **Azure AD Groups Filter**——可选,输入一个正则表达式字符串以限制导入哪些用户组(见下方[组映射](#group-mapping)) + +勾选**启用 Azure AD OAuth**并提交表单。登录页面上会出现一个**使用 Azure AD 登录**按钮。 + +## 组映射 + +组映射允许 DefectDojo 从 Azure AD 导入[用户组](../../user_management/create_user_group/)成员关系。DefectDojo 中的用户组通过 [RBAC](../../user_management/set_user_permissions/) 管理产品和产品类型的访问权限。 + +勾选**启用 Azure AD OAuth 分组**以激活此功能。登录时,DefectDojo 会将用户的 Azure AD 组与 DefectDojo 中已有的组进行匹配。任何在 DefectDojo 中不存在的组都会被自动创建。 + +如需仅导入部分组,请在 **Azure AD Groups Filter** 字段中输入正则表达式。例如: +- `^team-.*`——匹配任何以 `team-` 开头的组 +- `teamA|teamB|groupC`——匹配特定的指定组 + +### 配置 Azure AD 以发送组信息 + +Azure AD 令牌必须配置为包含组 ID,否则令牌中不会出现任何组信息。 + +配置方法如下: +1. 在 Azure AD 令牌配置中添加一个[组声明(Group Claim)](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims)。如果不确定选择哪种组类型,请选择 **All Groups**。 +2. **不要**启用 **Emit groups as role claims**。 +3. 更新应用的 API 权限,加入 `GroupMember.Read.All` 或 `Group.Read.All`。建议使用 `GroupMember.Read.All`,因为它授予的权限更少。 + +### 组清理 + +如果启用了**启用 Azure AD OAuth 组清理**,通过 Azure AD 同步创建的 DefectDojo 组在没有任何剩余成员时会被自动移除。当某个用户在 Azure AD 中被移出某个组时,该用户也会从 DefectDojo 中对应的组中被移除。 diff --git a/docs/content/admin/sso/PRO__github_enterprise.it.md b/docs/content/admin/sso/PRO__github_enterprise.it.md new file mode 100644 index 0000000000..5dc6e7b50d --- /dev/null +++ b/docs/content/admin/sso/PRO__github_enterprise.it.md @@ -0,0 +1,32 @@ +--- +title: GitHub Enterprise +description: Configura l'SSO di GitHub Enterprise in DefectDojo Pro +weight: 7 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite GitHub Enterprise. La versione open source di DefectDojo non include l'SSO — vedi [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Prerequisiti + +Completa i seguenti passaggi in GitHub Enterprise prima di configurare DefectDojo: + +1. [Crea una nuova OAuth App](https://docs.github.com/en/enterprise-server/developers/apps/building-oauth-apps/creating-an-oauth-app) nel tuo GitHub Enterprise Server. + +2. Scegli un nome per l'applicazione, ad es. `DefectDojo`. + +3. Imposta il **Redirect URI**: + `https://your-instance.cloud.defectdojo.com/complete/github-enterprise/` + +4. Annota il **Client ID** e il **Client Secret** dall'app. + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **GitHub Enterprise** e compila il modulo: + +- **GitHub Enterprise OAuth Key** — inserisci il tuo **Client ID** +- **GitHub Enterprise OAuth Secret** — inserisci il tuo **Client Secret** +- **GitHub Enterprise URL** — inserisci l'URL GitHub della tua organizzazione, ad es. `https://github.yourcompany.com/` +- **GitHub Enterprise API URL** — inserisci l'URL API GitHub della tua organizzazione, ad es. `https://github.yourcompany.com/api/v3/` + +Seleziona **Enable GitHub Enterprise OAuth** e invia il modulo. Un pulsante **Login With GitHub** comparirà nella pagina di accesso. diff --git a/docs/content/admin/sso/PRO__github_enterprise.pt-br.md b/docs/content/admin/sso/PRO__github_enterprise.pt-br.md new file mode 100644 index 0000000000..f563d2e41e --- /dev/null +++ b/docs/content/admin/sso/PRO__github_enterprise.pt-br.md @@ -0,0 +1,39 @@ +--- +title: GitHub Enterprise +description: Configure o SSO do GitHub Enterprise no DefectDojo Pro +weight: 7 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via GitHub Enterprise. O DefectDojo open-source não inclui +SSO — consulte [Usuários Autorizados](/admin/user_management/os__authorized_users/) para controle de acesso +no open-source. + +## Pré-requisitos + +Conclua as etapas a seguir no GitHub Enterprise antes de configurar o DefectDojo: + +1. [Crie um novo OAuth App](https://docs.github.com/en/enterprise-server/developers/apps/building-oauth-apps/creating-an-oauth-app) + no seu GitHub Enterprise Server. + +2. Escolha um nome para a aplicação, por exemplo `DefectDojo`. + +3. Defina a **Redirect URI**: + `https://your-instance.cloud.defectdojo.com/complete/github-enterprise/` + +4. Anote o **Client ID** e o **Client Secret** da aplicação. + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **GitHub Enterprise** e preencha o +formulário: + +- **GitHub Enterprise OAuth Key** — insira seu **Client ID** +- **GitHub Enterprise OAuth Secret** — insira seu **Client Secret** +- **GitHub Enterprise URL** — insira a URL do GitHub da sua organização, por exemplo + `https://github.yourcompany.com/` +- **GitHub Enterprise API URL** — insira a URL da API do GitHub da sua organização, por exemplo + `https://github.yourcompany.com/api/v3/` + +Marque **Enable GitHub Enterprise OAuth** e envie o formulário. Um botão **Login With GitHub** aparecerá na +página de login. diff --git a/docs/content/admin/sso/PRO__github_enterprise.zh-hans.md b/docs/content/admin/sso/PRO__github_enterprise.zh-hans.md new file mode 100644 index 0000000000..6b14c0cd58 --- /dev/null +++ b/docs/content/admin/sso/PRO__github_enterprise.zh-hans.md @@ -0,0 +1,32 @@ +--- +title: GitHub Enterprise +description: 在 DefectDojo Pro 中配置 GitHub Enterprise 单点登录 +weight: 7 +audience: pro +--- + +DefectDojo Pro 支持通过 GitHub Enterprise 登录。开源版 DefectDojo 不包含 SSO——开源版的访问控制请参见[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 前提条件 + +在配置 DefectDojo 之前,请先在 GitHub Enterprise 中完成以下步骤: + +1. 在您的 GitHub Enterprise Server 中[创建一个新的 OAuth 应用](https://docs.github.com/en/enterprise-server/developers/apps/building-oauth-apps/creating-an-oauth-app)。 + +2. 为该应用选择一个名称,例如 `DefectDojo`。 + +3. 设置 **Redirect URI**: + `https://your-instance.cloud.defectdojo.com/complete/github-enterprise/` + +4. 记录该应用的 **Client ID** 和 **Client Secret**。 + +## 配置 + +在 DefectDojo 中,前往**企业设置 > OAuth 设置**,选择 **GitHub Enterprise**,然后填写表单: + +- **GitHub Enterprise OAuth Key**——输入您的 **Client ID** +- **GitHub Enterprise OAuth Secret**——输入您的 **Client Secret** +- **GitHub Enterprise URL**——输入您组织的 GitHub URL,例如 `https://github.yourcompany.com/` +- **GitHub Enterprise API URL**——输入您组织的 GitHub API URL,例如 `https://github.yourcompany.com/api/v3/` + +勾选**启用 GitHub Enterprise OAuth**并提交表单。登录页面上会出现一个**使用 GitHub 登录**按钮。 diff --git a/docs/content/admin/sso/PRO__gitlab.it.md b/docs/content/admin/sso/PRO__gitlab.it.md new file mode 100644 index 0000000000..47d140e475 --- /dev/null +++ b/docs/content/admin/sso/PRO__gitlab.it.md @@ -0,0 +1,32 @@ +--- +title: GitLab +description: Configura l'SSO di GitLab in DefectDojo Pro +weight: 9 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite GitLab. La versione open source di DefectDojo non include l'SSO — vedi [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Prerequisiti + +Completa i seguenti passaggi in GitLab prima di configurare DefectDojo: + +1. Vai alla pagina Applications del tuo profilo GitLab: + - GitLab.com: `https://gitlab.com/profile/applications` + - Self-hosted: `https://your-gitlab-host/profile/applications` + +2. Crea una nuova applicazione: + - **Name:** `DefectDojo` + - **Redirect URI:** `https://your-dojo-instance.cloud.defectdojo.com/complete/gitlab/` + +3. Annota l'**Application ID** e il **Secret** dell'applicazione. + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **GitLab** e compila il modulo: + +- **GitLab OAuth Key** — inserisci il tuo **Application ID** +- **GitLab OAuth Secret** — inserisci il tuo **Secret** +- **GitLab API URL** — inserisci l'URL di base della tua istanza GitLab, ad es. `https://gitlab.com` + +Seleziona **Enable GitLab OAuth** e invia il modulo. Un pulsante **Login With GitLab** comparirà nella pagina di accesso. diff --git a/docs/content/admin/sso/PRO__gitlab.pt-br.md b/docs/content/admin/sso/PRO__gitlab.pt-br.md new file mode 100644 index 0000000000..b19f9f7277 --- /dev/null +++ b/docs/content/admin/sso/PRO__gitlab.pt-br.md @@ -0,0 +1,34 @@ +--- +title: GitLab +description: Configure o SSO do GitLab no DefectDojo Pro +weight: 9 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via GitLab. O DefectDojo open-source não inclui SSO — consulte +[Usuários Autorizados](/admin/user_management/os__authorized_users/) para controle de acesso no open-source. + +## Pré-requisitos + +Conclua as etapas a seguir no GitLab antes de configurar o DefectDojo: + +1. Acesse a página Applications do seu perfil do GitLab: + - GitLab.com: `https://gitlab.com/profile/applications` + - Self-hosted: `https://your-gitlab-host/profile/applications` + +2. Crie uma nova aplicação: + - **Name:** `DefectDojo` + - **Redirect URI:** `https://your-dojo-instance.cloud.defectdojo.com/complete/gitlab/` + +3. Anote o **Application ID** e o **Secret** da aplicação. + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **GitLab** e preencha o formulário: + +- **GitLab OAuth Key** — insira seu **Application ID** +- **GitLab OAuth Secret** — insira seu **Secret** +- **GitLab API URL** — insira a URL base da sua instância do GitLab, por exemplo `https://gitlab.com` + +Marque **Enable GitLab OAuth** e envie o formulário. Um botão **Login With GitLab** aparecerá na página de +login. diff --git a/docs/content/admin/sso/PRO__gitlab.zh-hans.md b/docs/content/admin/sso/PRO__gitlab.zh-hans.md new file mode 100644 index 0000000000..45bc79f017 --- /dev/null +++ b/docs/content/admin/sso/PRO__gitlab.zh-hans.md @@ -0,0 +1,32 @@ +--- +title: GitLab +description: 在 DefectDojo Pro 中配置 GitLab 单点登录 +weight: 9 +audience: pro +--- + +DefectDojo Pro 支持通过 GitLab 登录。开源版 DefectDojo 不包含 SSO——开源版的访问控制请参见[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 前提条件 + +在配置 DefectDojo 之前,请先在 GitLab 中完成以下步骤: + +1. 前往您 GitLab 个人资料的应用页面: + - GitLab.com:`https://gitlab.com/profile/applications` + - 自托管:`https://your-gitlab-host/profile/applications` + +2. 创建一个新应用: + - **Name:** `DefectDojo` + - **Redirect URI:** `https://your-dojo-instance.cloud.defectdojo.com/complete/gitlab/` + +3. 记录该应用的 **Application ID** 和 **Secret**。 + +## 配置 + +在 DefectDojo 中,前往**企业设置 > OAuth 设置**,选择 **GitLab**,然后填写表单: + +- **GitLab OAuth Key**——输入您的 **Application ID** +- **GitLab OAuth Secret**——输入您的 **Secret** +- **GitLab API URL**——输入您 GitLab 实例的基础 URL,例如 `https://gitlab.com` + +勾选**启用 GitLab OAuth**并提交表单。登录页面上会出现一个**使用 GitLab 登录**按钮。 diff --git a/docs/content/admin/sso/PRO__google.it.md b/docs/content/admin/sso/PRO__google.it.md new file mode 100644 index 0000000000..a8a5722971 --- /dev/null +++ b/docs/content/admin/sso/PRO__google.it.md @@ -0,0 +1,38 @@ +--- +title: Google Auth +description: Configura l'OAuth di Google in DefectDojo Pro +weight: 11 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite account Google. I nuovi utenti vengono creati automaticamente al primo accesso se non esistono già. Gli utenti DefectDojo esistenti vengono associati agli account Google in base al nome utente (la parte prima della `@` nella loro email Google). La versione open source di DefectDojo non include l'SSO — vedi [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Prerequisiti + +Completa i seguenti passaggi nella Google Cloud Console prima di configurare DefectDojo: + +1. Accedi alla [Google Developers Console](https://console.developers.google.com). + +2. Vai su **Credentials > Create Credentials > OAuth Client ID**. + + ![immagine](images/google_1.png) + +3. Seleziona **Web Application** e assegna un nome descrittivo (ad es. `DefectDojo`). + +4. In **Authorized Redirect URIs**, aggiungi: + `https://your-instance.cloud.defectdojo.com/complete/google-oauth2/` + +5. Annota il **Client ID** e la **Client Secret Key**. + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **Google** e compila il modulo: + +- **Google OAuth Key** — inserisci il tuo **Client ID** +- **Google OAuth Secret** — inserisci la tua **Client Secret Key** +- **Whitelisted Domains** — inserisci il dominio della tua organizzazione (ad es. `yourcompany.com`) per consentire l'accesso a qualsiasi utente con quel dominio +- **Whitelisted E-mail Addresses** — in alternativa, inserisci indirizzi email specifici da consentire (ad es. `user1@yourcompany.com, user2@yourcompany.com`) + +Devi impostare almeno un dominio o indirizzo email in whitelist, altrimenti nessun utente potrà accedere tramite Google. + +Seleziona **Enable Google OAuth** e invia il modulo. Un pulsante **Login With Google** comparirà nella pagina di accesso. diff --git a/docs/content/admin/sso/PRO__google.pt-br.md b/docs/content/admin/sso/PRO__google.pt-br.md new file mode 100644 index 0000000000..f06179a060 --- /dev/null +++ b/docs/content/admin/sso/PRO__google.pt-br.md @@ -0,0 +1,47 @@ +--- +title: Google Auth +description: Configure o OAuth do Google no DefectDojo Pro +weight: 11 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via contas do Google. Novos usuários são criados +automaticamente no primeiro login, caso ainda não existam. Usuários já existentes no DefectDojo são +correspondidos a contas do Google pelo nome de usuário (a parte antes do `@` no e-mail do Google). O +DefectDojo open-source não inclui SSO — consulte +[Usuários Autorizados](/admin/user_management/os__authorized_users/) para controle de acesso no open-source. + +## Pré-requisitos + +Conclua as etapas a seguir no Google Cloud Console antes de configurar o DefectDojo: + +1. Faça login no [Google Developers Console](https://console.developers.google.com). + +2. Acesse **Credentials > Create Credentials > OAuth Client ID**. + + ![image](images/google_1.png) + +3. Selecione **Web Application** e dê a ela um nome descritivo (por exemplo, `DefectDojo`). + +4. Em **Authorized Redirect URIs**, adicione: + `https://your-instance.cloud.defectdojo.com/complete/google-oauth2/` + +5. Anote o **Client ID** e a **Client Secret Key**. + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **Google** e preencha o +formulário: + +- **Google OAuth Key** — insira seu **Client ID** +- **Google OAuth Secret** — insira sua **Client Secret Key** +- **Whitelisted Domains** — insira o domínio da sua organização (por exemplo, `yourcompany.com`) para + permitir que qualquer usuário com esse domínio faça login +- **Whitelisted E-mail Addresses** — alternativamente, insira endereços de e-mail específicos para permitir + (por exemplo, `user1@yourcompany.com, user2@yourcompany.com`) + +É necessário definir pelo menos um domínio ou endereço de e-mail na lista de permissões, caso contrário +nenhum usuário conseguirá fazer login via Google. + +Marque **Enable Google OAuth** e envie o formulário. Um botão **Login With Google** aparecerá na página de +login. diff --git a/docs/content/admin/sso/PRO__google.zh-hans.md b/docs/content/admin/sso/PRO__google.zh-hans.md new file mode 100644 index 0000000000..d52e508e07 --- /dev/null +++ b/docs/content/admin/sso/PRO__google.zh-hans.md @@ -0,0 +1,38 @@ +--- +title: Google 身份验证 +description: 在 DefectDojo Pro 中配置 Google OAuth +weight: 11 +audience: pro +--- + +DefectDojo Pro 支持通过 Google 账户登录。首次登录时,如果新用户尚不存在,会自动创建。现有的 DefectDojo 用户会通过用户名(即 Google 邮箱中 `@` 之前的部分)与 Google 账户进行匹配。开源版 DefectDojo 不包含 SSO——开源版的访问控制请参见[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 前提条件 + +在配置 DefectDojo 之前,请先在 Google Cloud Console 中完成以下步骤: + +1. 登录 [Google Developers Console](https://console.developers.google.com)。 + +2. 前往**凭据 > 创建凭据 > OAuth 客户端 ID**。 + + ![image](images/google_1.png) + +3. 选择 **Web Application**,并为其设置一个描述性名称(例如 `DefectDojo`)。 + +4. 在**授权重定向 URI**下,添加: + `https://your-instance.cloud.defectdojo.com/complete/google-oauth2/` + +5. 记录 **Client ID** 和 **Client Secret Key**。 + +## 配置 + +在 DefectDojo 中,前往**企业设置 > OAuth 设置**,选择 **Google**,然后填写表单: + +- **Google OAuth Key**——输入您的 **Client ID** +- **Google OAuth Secret**——输入您的 **Client Secret Key** +- **Whitelisted Domains**——输入您组织的域名(例如 `yourcompany.com`),以允许该域下的任何用户登录 +- **Whitelisted E-mail Addresses**——或者,输入允许登录的特定邮箱地址(例如 `user1@yourcompany.com, user2@yourcompany.com`) + +您必须至少设置一个白名单域名或邮箱地址,否则将没有任何用户能够通过 Google 登录。 + +勾选**启用 Google OAuth**并提交表单。登录页面上会出现一个**使用 Google 登录**按钮。 diff --git a/docs/content/admin/sso/PRO__keycloak.it.md b/docs/content/admin/sso/PRO__keycloak.it.md new file mode 100644 index 0000000000..9eca8bf370 --- /dev/null +++ b/docs/content/admin/sso/PRO__keycloak.it.md @@ -0,0 +1,53 @@ +--- +title: KeyCloak +description: Configura l'SSO di KeyCloak in DefectDojo Pro +weight: 13 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite KeyCloak. La versione open source di DefectDojo non include l'SSO — vedi [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +Questa guida presuppone che tu abbia già configurato un Realm KeyCloak. In caso contrario, consulta la [documentazione di KeyCloak](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html). + +## Prerequisiti + +Completa i seguenti passaggi nel tuo realm KeyCloak prima di configurare DefectDojo: + +1. Aggiungi un nuovo client di tipo `openid-connect`. Annota il client ID. + +2. Nelle impostazioni del client: + - Imposta **Access Type** su `confidential` + - In **Valid Redirect URIs**, aggiungi il tuo URL DefectDojo, ad es. `https://yourorganization.cloud.defectdojo.com` oppure `https://your-dojo-host/*` + - In **Web Origins**, aggiungi lo stesso URL (oppure `+`) + - In **Fine Grained OpenID Connect Configuration**: + - Imposta **User Info Signed Response Algorithm** su `RS256` + - Imposta **Request Object Signature Algorithm** su `RS256` + - Salva le impostazioni. + +3. In **Scope**, imposta **Full Scope Allowed** su `off`. + +4. In **Mappers**, aggiungi un mapper personalizzato: + - **Name:** `aud` + - **Mapper Type:** `audience` + - **Included Audience:** seleziona il tuo client ID + - **Add ID to Token:** `off` + - **Add Access to Token:** `on` + +5. In **Credentials**, copia il **Secret**. + +6. In **Realm Settings > Keys**, copia la **Public Key** (chiave di firma). + +7. In **Realm Settings > General > Endpoints**, apri la configurazione dell'endpoint OpenID e copia gli URL degli endpoint **Authorization** e **Token**. + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **KeyCloak** e compila il modulo: + +- **KeyCloak OAuth Key** — inserisci il nome del tuo client (dal passaggio 1) +- **KeyCloak OAuth Secret** — inserisci il secret delle credenziali del client (dal passaggio 5) +- **KeyCloak Public Key** — inserisci la Public Key dalle impostazioni del tuo realm (dal passaggio 6) +- **KeyCloak Resource** — inserisci l'URL dell'Authorization Endpoint (dal passaggio 7) +- **KeyCloak Group Limiter** — inserisci l'URL del Token Endpoint (dal passaggio 7) +- **KeyCloak OAuth Login Button Text** — scegli il testo per il pulsante di accesso di DefectDojo + +Seleziona **Enable KeyCloak OAuth** e invia il modulo. Nella pagina di accesso comparirà un pulsante di login con il testo che hai configurato. diff --git a/docs/content/admin/sso/PRO__keycloak.pt-br.md b/docs/content/admin/sso/PRO__keycloak.pt-br.md new file mode 100644 index 0000000000..0f3d2ee140 --- /dev/null +++ b/docs/content/admin/sso/PRO__keycloak.pt-br.md @@ -0,0 +1,60 @@ +--- +title: KeyCloak +description: Configure o SSO do KeyCloak no DefectDojo Pro +weight: 13 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via KeyCloak. O DefectDojo open-source não inclui SSO — +consulte [Usuários Autorizados](/admin/user_management/os__authorized_users/) para controle de acesso no +open-source. + +Este guia pressupõe que você já tenha um Realm do KeyCloak configurado. Caso contrário, consulte a +[documentação do KeyCloak](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html). + +## Pré-requisitos + +Conclua as etapas a seguir no seu realm do KeyCloak antes de configurar o DefectDojo: + +1. Adicione um novo client com o tipo `openid-connect`. Anote o client ID. + +2. Nas configurações do client: + - Defina **Access Type** como `confidential` + - Em **Valid Redirect URIs**, adicione a URL do seu DefectDojo, por exemplo + `https://yourorganization.cloud.defectdojo.com` ou `https://your-dojo-host/*` + - Em **Web Origins**, adicione a mesma URL (ou `+`) + - Em **Fine Grained OpenID Connect Configuration**: + - Defina **User Info Signed Response Algorithm** como `RS256` + - Defina **Request Object Signature Algorithm** como `RS256` + - Salve as configurações. + +3. Em **Scope**, defina **Full Scope Allowed** como `off`. + +4. Em **Mappers**, adicione um mapper personalizado: + - **Name:** `aud` + - **Mapper Type:** `audience` + - **Included Audience:** selecione o seu client ID + - **Add ID to Token:** `off` + - **Add Access to Token:** `on` + +5. Em **Credentials**, copie o **Secret**. + +6. Em **Realm Settings > Keys**, copie a **Public Key** (chave de assinatura). + +7. Em **Realm Settings > General > Endpoints**, abra a configuração de endpoint do OpenID e copie as URLs + de endpoint **Authorization** e **Token**. + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **KeyCloak** e preencha o +formulário: + +- **KeyCloak OAuth Key** — insira o nome do seu client (da etapa 1) +- **KeyCloak OAuth Secret** — insira o secret de credenciais do seu client (da etapa 5) +- **KeyCloak Public Key** — insira a Public Key das configurações do seu realm (da etapa 6) +- **KeyCloak Resource** — insira a URL do Authorization Endpoint (da etapa 7) +- **KeyCloak Group Limiter** — insira a URL do Token Endpoint (da etapa 7) +- **KeyCloak OAuth Login Button Text** — escolha o texto do botão de login do DefectDojo + +Marque **Enable KeyCloak OAuth** e envie o formulário. Um botão de login aparecerá na página de login com o +texto que você configurou. diff --git a/docs/content/admin/sso/PRO__keycloak.zh-hans.md b/docs/content/admin/sso/PRO__keycloak.zh-hans.md new file mode 100644 index 0000000000..abdd55a319 --- /dev/null +++ b/docs/content/admin/sso/PRO__keycloak.zh-hans.md @@ -0,0 +1,53 @@ +--- +title: KeyCloak +description: 在 DefectDojo Pro 中配置 KeyCloak 单点登录 +weight: 13 +audience: pro +--- + +DefectDojo Pro 支持通过 KeyCloak 登录。开源版 DefectDojo 不包含 SSO——开源版的访问控制请参见[已授权用户](/admin/user_management/os__authorized_users/)。 + +本指南假定您已经配置好了一个 KeyCloak Realm。如果尚未配置,请参见 [KeyCloak 文档](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html)。 + +## 前提条件 + +在配置 DefectDojo 之前,请先在您的 KeyCloak realm 中完成以下步骤: + +1. 添加一个类型为 `openid-connect` 的新客户端。记录该客户端 ID。 + +2. 在客户端设置中: + - 将 **Access Type** 设置为 `confidential` + - 在 **Valid Redirect URIs** 下,添加您的 DefectDojo URL,例如 `https://yourorganization.cloud.defectdojo.com` 或 `https://your-dojo-host/*` + - 在 **Web Origins** 下,添加相同的 URL(或 `+`) + - 在 **Fine Grained OpenID Connect Configuration** 下: + - 将 **User Info Signed Response Algorithm** 设置为 `RS256` + - 将 **Request Object Signature Algorithm** 设置为 `RS256` + - 保存设置。 + +3. 在 **Scope** 下,将 **Full Scope Allowed** 设置为 `off`。 + +4. 在 **Mappers** 下,添加一个自定义映射器: + - **Name:** `aud` + - **Mapper Type:** `audience` + - **Included Audience:** 选择您的客户端 ID + - **Add ID to Token:** `off` + - **Add Access to Token:** `on` + +5. 在 **Credentials** 下,复制 **Secret**。 + +6. 在 **Realm Settings > Keys** 中,复制 **Public Key**(签名密钥)。 + +7. 在 **Realm Settings > General > Endpoints** 中,打开 OpenID 端点配置并复制 **Authorization** 和 **Token** 端点 URL。 + +## 配置 + +在 DefectDojo 中,前往**企业设置 > OAuth 设置**,选择 **KeyCloak**,然后填写表单: + +- **KeyCloak OAuth Key**——输入您的客户端名称(来自步骤 1) +- **KeyCloak OAuth Secret**——输入您的客户端凭据密钥(来自步骤 5) +- **KeyCloak Public Key**——输入来自您 realm 设置的 Public Key(来自步骤 6) +- **KeyCloak Resource**——输入 Authorization Endpoint URL(来自步骤 7) +- **KeyCloak Group Limiter**——输入 Token Endpoint URL(来自步骤 7) +- **KeyCloak OAuth Login Button Text**——为 DefectDojo 登录按钮选择显示文字 + +勾选**启用 KeyCloak OAuth**并提交表单。登录页面上会出现一个带有您所配置文字的登录按钮。 diff --git a/docs/content/admin/sso/PRO__ldap.it.md b/docs/content/admin/sso/PRO__ldap.it.md new file mode 100644 index 0000000000..47256b3a02 --- /dev/null +++ b/docs/content/admin/sso/PRO__ldap.it.md @@ -0,0 +1,108 @@ +--- +title: Autenticazione LDAP +description: Configura l'autenticazione LDAP in DefectDojo Pro +weight: 20 +audience: pro +aliases: +- /it/en/open_source/ldap-authentication +--- + +DefectDojo Pro supporta l'autenticazione LDAP dall'interfaccia **Enterprise Settings** — non sono necessarie immagini Docker +personalizzate né file di configurazione. + +A differenza degli altri provider di questa pagina, LDAP non è un flusso basato su redirect. Gli utenti accedono +con il modulo standard di nome utente e password di DefectDojo, e le loro credenziali vengono verificate rispetto +alla tua directory. Non c'è alcun pulsante di accesso aggiuntivo. + +## Configurazione + +Apri **Enterprise Settings > LDAP Settings**. + +![immagine](images/sso_ldap_settings.png) + +1. **Server URI** — la directory a cui connettersi, ad es. `ldaps://ldap.example.com:636`. + Preferisci `ldaps://`. Se devi usare `ldap://` semplice, abilita **Use StartTLS** più sotto in modo che la + connessione venga aggiornata prima dell'invio delle credenziali. +2. **Bind DN** — il distinguished name dell'account di servizio usato per cercare gli utenti. + Lascia vuoto per un bind anonimo. +3. **Bind Password** — la password per quell'account di servizio. Il valore memorizzato non viene mai + restituito al browser; lascia il campo vuoto per mantenere la password già salvata. +4. **User Search Base** — il DN sotto cui cercare le voci utente, ad es. + `ou=people,dc=example,dc=com`. +5. **User Search Filter** — il filtro usato per individuare l'utente. **Deve** contenere il + segnaposto letterale `%(user)s`, che viene sostituito con il nome utente inviato. Valori comuni + sono `(uid=%(user)s)` per OpenLDAP e `(sAMAccountName=%(user)s)` per Active + Directory. +6. **User Attribute Mapping** — vedi sotto. +7. Seleziona **Enable LDAP** per attivarlo. + +Usa **Validate Config** per verificare le impostazioni senza salvarle. Riporta la completezza delle impostazioni, +se il server è raggiungibile, se il bind ha successo, se le basi di ricerca si risolvono e se il mapping degli +attributi sembra utilizzabile. + +## User Attribute Mapping + +Ogni riga associa un **LDAP Attribute** al **DefectDojo Field** che deve popolare. Usa +**Add Attribute Mapping** per righe aggiuntive e l'icona del cestino per rimuoverne una. + +![immagine](images/sso_ldap_attribute_mapping.png) + +- **LDAP Attribute** è testo libero e deve corrispondere all'attributo effettivamente + restituito dalla tua directory — ad esempio `uid`, `givenName`, `sn`, `mail` su OpenLDAP, oppure + `sAMAccountName`, `givenName`, `sn`, `mail` su Active Directory. +- **DefectDojo Field** viene scelto da un elenco: **Username**, **First Name**, **Last Name** e + **Email**. +- È fortemente consigliato mappare un attributo su **Email**: DefectDojo usa l'indirizzo + email per le notifiche. +- Lo stesso attributo può alimentare più di un campo. Ogni campo DefectDojo può essere + mappato da un solo attributo. +- Senza alcun mapping, gli account vengono creati senza nome o indirizzo email. + +**Always Update User** controlla quando viene applicato il mapping. Se abilitato (impostazione predefinita), gli +attributi mappati vengono aggiornati dalla directory a ogni accesso, così una modifica di nome o email +in LDAP raggiunge DefectDojo. Se disabilitato, vengono applicati solo alla prima +creazione dell'account. + +## Mapping dei gruppi + +DefectDojo può replicare i gruppi LDAP di un utente nei gruppi DefectDojo all'accesso. Seleziona **Enable +Group Mapping** per visualizzare le impostazioni. + +![immagine](images/sso_ldap_group_mapping.png) + +- **Group Search Base** — il DN sotto cui cercare le voci di gruppo, ad es. + `ou=groups,dc=example,dc=com`. Obbligatorio quando il mapping dei gruppi è abilitato. +- **Group Type** — come la tua directory modella l'appartenenza. Scegli **groupOfNames** per + OpenLDAP e Active Directory, **groupOfUniqueNames**, oppure **posixGroup**. +- **Group Limiter Regex Expression** — vengono replicati solo i gruppi il cui nome corrisponde a questa + espressione. Usa `.*` per consentirli tutti, oppure un prefisso come `^dd-` per replicare solo i gruppi che + intendi far gestire a DefectDojo. + +I gruppi vengono creati al primo utilizzo se non esistono già. Un gruppo appena creato non ha +permessi finché un Superuser non li configura — vedi +[Gruppi utente](../../user_management/create_user_group/). + +## Opzioni aggiuntive + +* **Use StartTLS** — aggiorna a TLS una connessione `ldap://` semplice prima del bind. Non è necessario + quando l'URI è già `ldaps://`. +* **Always Update User** — aggiorna gli attributi mappati dalla directory a ogni accesso. + +## Risoluzione dei problemi + +Esegui prima **Validate Config** — di solito indica direttamente il problema. Oltre a questo: + +**Ogni accesso fallisce, ma la directory è raggiungibile.** Controlla che **User Search Filter** +contenga `%(user)s` e che l'attributo al suo interno corrisponda a quanto digitano effettivamente gli utenti. Un +filtro del tipo `(uid=%(user)s)` non corrisponderà mai se i tuoi utenti accedono con uno +`sAMAccountName` di Active Directory. + +**Gli accessi hanno successo ma gli account non hanno nome o email.** **User Attribute Mapping** è +vuoto, oppure i nomi degli attributi LDAP a sinistra non corrispondono a quanto restituisce la tua directory. + +**Un nome è cambiato in LDAP ma non in DefectDojo.** **Always Update User** è disabilitato, quindi il +mapping è stato applicato solo alla creazione dell'account. + +**I tentativi di accesso si bloccano o sono lenti.** Connessioni e ricerche sono limitate da un timeout, quindi +una directory irraggiungibile fallisce anziché bloccarsi indefinitamente. Controlla **Server Reachability** +in **Validate Config** e verifica che la porta sia aperta dall'host DefectDojo. diff --git a/docs/content/admin/sso/PRO__ldap.pt-br.md b/docs/content/admin/sso/PRO__ldap.pt-br.md new file mode 100644 index 0000000000..4f1f232bbc --- /dev/null +++ b/docs/content/admin/sso/PRO__ldap.pt-br.md @@ -0,0 +1,107 @@ +--- +title: Autenticação LDAP +description: Configure a autenticação LDAP no DefectDojo Pro +weight: 20 +audience: pro +aliases: +- /pt-br/en/open_source/ldap-authentication +--- + +O DefectDojo Pro oferece suporte a autenticação LDAP diretamente pela interface **Enterprise +Settings** — não são necessárias imagens Docker personalizadas nem arquivos de configuração. + +Diferentemente dos outros provedores nesta página, o LDAP não é um fluxo baseado em redirecionamento. Os +usuários fazem login com o formulário padrão de nome de usuário e senha do DefectDojo, e suas credenciais +são verificadas no seu diretório. Não há um botão de login extra. + +## Configuração + +Abra **Enterprise Settings > LDAP Settings**. + +![image](images/sso_ldap_settings.png) + +1. **Server URI** — o diretório ao qual se conectar, por exemplo `ldaps://ldap.example.com:636`. + Prefira `ldaps://`. Se for necessário usar `ldap://` simples, habilite **Use StartTLS** abaixo para que + a conexão seja atualizada antes do envio das credenciais. +2. **Bind DN** — o distinguished name da conta de serviço usada para pesquisar usuários. + Deixe em branco para um bind anônimo. +3. **Bind Password** — a senha dessa conta de serviço. O valor armazenado nunca é + retornado ao navegador; deixe o campo em branco para manter a senha que você já salvou. +4. **User Search Base** — o DN sob o qual pesquisar as entradas de usuário, por exemplo + `ou=people,dc=example,dc=com`. +5. **User Search Filter** — o filtro usado para localizar o usuário. Ele **deve** conter o + placeholder literal `%(user)s`, que é substituído pelo nome de usuário enviado. Valores + comuns são `(uid=%(user)s)` para OpenLDAP e `(sAMAccountName=%(user)s)` para Active + Directory. +6. **User Attribute Mapping** — veja abaixo. +7. Marque **Enable LDAP** para ativá-lo. + +Use **Validate Config** para verificar as configurações sem salvá-las. Ele reporta a integridade das +configurações, se o servidor está acessível, se o bind é bem-sucedido, se as bases de pesquisa são +resolvidas, e se o mapeamento de atributos parece utilizável. + +## User Attribute Mapping + +Cada linha mapeia um **LDAP Attribute** para o **DefectDojo Field** que ele deve preencher. Use +**Add Attribute Mapping** para adicionar linhas e o ícone de lixeira para remover uma. + +![image](images/sso_ldap_attribute_mapping.png) + +- **LDAP Attribute** é texto livre e deve corresponder ao atributo que o seu diretório realmente + retorna — por exemplo `uid`, `givenName`, `sn`, `mail` no OpenLDAP, ou `sAMAccountName`, + `givenName`, `sn`, `mail` no Active Directory. +- **DefectDojo Field** é escolhido a partir de uma lista: **Username**, **First Name**, **Last Name** e + **Email**. +- Mapear um atributo para **Email** é fortemente recomendado: o DefectDojo usa o endereço de e-mail para + notificações. +- O mesmo atributo pode alimentar mais de um campo. Cada campo do DefectDojo pode ser mapeado a partir de + apenas um atributo. +- Sem nenhum mapeamento, as contas são criadas sem nome ou endereço de e-mail. + +**Always Update User** controla quando o mapeamento é aplicado. Quando habilitado (o padrão), os atributos +mapeados são atualizados a partir do diretório a cada login, de modo que uma alteração de nome ou e-mail no +LDAP chega ao DefectDojo. Quando desabilitado, eles só são aplicados quando a conta é criada pela primeira +vez. + +## Group Mapping + +O DefectDojo pode espelhar os grupos LDAP de um usuário em grupos do DefectDojo no login. Marque +**Enable Group Mapping** para revelar as configurações. + +![image](images/sso_ldap_group_mapping.png) + +- **Group Search Base** — o DN sob o qual pesquisar as entradas de grupo, por exemplo + `ou=groups,dc=example,dc=com`. Obrigatório quando o group mapping está habilitado. +- **Group Type** — como o seu diretório modela a associação. Escolha **groupOfNames** para OpenLDAP e + Active Directory, **groupOfUniqueNames**, ou **posixGroup**. +- **Group Limiter Regex Expression** — apenas os grupos cujo nome corresponde a esta expressão são + espelhados. Use `.*` para permitir todos, ou um prefixo como `^dd-` para espelhar apenas os grupos que + você pretende que o DefectDojo gerencie. + +Os grupos são criados no primeiro uso, caso ainda não existam. Um grupo recém-criado não tem permissões até +que um Superuser as configure — veja [User Groups](../../user_management/create_user_group/). + +## Opções adicionais + +* **Use StartTLS** — atualiza uma conexão `ldap://` simples para TLS antes do bind. Não é necessário quando + a URI já é `ldaps://`. +* **Always Update User** — atualiza os atributos mapeados a partir do diretório a cada login. + +## Solução de problemas + +Execute **Validate Config** primeiro — geralmente ele indica o problema diretamente. Além disso: + +**Todo login falha, mas o diretório está acessível.** Verifique se o **User Search Filter** contém +`%(user)s` e se o atributo nele corresponde ao que os usuários realmente digitam. Um filtro +`(uid=%(user)s)` nunca vai corresponder se os seus usuários fizerem login com um `sAMAccountName` do Active +Directory. + +**Os logins são bem-sucedidos, mas as contas não têm nome ou e-mail.** O **User Attribute Mapping** está +vazio, ou os nomes de atributo LDAP à esquerda não correspondem ao que o seu diretório retorna. + +**Um nome mudou no LDAP, mas não no DefectDojo.** **Always Update User** está desabilitado, portanto o +mapeamento só foi aplicado quando a conta foi criada. + +**As tentativas de login travam ou ficam lentas.** As conexões e pesquisas são limitadas por um timeout, de +modo que um diretório inacessível falha em vez de bloquear indefinidamente. Verifique **Server +Reachability** em **Validate Config** e confirme se a porta está aberta a partir do host do DefectDojo. diff --git a/docs/content/admin/sso/PRO__ldap.zh-hans.md b/docs/content/admin/sso/PRO__ldap.zh-hans.md new file mode 100644 index 0000000000..285641ada6 --- /dev/null +++ b/docs/content/admin/sso/PRO__ldap.zh-hans.md @@ -0,0 +1,72 @@ +--- +title: LDAP 身份验证 +description: 在 DefectDojo Pro 中配置 LDAP 身份验证 +weight: 20 +audience: pro +aliases: +- /zh-hans/en/open_source/ldap-authentication +--- + +DefectDojo Pro 支持从**企业设置**界面配置 LDAP 身份验证——无需自定义 Docker 镜像或配置文件。 + +与本页面上的其他提供商不同,LDAP 不是基于重定向的流程。用户使用标准的 DefectDojo 用户名和密码表单登录,其凭据会与您的目录进行比对。没有额外的登录按钮。 + +## 配置 + +打开**企业设置 > LDAP 设置**。 + +![image](images/sso_ldap_settings.png) + +1. **Server URI**——要连接的目录,例如 `ldaps://ldap.example.com:636`。 + 建议使用 `ldaps://`。如果必须使用明文的 `ldap://`,请在下方启用 **Use StartTLS**,以便在发送凭据之前先升级连接。 +2. **Bind DN**——用于搜索用户的服务账户的可分辨名称。留空表示匿名绑定。 +3. **Bind Password**——该服务账户的密码。已保存的值不会返回到浏览器;若要保留您已保存的密码,请将此字段留空。 +4. **User Search Base**——搜索用户条目时所在的起始 DN,例如 `ou=people,dc=example,dc=com`。 +5. **User Search Filter**——用于定位用户的过滤器。它**必须**包含字面量占位符 `%(user)s`,该占位符会被替换为提交的用户名。常见取值为 OpenLDAP 的 `(uid=%(user)s)` 和 Active Directory 的 `(sAMAccountName=%(user)s)`。 +6. **User Attribute Mapping**——见下文。 +7. 勾选**启用 LDAP** 以激活它。 + +使用**验证配置**可以在不保存设置的情况下进行检查。它会报告设置的完整性、服务器是否可达、绑定是否成功、搜索基是否能够解析,以及属性映射是否看起来可用。 + +## 用户属性映射 + +每一行将一个 **LDAP 属性**映射到它应填充的 **DefectDojo 字段**。使用**添加属性映射**可添加更多行,使用垃圾桶图标可删除某一行。 + +![image](images/sso_ldap_attribute_mapping.png) + +- **LDAP 属性**是自由文本,必须与您目录实际返回的属性一致——例如 OpenLDAP 上的 `uid`、`givenName`、`sn`、`mail`,或 Active Directory 上的 `sAMAccountName`、`givenName`、`sn`、`mail`。 +- **DefectDojo 字段**从列表中选择:**用户名**、**名字**、**姓氏**和**电子邮箱**。 +- 强烈建议将某个属性映射到**电子邮箱**:DefectDojo 会使用该邮箱地址发送通知。 +- 同一个属性可以同时提供给多个字段使用。但每个 DefectDojo 字段只能来自一个属性的映射。 +- 完全不设置映射时,创建的账户将没有姓名或邮箱地址。 + +**Always Update User** 控制映射的应用时机。启用时(默认设置),映射的属性会在每次登录时从目录中刷新,因此 LDAP 中的姓名或邮箱变更会同步到 DefectDojo。禁用时,这些属性仅在账户首次创建时应用一次。 + +## 组映射 + +DefectDojo 可以在登录时将用户的 LDAP 组映射为 DefectDojo 组。勾选**启用组映射**以显示相关设置。 + +![image](images/sso_ldap_group_mapping.png) + +- **Group Search Base**——搜索组条目时所在的起始 DN,例如 `ou=groups,dc=example,dc=com`。启用组映射时为必填项。 +- **Group Type**——您目录建模成员关系的方式。OpenLDAP 和 Active Directory 请选择 **groupOfNames**,也可选择 **groupOfUniqueNames** 或 **posixGroup**。 +- **Group Limiter Regex Expression**——只有名称匹配该表达式的组才会被映射。使用 `.*` 可允许全部,或使用类似 `^dd-` 的前缀,只映射您希望由 DefectDojo 管理的组。 + +组在首次使用时如果尚不存在会被创建。新创建的组在超级用户为其配置权限之前不具备任何权限——参见[用户组](../../user_management/create_user_group/)。 + +## 其他选项 + +* **Use StartTLS**——在绑定之前将明文的 `ldap://` 连接升级为 TLS。如果 URI 已经是 `ldaps://`,则无需此项。 +* **Always Update User**——在每次登录时从目录刷新映射的属性。 + +## 故障排查 + +请先运行**验证配置**——它通常会直接指出问题所在。除此之外: + +**所有登录都失败,但目录可以访问。** 检查 **User Search Filter** 是否包含 `%(user)s`,以及其中的属性是否与用户实际输入的内容一致。如果您的用户是用 Active Directory 的 `sAMAccountName` 登录,那么 `(uid=%(user)s)` 这样的过滤器将永远无法匹配。 + +**登录成功,但账户没有姓名或邮箱。** **User Attribute Mapping** 为空,或者左侧的 LDAP 属性名称与您目录实际返回的内容不匹配。 + +**LDAP 中的姓名已更改,但 DefectDojo 中没有变化。** **Always Update User** 已禁用,因此映射只在账户创建时应用过一次。 + +**登录尝试挂起或很慢。** 连接和搜索都受超时限制,因此无法访问的目录会直接失败,而不会无限期阻塞。请在**验证配置**中检查**服务器可达性**,并确认端口从 DefectDojo 主机可以访问。 diff --git a/docs/content/admin/sso/PRO__oidc.it.md b/docs/content/admin/sso/PRO__oidc.it.md new file mode 100644 index 0000000000..24fc8805ae --- /dev/null +++ b/docs/content/admin/sso/PRO__oidc.it.md @@ -0,0 +1,62 @@ +--- +title: OIDC +description: Configura il Single Sign-On OpenID Connect (OIDC) in DefectDojo Pro +weight: 17 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite un provider OpenID Connect (OIDC) generico. DefectDojo open source non include il SSO — consulta [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OIDC Settings**. + +![image](images/oidc_pro.png) + +Compila il modulo: + +1. **Endpoint** — l'URL di base del tuo provider OIDC. Non includere `/.well-known/openid-configuration`. +2. **Client ID** — il tuo client ID OIDC. +3. **Client Secret** — il tuo client secret OIDC. +4. Facoltativamente configura **Claim Mapping** e **Group Mapping** — vedi sotto. +5. Seleziona **Enable OIDC**. + +Invia il modulo. Nella pagina di accesso di DefectDojo apparirà un pulsante **Log In With OIDC**. + +Usa **Validate Config** in qualsiasi momento per verificare le impostazioni senza salvarle. Questa funzione recupera il documento di discovery, verifica le chiavi di firma e l'issuer, restituisce l'esatto redirect URI da registrare presso il tuo provider e confronta le tue mappature di claim e gruppi con i claim pubblicizzati dal provider. + +## Claim Mapping + +Ogni riga associa una **OIDC Claim** al **DefectDojo Field** che deve popolare. Usa **Add Claim Mapping** per aggiungere altre righe e l'icona del cestino per rimuoverne una. + +![image](images/sso_oidc_claim_mapping.png) + +Un campo senza una riga corrispondente mantiene il proprio claim standard, quindi questa sezione è necessaria solo se il tuo provider utilizza nomi diversi. I claim standard sono: + +| DefectDojo Field | Claim standard | +| --- | --- | +| Username | `preferred_username` | +| Email | `email` | +| First Name | `given_name` | +| Last Name | `family_name` | + +Note: + +- Un'istanza non configurata si apre con queste quattro righe già compilate, così puoi vedere cosa fa OIDC prima di modificare qualsiasi cosa. +- Lo stesso claim può alimentare più di un campo. Ogni campo di DefectDojo può invece essere mappato da un solo claim. +- I claim vengono letti sia dall'ID token sia dalla risposta userinfo, quindi un claim che il tuo provider rilascia solo in uno dei due funziona comunque. +- Se per un determinato utente un claim mappato è mancante o vuoto, il campo mantiene il proprio valore standard invece di essere svuotato. + +## Group Mapping + +DefectDojo può replicare nei propri gruppi quelli segnalati dal tuo provider a ogni accesso. Seleziona **Enable Group Mapping** per visualizzare le impostazioni. + +![image](images/sso_oidc_group_mapping.png) + +- **Group Claim Name** — il claim che contiene i gruppi dell'utente. **La maggior parte dei provider non lo emette per impostazione predefinita** e richiede la configurazione esplicita di un mapper; in Keycloak, ad esempio, aggiungi un mapper *Group Membership* al client. Nota che un mapper *User Realm Role* invia i **ruoli** del realm, non i gruppi. +- **Group Limiter Regex Expression** — vengono replicati solo i gruppi che corrispondono a questa espressione. Usa `.*` per consentirli tutti. +- **Remove Stale Group Memberships** — se abilitata, le appartenenze a gruppi creati tramite OIDC che il provider non segnala più vengono rimosse al successivo accesso. Sono interessati solo i gruppi creati da OIDC; i gruppi assegnati manualmente e quelli forniti da un altro provider, come SAML, non vengono mai toccati. + +I gruppi vengono creati al primo utilizzo e denominati esattamente come li segnala il provider. Se il tuo provider invia i percorsi completi dei gruppi (il mapper *Group Membership* di Keycloak lo fa quando è abilitata l'opzione **Full group path**), il gruppo in DefectDojo viene denominato `/Group A` anziché `Group A`. Disattiva questa opzione se vuoi che i nomi corrispondano ai gruppi provenienti da un altro provider, altrimenti finirai per avere due gruppi DefectDojo per lo stesso gruppo logico. + +Se il mapping dei gruppi sembra non avere alcun effetto, esegui **Validate Config**: questa funzione indica se il claim che hai indicato è tra quelli pubblicizzati dal provider. diff --git a/docs/content/admin/sso/PRO__oidc.pt-br.md b/docs/content/admin/sso/PRO__oidc.pt-br.md new file mode 100644 index 0000000000..4dad98c8bd --- /dev/null +++ b/docs/content/admin/sso/PRO__oidc.pt-br.md @@ -0,0 +1,62 @@ +--- +title: OIDC +description: Configure o SSO OpenID Connect (OIDC) no DefectDojo Pro +weight: 17 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login por meio de um provedor genérico OpenID Connect (OIDC). O DefectDojo open-source não inclui SSO — consulte [Usuários Autorizados](/admin/user_management/os__authorized_users/) para o controle de acesso no open-source. + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OIDC Settings**. + +![image](images/oidc_pro.png) + +Preencha o formulário: + +1. **Endpoint** — a URL base do seu provedor OIDC. Não inclua `/.well-known/openid-configuration`. +2. **Client ID** — o ID de cliente do seu OIDC. +3. **Client Secret** — o segredo de cliente do seu OIDC. +4. Opcionalmente, configure **Claim Mapping** e **Group Mapping** — veja abaixo. +5. Marque **Enable OIDC**. + +Envie o formulário. Um botão **Log In With OIDC** aparecerá na página de login do DefectDojo. + +Use **Validate Config** a qualquer momento para verificar as configurações sem salvá-las. Isso busca o documento de descoberta, verifica as chaves de assinatura e o emissor, exibe o URI de redirecionamento exato a ser registrado no seu provedor e faz a validação cruzada dos seus mapeamentos de claims e grupos com as claims anunciadas pelo provedor. + +## Mapeamento de Claims + +Cada linha mapeia uma **OIDC Claim** para o **DefectDojo Field** que ela deve preencher. Use **Add Claim Mapping** para adicionar linhas e o ícone de lixeira para remover uma. + +![image](images/sso_oidc_claim_mapping.png) + +Um campo sem linha correspondente mantém sua claim padrão, então esta seção só é necessária quando seu provedor nomeia as coisas de forma diferente. As claims padrão são: + +| DefectDojo Field | Claim padrão | +| --- | --- | +| Username | `preferred_username` | +| Email | `email` | +| First Name | `given_name` | +| Last Name | `family_name` | + +Observações: + +- Uma instância não configurada é aberta com essas quatro linhas já preenchidas, para que você possa ver o que o OIDC está fazendo antes de alterar qualquer coisa. +- A mesma claim pode alimentar mais de um campo. Cada campo do DefectDojo só pode ser mapeado a partir de uma única claim. +- As claims são lidas tanto do ID token quanto da resposta userinfo, então uma claim que seu provedor libera em apenas um dos dois ainda funciona. +- Se uma claim mapeada estiver ausente ou vazia para um determinado usuário, esse campo mantém seu valor padrão em vez de ficar em branco. + +## Mapeamento de Grupos + +O DefectDojo pode espelhar os grupos que seu provedor reporta nos grupos do DefectDojo a cada login. Marque **Enable Group Mapping** para exibir as configurações. + +![image](images/sso_oidc_group_mapping.png) + +- **Group Claim Name** — a claim que contém os grupos do usuário. **A maioria dos provedores não emite uma por padrão** e precisa que um mapper seja configurado explicitamente; no Keycloak, por exemplo, adicione um mapper *Group Membership* ao cliente. Observe que um mapper *User Realm Role* envia **roles** de realm, não grupos. +- **Group Limiter Regex Expression** — apenas os grupos que correspondem a esta expressão são espelhados. Use `.*` para permitir todos. +- **Remove Stale Group Memberships** — quando habilitado, as associações em grupos provisionados pelo OIDC que o provedor não reporta mais são removidas no próximo login. Apenas os grupos criados pelo OIDC são afetados; grupos que você atribuiu manualmente e grupos provisionados por outro provedor, como o SAML, nunca são alterados. + +Os grupos são criados no primeiro uso e nomeados exatamente como o provedor os reporta. Se o seu provedor enviar caminhos completos de grupo (o mapper *Group Membership* do Keycloak faz isso quando **Full group path** está habilitado), o grupo do DefectDojo será nomeado `/Group A` em vez de `Group A`. Desative essa opção se quiser que os nomes correspondam aos grupos vindos de outro provedor; caso contrário, você acabará com dois grupos do DefectDojo para o mesmo grupo lógico. + +Se o mapeamento de grupos parecer não fazer nada, execute **Validate Config**: ele informa se a claim que você indicou é uma das que o provedor anuncia. diff --git a/docs/content/admin/sso/PRO__oidc.zh-hans.md b/docs/content/admin/sso/PRO__oidc.zh-hans.md new file mode 100644 index 0000000000..798765f383 --- /dev/null +++ b/docs/content/admin/sso/PRO__oidc.zh-hans.md @@ -0,0 +1,62 @@ +--- +title: OIDC +description: 在 DefectDojo Pro 中配置 OpenID Connect (OIDC) 单点登录 +weight: 17 +audience: pro +--- + +DefectDojo Pro 支持通过通用 OpenID Connect (OIDC) 提供程序登录。开源版 DefectDojo 不包含单点登录（SSO）功能——有关开源版的访问控制，请参阅[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 配置 + +在 DefectDojo 中，进入 **Enterprise Settings > OIDC Settings**。 + +![image](images/oidc_pro.png) + +填写表单： + +1. **Endpoint** —— 您的 OIDC 提供程序的基础 URL。请勿包含 `/.well-known/openid-configuration`。 +2. **Client ID** —— 您的 OIDC 客户端 ID。 +3. **Client Secret** —— 您的 OIDC 客户端密钥。 +4. 可选配置 **Claim Mapping** 和 **Group Mapping** —— 参见下文。 +5. 勾选 **Enable OIDC**。 + +提交表单后，DefectDojo 登录页面上会出现一个 **Log In With OIDC** 按钮。 + +您可以随时使用 **Validate Config** 在不保存设置的情况下检查配置。它会获取发现文档、验证签名密钥和颁发者、回显应在您的提供程序处注册的确切重定向 URI，并将您的声明与组映射与提供程序公布的声明进行交叉核对。 + +## 声明映射 + +每一行将一个 **OIDC Claim** 映射到它应填充的 **DefectDojo Field**。使用 **Add Claim Mapping** 添加更多行，使用垃圾桶图标删除某一行。 + +![image](images/sso_oidc_claim_mapping.png) + +没有对应行的字段将保留其标准声明，因此只有在您的提供程序使用不同命名时才需要此部分。标准声明如下： + +| DefectDojo Field | Standard claim | +| --- | --- | +| Username | `preferred_username` | +| Email | `email` | +| First Name | `given_name` | +| Last Name | `family_name` | + +说明： + +- 未配置的实例默认已填好这四行，因此您可以在做任何更改之前先看到 OIDC 的默认行为。 +- 同一个声明可以填充多个字段。但每个 DefectDojo 字段只能由一个声明映射。 +- 声明会同时从 ID 令牌和 userinfo 响应中读取，因此即使您的提供程序只在其中一处发布某个声明，映射仍然有效。 +- 如果某个用户缺少已映射的声明或该声明为空，该字段将保留其标准值，而不会被清空。 + +## 组映射 + +DefectDojo 可以在每次登录时，将您的提供程序报告的组镜像为 DefectDojo 中的组。勾选 **Enable Group Mapping** 以显示相关设置。 + +![image](images/sso_oidc_group_mapping.png) + +- **Group Claim Name** —— 包含用户组信息的声明。**大多数提供程序默认不会发出此声明**，需要显式配置映射器；例如在 Keycloak 中，需要为客户端添加一个 *Group Membership* 映射器。请注意，*User Realm Role* 映射器发送的是领域（realm）**角色**，而不是组。 +- **Group Limiter Regex Expression** —— 只有匹配此表达式的组才会被镜像。使用 `.*` 可允许所有组。 +- **Remove Stale Group Memberships** —— 启用后，提供程序在下一次登录时不再报告的 OIDC 生成组的成员关系将被移除。此操作仅影响由 OIDC 创建的组；您手动分配的组，以及由其他提供程序（如 SAML）生成的组，均不受影响。 + +组会在首次使用时创建，并按提供程序报告的名称精确命名。如果您的提供程序发送完整的组路径（例如启用了 **Full group path** 选项的 Keycloak *Group Membership* 映射器就会这样做），DefectDojo 中的组名将是 `/Group A` 而不是 `Group A`。如果您希望名称与来自其他提供程序的组保持一致，请关闭该选项，否则最终会为同一个逻辑组生成两个不同的 DefectDojo 组。 + +如果组映射看起来没有任何效果，请运行 **Validate Config**：它会报告您指定的声明是否是提供程序实际公布的声明之一。 diff --git a/docs/content/admin/sso/PRO__okta.it.md b/docs/content/admin/sso/PRO__okta.it.md new file mode 100644 index 0000000000..7440aaa646 --- /dev/null +++ b/docs/content/admin/sso/PRO__okta.it.md @@ -0,0 +1,46 @@ +--- +title: Okta +description: Configura il Single Sign-On Okta in DefectDojo Pro +weight: 15 +audience: pro +--- + +DefectDojo Pro supporta l'accesso tramite Okta. DefectDojo open source non include il SSO — consulta [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## Prerequisiti + +Completa i seguenti passaggi in Okta prima di configurare DefectDojo: + +1. Accedi o crea un account su [Okta](https://www.okta.com/developer/signup/). + +2. Vai su **Applications** e fai clic su **Add Application**. + + ![image](images/okta_1.png) + +3. Seleziona **Web Applications**. + + ![image](images/okta_2.png) + +4. In **Login Redirect URLs**, aggiungi l'URL di callback di DefectDojo. Seleziona anche la casella **Implicit**. + + ![image](images/okta_3.png) + +5. Fai clic su **Done**. + +6. Dalla **Dashboard**, annota l'**Org-URL**. + + ![image](images/okta_4.png) + +7. Apri l'applicazione appena creata e annota il **Client ID** e il **Client Secret**. + + ![image](images/okta_5.png) + +## Configurazione + +In DefectDojo, vai su **Enterprise Settings > OAuth Settings**, seleziona **Okta** e compila il modulo: + +- **Okta OAuth Key** — inserisci il tuo **Client ID** +- **Okta OAuth Secret** — inserisci il tuo **Client Secret** +- **Okta Tenant ID** — inserisci il tuo Org-URL nel formato `https://your-org-url/oauth2` + +Seleziona **Enable Okta OAuth** e invia il modulo. Nella pagina di accesso apparirà un pulsante **Login With Okta**. diff --git a/docs/content/admin/sso/PRO__okta.pt-br.md b/docs/content/admin/sso/PRO__okta.pt-br.md new file mode 100644 index 0000000000..e60c61664f --- /dev/null +++ b/docs/content/admin/sso/PRO__okta.pt-br.md @@ -0,0 +1,46 @@ +--- +title: Okta +description: Configure o SSO do Okta no DefectDojo Pro +weight: 15 +audience: pro +--- + +O DefectDojo Pro oferece suporte a login via Okta. O DefectDojo open-source não inclui SSO — consulte [Usuários Autorizados](/admin/user_management/os__authorized_users/) para o controle de acesso no open-source. + +## Pré-requisitos + +Conclua as etapas a seguir no Okta antes de configurar o DefectDojo: + +1. Faça login ou crie uma conta em [Okta](https://www.okta.com/developer/signup/). + +2. Acesse **Applications** e clique em **Add Application**. + + ![image](images/okta_1.png) + +3. Selecione **Web Applications**. + + ![image](images/okta_2.png) + +4. Em **Login Redirect URLs**, adicione a URL de callback do seu DefectDojo. Marque também a caixa **Implicit**. + + ![image](images/okta_3.png) + +5. Clique em **Done**. + +6. No **Dashboard**, anote a **Org-URL**. + + ![image](images/okta_4.png) + +7. Abra o aplicativo recém-criado e anote o **Client ID** e o **Client Secret**. + + ![image](images/okta_5.png) + +## Configuração + +No DefectDojo, acesse **Enterprise Settings > OAuth Settings**, selecione **Okta** e preencha o formulário: + +- **Okta OAuth Key** — insira seu **Client ID** +- **Okta OAuth Secret** — insira seu **Client Secret** +- **Okta Tenant ID** — insira sua Org-URL no formato `https://your-org-url/oauth2` + +Marque **Enable Okta OAuth** e envie o formulário. Um botão **Login With Okta** aparecerá na página de login. diff --git a/docs/content/admin/sso/PRO__okta.zh-hans.md b/docs/content/admin/sso/PRO__okta.zh-hans.md new file mode 100644 index 0000000000..55834ac230 --- /dev/null +++ b/docs/content/admin/sso/PRO__okta.zh-hans.md @@ -0,0 +1,46 @@ +--- +title: Okta +description: 在 DefectDojo Pro 中配置 Okta 单点登录 +weight: 15 +audience: pro +--- + +DefectDojo Pro 支持通过 Okta 登录。开源版 DefectDojo 不包含单点登录（SSO）功能——有关开源版的访问控制，请参阅[已授权用户](/admin/user_management/os__authorized_users/)。 + +## 前提条件 + +在配置 DefectDojo 之前，请先在 Okta 中完成以下步骤： + +1. 前往 [Okta](https://www.okta.com/developer/signup/) 登录或创建账户。 + +2. 进入 **Applications**，点击 **Add Application**。 + + ![image](images/okta_1.png) + +3. 选择 **Web Applications**。 + + ![image](images/okta_2.png) + +4. 在 **Login Redirect URLs** 下，添加您的 DefectDojo 回调 URL。同时勾选 **Implicit** 复选框。 + + ![image](images/okta_3.png) + +5. 点击 **Done**。 + +6. 在 **Dashboard** 中，记下 **Org-URL**。 + + ![image](images/okta_4.png) + +7. 打开新创建的应用程序，记下 **Client ID** 和 **Client Secret**。 + + ![image](images/okta_5.png) + +## 配置 + +在 DefectDojo 中，进入 **Enterprise Settings > OAuth Settings**，选择 **Okta**，然后填写表单： + +- **Okta OAuth Key** —— 输入您的 **Client ID** +- **Okta OAuth Secret** —— 输入您的 **Client Secret** +- **Okta Tenant ID** —— 按照 `https://your-org-url/oauth2` 的格式输入您的 Org-URL + +勾选 **Enable Okta OAuth** 并提交表单。登录页面上将出现一个 **Login With Okta** 按钮。 diff --git a/docs/content/admin/sso/PRO__saml.it.md b/docs/content/admin/sso/PRO__saml.it.md new file mode 100644 index 0000000000..272e27fe72 --- /dev/null +++ b/docs/content/admin/sso/PRO__saml.it.md @@ -0,0 +1,155 @@ +--- +title: Configurazione SAML +description: Configura SAML in DefectDojo Pro +weight: 1 +audience: pro +--- + +DefectDojo Pro supporta l'autenticazione SAML tramite l'interfaccia **Enterprise Settings**. DefectDojo open source non include il SSO — consulta [Utenti autorizzati](/admin/user_management/os__authorized_users/) per il controllo degli accessi in open source. + +## URL ACS (Assertion Consumer Service) + +Il tuo Identity Provider deve sapere dove effettuare il POST della risposta SAML dopo l'autenticazione di un utente. L'URL ACS di DefectDojo è: + +``` +https://.cloud.defectdojo.com/saml2/acs/ +``` + +Alcune cose da sapere su questo endpoint: + +- **L'endpoint accetta solo richieste `POST`.** Aprire l'URL ACS direttamente in un browser genera una richiesta GET e restituisce un **HTTP 405 Method Not Allowed**. Si tratta di un comportamento previsto — non significa che SAML sia rotto o mal configurato. L'endpoint è pensato per essere invocato dal tuo IdP come parte del flusso di redirect SAML, non digitando l'URL in un browser. +- **L'URL ACS è sempre disponibile sulla tua istanza DefectDojo Cloud** — non è necessario abilitare prima SAML in DefectDojo per poterlo indicare al tuo IdP. Puoi configurare il lato IdP e il lato DefectDojo nell'ordine che preferisci. + +## Configurazione + +1. Apri **Enterprise Settings > SAML Settings**. + + ![image](images/sso_betaui_1.png) + +2. Imposta un **Entity ID** — un'etichetta o un URL che il tuo SAML Identity Provider utilizza per identificare DefectDojo. Questo campo è obbligatorio. + +3. Facoltativamente, imposta **Login Button Text** — il testo mostrato sul pulsante che gli utenti cliccano per avviare l'accesso SAML. + +4. Facoltativamente, imposta un **Logout URL** verso cui reindirizzare gli utenti dopo che escono da DefectDojo. + +5. Scegli un **Name ID Format**: + - **Persistent** — gli utenti vengono identificati in modo coerente tramite SAML tra una sessione e l'altra. + - **Transient** — gli utenti ricevono un ID SAML diverso a ogni accesso. + - **Entity** — tutti gli utenti condividono un unico NameID SAML. + - **Encrypted** — il NameID di ciascun utente è crittografato. + +6. **Required Attributes** — specifica gli attributi che DefectDojo richiede dalla risposta SAML. + +7. **Attribute Mapping** — associa gli attributi inviati dal tuo IdP ai campi utente di DefectDojo che devono popolare. Ogni riga abbina un **SAML Attribute** a un **DefectDojo Field**; usa **Add Attribute Mapping** per aggiungere altre righe e l'icona del cestino per rimuoverne una. + + ![image](images/sso_saml_attribute_mapping.png) + + - **SAML Attribute** è testo libero e deve corrispondere al nome dell'attributo effettivamente emesso dal tuo IdP. Alcuni IdP (ad esempio Entra ID / Azure AD) inviano URI di claim completamente qualificati, come `http://schemas.microsoft.com/identity/claims/emailaddress`, anziché nomi semplici. Se non sei sicuro di cosa invii il tuo IdP, abilita **Enable SAML Debugging** (vedi [Risoluzione dei problemi](#troubleshooting)) e ispeziona l'asserzione nei log. + - **DefectDojo Field** si sceglie da un elenco: **Username**, **First Name**, **Last Name** e **Email**. + - Come minimo, associa l'attributo corrispondente a **Username**. DefectDojo cerca gli utenti in base allo username quando abbina gli accessi SAML agli account esistenti. + - Si consiglia vivamente di associare un attributo a **Email**: DefectDojo utilizza l'indirizzo email per le notifiche e per abbinare un accesso in entrata a un account esistente in base all'email. + - Lo stesso attributo può alimentare più di un campo — ad esempio un claim email usato sia per **Email** sia per **Username**. Il contrario non è consentito: ogni campo di DefectDojo può essere mappato da un solo attributo. + - Una riga con solo una metà compilata viene rifiutata al salvataggio e la cella incriminata viene evidenziata. Le righe aggiunte ma mai compilate vengono scartate anziché essere trattate come errori. + +8. **Remote SAML Metadata** — l'URL in cui è ospitato il metadata del tuo SAML Identity Provider. + +9. Seleziona **Enable SAML** in fondo al modulo per attivare l'accesso SAML. Nella pagina di accesso di DefectDojo apparirà un pulsante **Login With SAML**. + + ![image](images/sso_saml_login.png). + +## Opzioni aggiuntive + +* **Create Unknown User** — crea automaticamente un nuovo utente DefectDojo se non viene trovato nella risposta SAML. +* **Allow Unknown Attributes** — consente l'accesso agli utenti che hanno attributi non elencati nell'Attribute Mapping. +* **Sign Assertions/Responses** — richiede che tutte le risposte SAML in entrata siano firmate. +* **Sign Logout Requests** — firma tutte le richieste di logout inviate da DefectDojo. +* **Force Authentication** — richiede agli utenti di autenticarsi con l'Identity Provider a ogni accesso, indipendentemente dalle sessioni esistenti. +* **Enable SAML Debugging** — registra un output SAML dettagliato per la risoluzione dei problemi. Consulta [Risoluzione dei problemi → Output di SAML Debugging](#saml-debugging-output) per sapere dove compare l'output dei log. + +## SAML Group Mapping + +DefectDojo può utilizzare l'asserzione SAML per assegnare automaticamente gli utenti ai [Gruppi di utenti](../../user_management/create_user_group/). I gruppi in DefectDojo assegnano i permessi a tutti i loro membri, quindi il Group Mapping consente di gestire i permessi in blocco. Questo è l'unico modo per impostare i permessi tramite SAML. + +**Il group mapping è facoltativo.** Sebbene i campi **Group Name Attribute** e **Group Limiter Regex Expression** compaiano con l'asterisco dei campi obbligatori (`*`) nell'interfaccia, il modulo SAML viene inviato anche senza compilarli, e l'accesso SAML funziona anche senza group mapping. Non è necessario creare in anticipo gruppi o ruoli nel tuo IdP (ad esempio i ruoli applicativi di Azure AD) prima di abilitare SAML — devi configurare questi campi solo quando vuoi effettivamente che DefectDojo legga l'appartenenza ai gruppi dall'asserzione. Se non configuri il group mapping, i nuovi utenti SSO creati non avranno alcun permesso per impostazione predefinita; consulta [Accesso predefinito per gli utenti forniti tramite SSO](#default-access-for-sso-provisioned-users) più sotto. + +Il campo **Group Name Attribute** specifica quale attributo nell'asserzione SAML contiene le appartenenze ai gruppi dell'utente. Quando un utente accede, DefectDojo legge questo attributo e assegna l'utente a tutti i gruppi corrispondenti. Per limitare quali gruppi dell'asserzione vengono considerati, usa il campo **Group Limiter Regex Expression** — si tratta di un'espressione regolare applicata ai nomi dei gruppi presenti nell'asserzione, usata per filtrare su quali DefectDojo deve agire. + +Il valore deve corrispondere esattamente al nome dell'attributo emesso dal tuo Identity Provider nell'asserzione, incluso eventuale prefisso di namespace. Un nome breve e semplice come `groups` funziona solo se il tuo IdP è configurato per emettere esattamente quel nome di attributo — molti IdP utilizzano invece un URI di claim completamente qualificato. + +### Group Name Attribute per Identity Provider + +| Identity Provider | Nome attributo predefinito da usare | +|---|---| +| **Entra ID / Azure AD** | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` | +| **Okta** | `groups` (il nome dell'attributo configurato nella Group Attribute Statement dell'app SAML) | +| **Keycloak** | `groups` (oppure il valore impostato come "SAML Attribute Name" nel mapper Group List) | +| **PingFederate / generico** | Il valore configurato lato IdP — verifica l'asserzione del tuo IdP prima di presumere che sia `groups` | + +Se il group mapping sembra non avere alcun effetto — gli utenti accedono correttamente ma non viene creato o assegnato alcun gruppo — consulta [Risoluzione dei problemi → Il SAML group mapping non ha alcun effetto](#saml-group-mapping-does-nothing--users-log-in-but-no-groups-are-assigned) più sotto. + +Se non esiste alcun gruppo con un nome corrispondente, DefectDojo ne crea automaticamente uno e assegna ai suoi membri il ruolo **Reader**. Nota che questo ruolo Reader governa l'accesso del membro *al gruppo stesso* — non concede alcun accesso ai Prodotti, ai Tipi di Prodotto o ad altri asset organizzativi sottostanti. Questi permessi vengono configurati separatamente, e un gruppo appena creato automaticamente non ne ha ancora nessuno finché un Superuser non assegna al gruppo un ruolo sui relativi Prodotti o Tipi di Prodotto. + +Per attivare il group mapping, seleziona la casella **Enable Group Mapping** in fondo al modulo. + +## Accesso predefinito per gli utenti forniti tramite SSO + +Quando un nuovo utente viene creato tramite SAML (o qualsiasi provider di social-auth) e non viene aggiunto ad alcun gruppo tramite il SAML Group Mapping, si troverà su un'istanza DefectDojo **senza alcun permesso**. Al momento dell'accesso non vedrà alcun Tipo di Prodotto, alcun Prodotto né alcun Engagement — la dashboard apparirà vuota. + +Per fornire a ogni nuovo utente SSO una base di permessi ragionevole, configura un **Default group** e un **Default group role** nella pagina System Settings: + +1. Apri **⚙️ Configuration → System Settings** (solo Superuser). +2. Imposta **Default group** sul [Gruppo di utenti](../../user_management/create_user_group/) a cui devono unirsi i nuovi utenti creati. +3. Imposta **Default group role** sul ruolo che devono avere in quel gruppo (ad esempio **Reader**). +4. Facoltativamente, imposta **Default group email pattern** su un'espressione regolare (ad esempio `.*@yourcompany\.com$`) in modo che il gruppo predefinito venga applicato solo agli utenti la cui email corrisponde. +5. Salva. + +Devono essere impostati sia **Default group** sia **Default group role** — se anche uno solo dei due è vuoto, il gruppo predefinito non viene applicato. + +Questa impostazione si applica a **ogni nuovo utente creato**, compresi quelli creati tramite SAML, OAuth e altri provider di social-auth, perché viene eseguita sul signal di creazione utente di Django anziché all'interno di un backend di autenticazione specifico. + +> **Gli utenti esistenti non sono interessati.** Il gruppo predefinito viene applicato solo alla prima creazione di un utente. Gli utenti DefectDojo esistenti manterranno le loro attuali appartenenze ai gruppi anche se in seguito modifichi questa impostazione. + +## Differenze tra Cloud e On-Premise + +DefectDojo Cloud non offre lo stesso livello di personalizzazione SAML di DefectDojo On-Prem. Le uniche variabili impostabili sono quelle disponibili tramite l'interfaccia. Ecco alcune delle differenze principali: + +| Capability | Cloud | On-Premise | +|---|---|---| +| **Corrispondenza username** | Solo NameID | Solo NameID (la variabile d'ambiente `SAML_USE_NAME_ID_AS_USERNAME` si applica solo a Open Source, non a Pro) | +| **Crittografia dell'asserzione SAML** | Non attualmente supportata | Non attualmente supportata | +| **Log di accesso SAML** | Non disponibili nell'interfaccia. Contatta il Supporto per richiedere i log. | Disponibili tramite i log del container dell'applicazione (`docker logs dojo`) | +| **Metodo di configurazione** | Solo interfaccia Enterprise Settings | Interfaccia Enterprise Settings, Django Admin o Django Shell | +| **Variabili d'ambiente** | Non possono essere impostate direttamente dai clienti. Contatta il Supporto per le modifiche. | Possono essere impostate tramite `dojo-compose-cli environment add` | + +Se hai bisogno di far corrispondere gli utenti in base a un attributo diverso da NameID (come `uid` o `email`), configura il tuo Identity Provider affinché invii il valore desiderato come NameID, invece di modificare le impostazioni di DefectDojo. + +## Risoluzione dei problemi + +### Output di SAML Debugging + +Quando è selezionata **Enable SAML Debugging** (in [Opzioni aggiuntive](#additional-options)), DefectDojo scrive un output dettagliato dell'elaborazione SAML — inclusi gli attributi grezzi ricevuti dall'IdP — nei log dell'applicazione a livello `DEBUG`, sotto il logger `saml2`. + +| Where you're running | Where to read the debug output | +|---|---| +| **DefectDojo Cloud** | Il log di debug SAML non è esposto nell'interfaccia. Contatta il Supporto DefectDojo per richiedere i log relativi a un intervallo di tempo specifico. | +| **On-Premise (container singolo)** | `docker logs dojo` (oppure l'aggregatore di log del tuo Helm/K8s) | +| **On-Premise (Helm/K8s)** | `kubectl logs deployment/defectdojo-django -c uwsgi` (oppure l'aggregatore di log del tuo cluster) | + +Disattiva questa opzione una volta terminata la risoluzione dei problemi — i log di debug SAML sono verbosi e potrebbero contenere valori di attributi sensibili provenienti dal tuo IdP. + +### Gli utenti ricevono un errore "User not found" o "Permission denied" dopo un accesso IdP riuscito + +Se l'asserzione SAML viene analizzata correttamente (nessun errore XML o di firma) ma DefectDojo rifiuta l'accesso, la causa più comune è una **discrepanza tra gli username** dell'IdP e di DefectDojo. + +DefectDojo cerca l'utente **in base allo username** quando abbina un accesso SAML a un account esistente. Se il valore inviato dal tuo IdP come attributo `username` non corrisponde allo username di un utente DefectDojo esistente, la ricerca fallisce — anche se il resto dell'asserzione è valido. + +Due possibili soluzioni, scegli quella più adatta al tuo ambiente: + +- **Rimuovi `username` dall'Attribute Mapping** e lascia che DefectDojo utilizzi invece il `NameID` SAML come username. Questo è appropriato se gli username di DefectDojo corrispondono già al formato NameID emesso dal tuo IdP. +- **Allinea gli username.** Assicurati che gli username in DefectDojo corrispondano esattamente a quanto invia il tuo IdP nel claim `username`. Per la maggior parte delle organizzazioni la convenzione più semplice è far coincidere gli username di DefectDojo con l'indirizzo email dell'utente, e far sì che l'IdP invii l'email come claim `username`. + +Se non sei sicuro di cosa stia effettivamente inviando l'IdP, abilita **Enable SAML Debugging** (sopra) e ispeziona gli attributi analizzati nei log. + +### Il SAML group mapping non ha alcun effetto — gli utenti accedono ma non viene assegnato alcun gruppo + +La causa più comune è una discrepanza tra il campo **Group Name Attribute** e il nome dell'attributo effettivamente inviato dal tuo IdP. Consulta la tabella [Group Name Attribute per Identity Provider](#group-name-attribute-by-identity-provider) più sopra e abilita **Enable SAML Debugging** per vedere gli attributi grezzi restituiti dall'IdP. diff --git a/docs/content/admin/sso/PRO__saml.pt-br.md b/docs/content/admin/sso/PRO__saml.pt-br.md new file mode 100644 index 0000000000..fcf5133f8f --- /dev/null +++ b/docs/content/admin/sso/PRO__saml.pt-br.md @@ -0,0 +1,155 @@ +--- +title: Configuração de SAML +description: Configure o SAML no DefectDojo Pro +weight: 1 +audience: pro +--- + +O DefectDojo Pro oferece suporte à autenticação SAML por meio da interface **Enterprise Settings**. O DefectDojo open-source não inclui SSO — consulte [Usuários Autorizados](/admin/user_management/os__authorized_users/) para o controle de acesso no open-source. + +## URL do ACS (Assertion Consumer Service) + +Seu Identity Provider precisa saber para onde enviar (POST) a resposta SAML depois que um usuário se autentica. A URL do ACS do DefectDojo é: + +``` +https://.cloud.defectdojo.com/saml2/acs/ +``` + +Algumas coisas a saber sobre esse endpoint: + +- **O endpoint aceita apenas requisições `POST`.** Abrir a URL do ACS diretamente em um navegador emite um GET e retornará um **HTTP 405 Method Not Allowed**. Esse é o comportamento esperado — não significa que o SAML esteja quebrado ou mal configurado. O endpoint foi projetado para ser invocado pelo seu IdP como parte do fluxo de redirecionamento SAML, não por um navegador acessando a URL diretamente. +- **A URL do ACS está disponível na sua instância do DefectDojo Cloud o tempo todo** — você não precisa habilitar o SAML no DefectDojo antes de apontar seu IdP para ela. Você pode configurar o lado do IdP e o lado do DefectDojo em qualquer ordem. + +## Configuração inicial + +1. Acesse **Enterprise Settings > SAML Settings**. + + ![image](images/sso_betaui_1.png) + +2. Defina um **Entity ID** — um rótulo ou URL que seu SAML Identity Provider usa para identificar o DefectDojo. Este campo é obrigatório. + +3. Opcionalmente, defina o **Login Button Text** — o texto exibido no botão em que os usuários clicam para iniciar o login SAML. + +4. Opcionalmente, defina uma **Logout URL** para redirecionar os usuários depois que eles saírem do DefectDojo. + +5. Escolha um **Name ID Format**: + - **Persistent** — os usuários são identificados de forma consistente pelo SAML entre sessões. + - **Transient** — os usuários recebem um ID SAML diferente a cada login. + - **Entity** — todos os usuários compartilham um único NameID SAML. + - **Encrypted** — o NameID de cada usuário é criptografado. + +6. **Required Attributes** — especifique os atributos que o DefectDojo exige na resposta SAML. + +7. **Attribute Mapping** — mapeie os atributos enviados pelo seu IdP para os campos de usuário do DefectDojo que eles devem preencher. Cada linha associa um **SAML Attribute** a um **DefectDojo Field**; use **Add Attribute Mapping** para adicionar linhas e o ícone de lixeira para remover uma. + + ![image](images/sso_saml_attribute_mapping.png) + + - **SAML Attribute** é um campo de texto livre e deve corresponder exatamente ao nome do atributo que seu IdP realmente emite. Alguns IdPs (por exemplo, Entra ID / Azure AD) enviam URIs de claim totalmente qualificados, como `http://schemas.microsoft.com/identity/claims/emailaddress`, em vez de nomes amigáveis. Se você não tiver certeza do que seu IdP envia, habilite **Enable SAML Debugging** (veja [Solução de problemas](#troubleshooting)) e inspecione a assertion nos logs. + - **DefectDojo Field** é escolhido a partir de uma lista: **Username**, **First Name**, **Last Name** e **Email**. + - No mínimo, mapeie o atributo que corresponde a **Username**. O DefectDojo procura usuários pelo nome de usuário ao associar logins SAML a contas existentes. + - É altamente recomendável mapear um atributo para **Email**: o DefectDojo usa o endereço de e-mail para notificações e para associar um login recebido a uma conta existente pelo e-mail. + - O mesmo atributo pode alimentar mais de um campo — por exemplo, uma claim de e-mail usada tanto para **Email** quanto para **Username**. O inverso não é permitido: cada campo do DefectDojo só pode ser mapeado a partir de um único atributo. + - Uma linha com apenas metade preenchida é rejeitada ao salvar, e a célula problemática é destacada. Linhas que você adiciona mas nunca preenche são descartadas em vez de tratadas como erros. + +8. **Remote SAML Metadata** — a URL onde os metadados do seu SAML Identity Provider estão hospedados. + +9. Marque **Enable SAML** na parte inferior do formulário para ativar o login SAML. Um botão **Login With SAML** aparecerá na página de login do DefectDojo. + + ![image](images/sso_saml_login.png). + +## Opções adicionais + +* **Create Unknown User** — cria automaticamente um novo usuário do DefectDojo caso ele não seja encontrado na resposta SAML. +* **Allow Unknown Attributes** — permite o login de usuários que possuem atributos não listados no Attribute Mapping. +* **Sign Assertions/Responses** — exige que todas as respostas SAML recebidas sejam assinadas. +* **Sign Logout Requests** — assina todas as requisições de logout enviadas pelo DefectDojo. +* **Force Authentication** — exige que os usuários se autentiquem no Identity Provider a cada login, independentemente de sessões existentes. +* **Enable SAML Debugging** — registra a saída detalhada do SAML para solução de problemas. Veja [Solução de problemas → Saída do SAML Debugging](#saml-debugging-output) para saber onde essa saída aparece. + +## Mapeamento de Grupos SAML + +O DefectDojo pode usar a assertion SAML para atribuir usuários automaticamente a [Grupos de Usuários](../../user_management/create_user_group/). Os grupos no DefectDojo atribuem permissões a todos os seus membros, então o Group Mapping permite gerenciar permissões em massa. Essa é a única forma de definir permissões via SAML. + +**O mapeamento de grupos é opcional.** Embora os campos **Group Name Attribute** e **Group Limiter Regex Expression** apareçam com um asterisco de campo obrigatório (`*`) na interface, o formulário SAML será enviado sem eles, e o login SAML funcionará sem o mapeamento de grupos. Não é necessário pré-criar grupos ou roles no seu IdP (por exemplo, application roles do Azure AD) antes de habilitar o SAML — você só precisa configurar esses campos quando realmente quiser que o DefectDojo leia a associação a grupos a partir da assertion. Se você não configurar o mapeamento de grupos, os usuários de SSO recém-criados não terão permissões por padrão; veja [Acesso padrão para usuários provisionados por SSO](#default-access-for-sso-provisioned-users) abaixo. + +O campo **Group Name Attribute** especifica qual atributo na assertion SAML contém as associações de grupo do usuário. Quando um usuário faz login, o DefectDojo lê esse atributo e atribui o usuário a quaisquer grupos correspondentes. Para limitar quais grupos da assertion são considerados, use o campo **Group Limiter Regex Expression** — uma expressão regular aplicada aos nomes de grupo da assertion, usada para filtrar em quais o DefectDojo deve atuar. + +O valor deve corresponder exatamente ao nome do atributo que seu Identity Provider emite na assertion, incluindo qualquer prefixo de namespace. Um nome curto e amigável como `groups` só funcionará se o seu IdP estiver configurado para emitir esse nome de atributo literal — muitos IdPs usam, em vez disso, um URI de claim totalmente qualificado. + +### Group Name Attribute por Identity Provider + +| Identity Provider | Nome de atributo padrão a ser usado | +|---|---| +| **Entra ID / Azure AD** | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` | +| **Okta** | `groups` (o nome de atributo configurado no Group Attribute Statement do aplicativo SAML) | +| **Keycloak** | `groups` (ou o que você definir como "SAML Attribute Name" no mapper Group List) | +| **PingFederate / generic** | O valor que você configurou no lado do IdP — verifique a assertion do seu IdP antes de presumir `groups` | + +Se o mapeamento de grupos parecer não fazer nada — os usuários fazem login com sucesso, mas nenhum grupo é criado ou atribuído — veja [Solução de problemas → O mapeamento de grupos SAML não faz nada](#saml-group-mapping-does-nothing--users-log-in-but-no-groups-are-assigned) abaixo. + +Se não existir um grupo com o nome correspondente, o DefectDojo criará um automaticamente e atribuirá a seus membros a role **Reader**. Observe que essa role Reader rege o acesso do membro *ao próprio grupo* — ela não concede nenhum acesso aos Produtos, Tipos de Produto ou outros ativos organizacionais subjacentes. Essas permissões são configuradas separadamente, e um grupo recém-criado automaticamente ainda não tem nenhuma delas até que um Superuser atribua ao grupo uma role nos Produtos ou Tipos de Produto relevantes. + +Para ativar o mapeamento de grupos, marque a caixa de seleção **Enable Group Mapping** na parte inferior do formulário. + +## Acesso padrão para usuários provisionados por SSO + +Quando um novo usuário é criado via SAML (ou qualquer provedor social-auth) e não é adicionado a nenhum grupo via SAML Group Mapping, ele chegará a uma instância do DefectDojo **sem permissões**. Ao fazer login, ele verá zero Tipos de Produto, zero Produtos e zero Engajamentos — o painel aparecerá vazio. + +Para dar a todo novo usuário de SSO provisionado uma base razoável, configure um **Default group** + **Default group role** na página System Settings: + +1. Acesse **⚙️ Configuration → System Settings** (somente Superuser). +2. Defina **Default group** como o [Grupo de Usuários](../../user_management/create_user_group/) que os usuários recém-criados devem integrar. +3. Defina **Default group role** como a role que eles devem ter nesse grupo (por exemplo, **Reader**). +4. Opcionalmente, defina **Default group email pattern** com uma regex (por exemplo, `.*@yourcompany\\.com$`) para que o grupo padrão seja aplicado somente a usuários cujo e-mail corresponda. +5. Salve. + +Tanto **Default group** quanto **Default group role** precisam estar definidos — se algum deles estiver vazio, o grupo padrão não é aplicado. + +Essa configuração se aplica a **todo usuário recém-criado**, incluindo usuários criados via SAML, OAuth e outros provedores social-auth, porque ela é executada no sinal de criação de usuário do Django, em vez de dentro de um backend de autenticação específico. + +> **Usuários existentes não são afetados.** O grupo padrão só é aplicado quando um usuário é criado pela primeira vez. Os usuários existentes do DefectDojo manterão suas associações de grupo atuais mesmo que você altere essa configuração posteriormente. + +## Diferenças entre Cloud e On-Premise + +O DefectDojo Cloud não tem o mesmo nível de personalização de SAML que o DefectDojo On-Prem. As únicas variáveis que podem ser definidas são pela interface. Aqui estão algumas das principais diferenças: + +| Capacidade | Cloud | On-Premise | +|---|---|---| +| **Correspondência de nome de usuário** | Somente NameID | Somente NameID (a variável de ambiente `SAML_USE_NAME_ID_AS_USERNAME` se aplica somente ao Open Source, não ao Pro) | +| **Criptografia de assertion SAML** | Atualmente não suportado | Atualmente não suportado | +| **Logs de login SAML** | Não disponível na interface. Entre em contato com o Suporte para solicitar os logs. | Disponível via logs do container da aplicação (`docker logs dojo`) | +| **Método de configuração** | Somente pela interface Enterprise Settings | Interface Enterprise Settings, Django Admin ou Django Shell | +| **Variáveis de ambiente** | Não podem ser definidas diretamente pelos clientes. Entre em contato com o Suporte para alterações. | Podem ser definidas via `dojo-compose-cli environment add` | + +Se você precisar corresponder usuários por um atributo diferente de NameID (como `uid` ou `email`), configure seu Identity Provider para enviar o valor desejado como o NameID, em vez de ajustar as configurações do DefectDojo. + +## Solução de problemas + +### Saída do SAML Debugging + +Quando **Enable SAML Debugging** (em [Opções adicionais](#additional-options)) está marcado, o DefectDojo grava a saída detalhada do processamento SAML — incluindo os atributos brutos recebidos do IdP — nos logs da aplicação no nível `DEBUG`, sob o logger `saml2`. + +| Onde você está executando | Onde ler a saída de debug | +|---|---| +| **DefectDojo Cloud** | O log de debug do SAML não é exposto na interface. Entre em contato com o Suporte do DefectDojo para solicitar os logs de uma janela de tempo específica. | +| **On-Premise (container único)** | `docker logs dojo` (ou sua agregação de logs Helm/K8s) | +| **On-Premise (Helm/K8s)** | `kubectl logs deployment/defectdojo-django -c uwsgi` (ou o agregador de logs do seu cluster) | + +Desative essa opção depois de concluir a solução de problemas — os logs de debug do SAML são verbosos e podem conter valores de atributos sensíveis do seu IdP. + +### Os usuários recebem um erro "User not found" ou "Permission denied" depois de um login bem-sucedido no IdP + +Se a assertion SAML for processada com sucesso (sem erros de XML ou de assinatura), mas o DefectDojo recusar o login, a causa mais comum é uma **incompatibilidade de nome de usuário** entre o IdP e o DefectDojo. + +O DefectDojo procura o usuário **pelo nome de usuário** ao associar um login SAML a uma conta existente. Se o valor que seu IdP envia como o atributo `username` não corresponder ao nome de usuário de um usuário existente do DefectDojo, a busca falha — mesmo que o restante da assertion seja válido. + +Duas soluções possíveis, escolha a que melhor se encaixa no seu ambiente: + +- **Remova `username` do Attribute Mapping** e deixe o DefectDojo usar o `NameID` do SAML como nome de usuário. Isso é apropriado se os nomes de usuário do DefectDojo já corresponderem ao formato de NameID emitido pelo seu IdP. +- **Alinhe os nomes de usuário.** Certifique-se de que os nomes de usuário no DefectDojo sejam exatamente o que seu IdP envia na claim `username`. Para a maioria das organizações, a convenção mais simples é fazer os nomes de usuário do DefectDojo serem iguais ao endereço de e-mail do usuário, e configurar o IdP para enviar o e-mail como a claim `username`. + +Se você não tiver certeza do que o IdP está realmente enviando, habilite **Enable SAML Debugging** (acima) e inspecione os atributos processados nos logs. + +### O mapeamento de grupos SAML não faz nada — os usuários fazem login, mas nenhum grupo é atribuído + +A causa mais comum é uma incompatibilidade entre o campo **Group Name Attribute** e o nome do atributo que seu IdP está realmente enviando. Veja a tabela [Group Name Attribute por Identity Provider](#group-name-attribute-by-identity-provider) acima, e habilite **Enable SAML Debugging** para ver os atributos brutos retornados pelo IdP. diff --git a/docs/content/admin/sso/PRO__saml.zh-hans.md b/docs/content/admin/sso/PRO__saml.zh-hans.md new file mode 100644 index 0000000000..8a17395e9c --- /dev/null +++ b/docs/content/admin/sso/PRO__saml.zh-hans.md @@ -0,0 +1,155 @@ +--- +title: SAML 配置 +description: 在 DefectDojo Pro 中配置 SAML +weight: 1 +audience: pro +--- + +DefectDojo Pro 支持通过 **Enterprise Settings** 界面进行 SAML 身份验证。开源版 DefectDojo 不包含单点登录（SSO）功能——有关开源版的访问控制，请参阅[已授权用户](/admin/user_management/os__authorized_users/)。 + +## ACS URL (Assertion Consumer Service) + +您的身份提供程序需要知道在用户完成身份验证后应将 SAML 响应 POST 到哪里。DefectDojo 的 ACS URL 为： + +``` +https://.cloud.defectdojo.com/saml2/acs/ +``` + +关于此端点，有几点需要了解： + +- **该端点仅接受 `POST` 请求。** 直接在浏览器中打开 ACS URL 会发出 GET 请求，并返回 **HTTP 405 Method Not Allowed**。这是预期行为——并不代表 SAML 配置有误或出现故障。该端点被设计为由您的 IdP 在 SAML 重定向流程中调用，而不是由浏览器直接输入网址访问。 +- **ACS URL 始终在您的 DefectDojo Cloud 实例上可用**——您无需先在 DefectDojo 中启用 SAML 才能将 IdP 指向它。您可以按任意顺序配置 IdP 端和 DefectDojo 端。 + +## 设置 + +1. 打开 **Enterprise Settings > SAML Settings**。 + + ![image](images/sso_betaui_1.png) + +2. 设置 **Entity ID**——即您的 SAML 身份提供程序用来识别 DefectDojo 的标签或 URL。此字段为必填项。 + +3. 可选设置 **Login Button Text**——用户点击以开始 SAML 登录的按钮上显示的文字。 + +4. 可选设置 **Logout URL**，用于在用户从 DefectDojo 注销后将其重定向到该地址。 + +5. 选择一种 **Name ID Format**： + - **Persistent** —— 用户在各个会话中始终由相同的 SAML 标识来识别。 + - **Transient** —— 用户每次登录都会获得不同的 SAML ID。 + - **Entity** —— 所有用户共用同一个 SAML NameID。 + - **Encrypted** —— 每个用户的 NameID 均经过加密。 + +6. **Required Attributes** —— 指定 DefectDojo 要求 SAML 响应中必须包含的属性。 + +7. **Attribute Mapping** —— 将您的 IdP 发送的属性映射到它们应填充的 DefectDojo 用户字段。每一行将一个 **SAML Attribute** 与一个 **DefectDojo Field** 配对；使用 **Add Attribute Mapping** 添加更多行，使用垃圾桶图标删除某一行。 + + ![image](images/sso_saml_attribute_mapping.png) + + - **SAML Attribute** 为自由文本，必须与您的 IdP 实际发出的属性名称完全一致。部分 IdP（例如 Entra ID / Azure AD）发送的是完整限定的声明 URI，例如 `http://schemas.microsoft.com/identity/claims/emailaddress`，而不是易读的名称。如果不确定您的 IdP 发送的是什么，请启用 **Enable SAML Debugging**（参见[故障排查](#troubleshooting)），并在日志中查看断言内容。 + - **DefectDojo Field** 从一个列表中选择：**Username**、**First Name**、**Last Name** 和 **Email**。 + - 至少应映射对应 **Username** 的属性。DefectDojo 在将 SAML 登录与现有账户匹配时是按用户名查找用户的。 + - 强烈建议将某个属性映射到 **Email**：DefectDojo 会使用电子邮件地址发送通知，并用它来将传入的登录与现有账户按邮箱匹配。 + - 同一个属性可以填充多个字段——例如同一个电子邮件声明可以同时用于 **Email** 和 **Username**。但反过来不允许：每个 DefectDojo 字段只能由一个属性映射得到。 + - 只填写了一半的行在保存时会被拒绝，出错的单元格会被高亮显示。您添加但从未填写的行会被直接丢弃，而不会被当作错误处理。 + +8. **Remote SAML Metadata** —— 托管您的 SAML 身份提供程序元数据的 URL。 + +9. 勾选表单底部的 **Enable SAML** 以启用 SAML 登录。DefectDojo 登录页面上会出现一个 **Login With SAML** 按钮。 + + ![image](images/sso_saml_login.png)。 + +## 附加选项 + +* **Create Unknown User** —— 如果在 SAML 响应中找不到某用户，自动创建一个新的 DefectDojo 用户。 +* **Allow Unknown Attributes** —— 允许拥有未在 Attribute Mapping 中列出的属性的用户登录。 +* **Sign Assertions/Responses** —— 要求所有传入的 SAML 响应均已签名。 +* **Sign Logout Requests** —— 对 DefectDojo 发送的所有注销请求进行签名。 +* **Force Authentication** —— 无论是否存在现有会话，都要求用户在每次登录时都向身份提供程序进行身份验证。 +* **Enable SAML Debugging** —— 记录详细的 SAML 输出以供故障排查。有关日志输出位置，请参见[故障排查 → SAML Debugging output](#saml-debugging-output)。 + +## SAML 组映射 + +DefectDojo 可以使用 SAML 断言自动将用户分配到[用户组](../../user_management/create_user_group/)。DefectDojo 中的组会为其所有成员分配权限，因此组映射使您能够批量管理权限。这是通过 SAML 设置权限的唯一方式。 + +**组映射是可选的。** 尽管 **Group Name Attribute** 和 **Group Limiter Regex Expression** 字段在界面中带有必填星号（`*`），但即使不填写这两项，SAML 表单也可以提交，SAML 登录也能正常工作，无需组映射。您无需在启用 SAML 之前先在 IdP 中预先建好组或角色（例如 Azure AD 应用角色）——只有当您确实希望 DefectDojo 从断言中读取组成员信息时，才需要配置这些字段。如果不配置组映射，新创建的 SSO 用户默认将没有任何权限；请参见下文的 [SSO 生成用户的默认访问权限](#default-access-for-sso-provisioned-users)。 + +**Group Name Attribute** 字段用于指定 SAML 断言中哪个属性包含用户的组成员信息。用户登录时，DefectDojo 会读取该属性，并将用户分配到任何匹配的组。若要限制断言中哪些组会被纳入考虑，可使用 **Group Limiter Regex Expression** 字段——这是一个应用于断言中组名称的正则表达式，用于筛选 DefectDojo 应处理哪些组。 + +该值必须与您的身份提供程序在断言中实际发出的属性名称完全一致，包括任何命名空间前缀。像 `groups` 这样简短易读的名称，只有在您的 IdP 被配置为确实发出这个字面属性名时才有效——许多 IdP 实际使用的是完整限定的声明 URI。 + +### 按身份提供程序划分的 Group Name Attribute + +| Identity Provider | Default attribute name to use | +|---|---| +| **Entra ID / Azure AD** | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` | +| **Okta** | `groups`（您在 SAML 应用的 Group Attribute Statement 中配置的属性名） | +| **Keycloak** | `groups`（或您在 Group List 映射器上设置的 “SAML Attribute Name”） | +| **PingFederate / generic** | 您在 IdP 端配置的值——请检查您 IdP 的断言，不要想当然地认为是 `groups` | + +如果组映射看起来没有任何效果——用户能成功登录，但没有创建或分配任何组——请参见下文的[故障排查 → SAML 组映射没有效果](#saml-group-mapping-does-nothing--users-log-in-but-no-groups-are-assigned)。 + +如果不存在名称匹配的组，DefectDojo 会自动创建一个，并为其成员分配 **Reader** 角色。请注意，此 Reader 角色控制的是成员*对该组本身*的访问权限——它并不会授予对底层产品、产品类型或其他组织资产的任何访问权限。这些权限需要单独配置，新自动创建的组在超级用户为其分配相关产品或产品类型上的角色之前，不具备任何这类权限。 + +要启用组映射，请勾选表单底部的 **Enable Group Mapping** 复选框。 + +## SSO 生成用户的默认访问权限 + +当通过 SAML（或任何社交身份验证提供程序）创建新用户，且该用户未通过 SAML 组映射被添加到任何组时，该用户登录 DefectDojo 实例后将**没有任何权限**。他们登录后会看到零个产品类型、零个产品、零个测试活动——仪表板将显示为空。 + +要为每个新生成的 SSO 用户提供合理的基础权限，请在系统设置页面配置 **Default group** 和 **Default group role**： + +1. 打开 **⚙️ Configuration → System Settings**（仅超级用户可见）。 +2. 将 **Default group** 设置为新创建用户应加入的[用户组](../../user_management/create_user_group/)。 +3. 将 **Default group role** 设置为他们在该组中应持有的角色（例如 **Reader**）。 +4. 可选地将 **Default group email pattern** 设置为一个正则表达式（例如 `.*@yourcompany\.com$`），使默认组仅应用于邮箱匹配的用户。 +5. 保存。 + +**Default group** 和 **Default group role** 必须同时设置——如果其中任意一项为空，默认组将不会被应用。 + +此设置适用于**每个新创建的用户**，包括通过 SAML、OAuth 及其他社交身份验证提供程序创建的用户，因为它运行在 Django 的用户创建信号上，而不是在某个特定的身份验证后端内部。 + +> **现有用户不受影响。** 默认组仅在用户首次创建时应用。即使您之后更改此设置，现有的 DefectDojo 用户仍将保留其当前的组成员关系。 + +## Cloud 与 On-Premise 版本的差异 + +DefectDojo Cloud 的 SAML 自定义程度不如 DefectDojo On-Prem。唯一可设置的变量都是通过界面进行的。以下是一些主要区别： + +| Capability | Cloud | On-Premise | +|---|---|---| +| **Username matching** | 仅 NameID | 仅 NameID（`SAML_USE_NAME_ID_AS_USERNAME` 环境变量仅适用于开源版，不适用于 Pro 版） | +| **SAML assertion encryption** | 目前不支持 | 目前不支持 | +| **SAML login logs** | 界面中不可用。请联系支持团队请求日志。 | 可通过应用容器日志获取（`docker logs dojo`） | +| **Configuration method** | 仅限 Enterprise Settings 界面 | Enterprise Settings 界面、Django Admin 或 Django Shell | +| **Environment variables** | 客户无法直接设置。如需更改，请联系支持团队。 | 可通过 `dojo-compose-cli environment add` 设置 | + +如果您需要按 NameID 以外的属性（例如 `uid` 或 `email`）匹配用户，请将您的身份提供程序配置为将所需的值作为 NameID 发送，而不是调整 DefectDojo 的设置。 + +## 故障排查 + +### SAML 调试输出 + +当勾选[附加选项](#additional-options)中的 **Enable SAML Debugging** 后，DefectDojo 会将详细的 SAML 处理输出——包括从 IdP 收到的原始属性——以 `DEBUG` 级别写入 `saml2` 日志记录器下的应用日志。 + +| Where you're running | Where to read the debug output | +|---|---| +| **DefectDojo Cloud** | SAML 调试日志不会在界面中显示。请联系 DefectDojo 支持团队请求特定时间段的日志。 | +| **On-Premise (single container)** | `docker logs dojo`（或您的 Helm/K8s 日志聚合系统） | +| **On-Premise (Helm/K8s)** | `kubectl logs deployment/defectdojo-django -c uwsgi`（或您集群的日志聚合系统） | + +完成故障排查后，请**关闭**此选项——SAML 调试日志内容详细，可能包含来自您 IdP 的敏感属性值。 + +### 用户在 IdP 登录成功后收到 "User not found" 或 "Permission denied" 错误 + +如果 SAML 断言解析成功（没有 XML 或签名错误），但 DefectDojo 拒绝了登录，最常见的原因是 IdP 与 DefectDojo 之间的**用户名不匹配**。 + +DefectDojo 在将 SAML 登录与现有账户匹配时是**按用户名**查找用户的。如果您的 IdP 作为 `username` 属性发送的值与某个现有 DefectDojo 用户的用户名不一致，即使断言的其余部分均有效，查找也会失败。 + +有两种解决方法，请根据您的环境选择其一： + +- **从 Attribute Mapping 中移除 `username`**，让 DefectDojo 改为使用 SAML 的 `NameID` 作为用户名。如果您 DefectDojo 中的用户名已经与 IdP 发出的 NameID 格式一致，这种方式是合适的。 +- **统一用户名。** 确保 DefectDojo 中的用户名与您的 IdP 在 `username` 声明中发送的值完全一致。对大多数组织而言，最简单的约定是让 DefectDojo 用户名等于用户的电子邮件地址，并让 IdP 将邮箱作为 `username` 声明发送。 + +如果不确定 IdP 实际发送的内容，请启用上文的 **Enable SAML Debugging**，并在日志中查看解析后的属性。 + +### SAML 组映射没有效果——用户可以登录，但没有分配任何组 + +最常见的原因是 **Group Name Attribute** 字段与您的 IdP 实际发送的属性名称不匹配。请参见上文的[按身份提供程序划分的 Group Name Attribute](#group-name-attribute-by-identity-provider) 表格，并启用 **Enable SAML Debugging** 以查看 IdP 返回的原始属性。 diff --git a/docs/content/admin/sso/PRO__scim.it.md b/docs/content/admin/sso/PRO__scim.it.md new file mode 100644 index 0000000000..1b0c9f3da7 --- /dev/null +++ b/docs/content/admin/sso/PRO__scim.it.md @@ -0,0 +1,148 @@ +--- +title: Provisioning SCIM +description: Effettua il provisioning e il deprovisioning degli utenti di DefectDojo + Pro dal tuo identity provider +weight: 19 +audience: pro +--- + +DefectDojo Pro supporta SCIM 2.0, che consente al tuo identity provider di creare, aggiornare e disattivare direttamente gli utenti di DefectDojo. Senza SCIM, DefectDojo viene a conoscenza di un utente solo quando questo effettua l'accesso, quindi rimuovere qualcuno dal tuo identity provider blocca gli accessi futuri ma lascia attivo il suo account DefectDojo. + +SCIM è distinto dal single sign-on e lo completa. Il SSO decide chi può accedere; SCIM mantiene l'elenco stesso degli account allineato alla tua directory. La maggior parte dei clienti configura entrambi: SAML o OIDC per l'autenticazione, SCIM per il provisioning. + +La configurazione di SCIM può essere eseguita solo da un **Superuser**. + +## Cosa fa SCIM in DefectDojo + +Quando colleghi un identity provider tramite SCIM, questo può: + +* creare utenti DefectDojo quando qualcuno viene assegnato all'applicazione +* aggiornare nomi e indirizzi email quando cambiano nella directory +* disattivare gli utenti quando vengono rimossi dall'assegnazione o lasciano l'organizzazione +* creare gruppi e aggiungere o rimuovere i loro membri + +Disattivare un utente tramite SCIM fa due cose contemporaneamente. L'account viene contrassegnato come inattivo, quindi l'utente non può più accedere, e i token API DefectDojo dell'utente vengono eliminati. L'offboarding chiude quindi entrambe le porte in un unico passaggio, ed è questo il motivo principale per usare SCIM anziché affidarsi solo al proprio identity provider. + +Il record utente stesso viene conservato. I Riscontri, le note e la cronologia fanno riferimento alle persone che li hanno creati, quindi DefectDojo disattiva l'account invece di eliminarlo. Se la stessa persona ritorna, riattivarla tramite il tuo identity provider ripristina l'accesso senza alterare quella cronologia. + +## Configurazione + +1. Apri **Connect > Authorization** e seleziona **SCIM Provisioning**. SCIM è elencato insieme ai tuoi provider di accesso perché si collega allo stesso identity provider, ed è contrassegnato come **Provisioning** per distinguerlo dai provider che aggiungono un pulsante alla pagina di accesso. + +2. Seleziona **Enable SCIM Provisioning** e invia. Finché questa opzione è disattivata, gli endpoint SCIM si comportano come se non esistessero, quindi un test di connessione dal tuo identity provider segnala l'indirizzo come non trovato. + +3. Copia il **Tenant URL** mostrato nella pagina. È simile a questo: + + ``` + https://.cloud.defectdojo.com/scim/v2 + ``` + +4. Nel pannello **SCIM Tokens**, assegna al token un nome che indichi dove verrà utilizzato, ad esempio "Okta production", quindi seleziona **Generate Token**. + +5. Copia il token dalla finestra di dialogo e incollalo nel tuo identity provider. DefectDojo memorizza solo un hash del token, quindi non può essere mostrato di nuovo. Se lo perdi, generane un altro e revoca quello vecchio. + +Puoi mantenere attivo più di un token contemporaneamente. Per ruotarli, genera un nuovo token, aggiorna il tuo identity provider, quindi revoca quello vecchio. Non c'è alcun intervallo in cui il provisioning smette di funzionare. + +Il pannello dei token registra quando ciascun token è stato usato l'ultima volta, un modo rapido per verificare che il tuo identity provider stia effettivamente raggiungendo DefectDojo. + +## Okta + +1. Nella Okta Admin Console, vai su **Applications > Browse App Catalog** e aggiungi **SCIM 2.0 Test App (Header Auth)**. Se hai già un'applicazione SAML per DefectDojo, puoi invece abilitare il provisioning su quell'applicazione. + +2. Apri la scheda **Provisioning** e seleziona **Configure API Integration**. + +3. Imposta **SCIM 2.0 Base Url** sul Tenant URL copiato in precedenza. + +4. Imposta **API Token** su `Bearer `, includendo la parola `Bearer` e uno spazio singolo. Questo tipo di applicazione invia il valore testualmente come header Authorization. + +5. Seleziona **Test API Credentials**, quindi salva. + +6. In **Provisioning > To App**, abilita **Create Users**, **Update User Attributes** e **Deactivate Users**. + +7. Assegna persone o gruppi all'applicazione. Okta cerca prima ogni persona in DefectDojo in base allo username e crea un account solo se non ne trova uno, quindi chiunque abbia già un account DefectDojo viene collegato anziché duplicato. + +Per effettuare il push anche dei gruppi, apri la scheda **Push Groups** e aggiungi i gruppi che vuoi che DefectDojo replichi. Consulta [Gruppi](#groups) più sotto per sapere cosa ne fa DefectDojo. + +## Microsoft Entra ID + +1. Nell'Entra admin center, vai su **Enterprise applications > New application > Create your own application** e scegli l'opzione non-gallery. Se hai già un'applicazione per DefectDojo, usa quella. + +2. Apri **Provisioning** e imposta **Provisioning Mode** su **Automatic**. + +3. Imposta **Tenant URL** sul Tenant URL copiato in precedenza. + +4. Imposta **Secret Token** sul tuo token SCIM. Entra lo invia come bearer token, quindi qui non aggiungere la parola `Bearer`. + +5. Seleziona **Test Connection**, quindi salva. + +6. Assegna utenti e gruppi in **Users and groups**, quindi avvia il provisioning. + +Entra effettua il provisioning con un ciclo di circa 40 minuti. Durante la configurazione, **Provision on demand** applica immediatamente un singolo utente o gruppo, il che rende molto più rapido verificare che la configurazione funzioni. + +## Cosa memorizza DefectDojo + +DefectDojo mappa un piccolo insieme di attributi SCIM e ignora il resto. + +| SCIM attribute | DefectDojo field | +|---|---| +| `userName` | Username | +| `name.givenName` | Nome | +| `name.familyName` | Cognome | +| `emails` | Indirizzo email | +| `active` | Se l'account è abilitato | +| `externalId` | Conservato in modo che il tuo identity provider possa far corrispondere il record in seguito | + +Gli attributi che DefectDojo non modella, inclusi numeri di telefono, titoli professionali e l'estensione enterprise di SCIM, vengono accettati e ignorati anziché rifiutati. Mappare attributi aggiuntivi nel tuo identity provider è innocuo. + +Due attributi meritano particolare attenzione: + +**Username.** DefectDojo consente lettere, cifre e i caratteri `@ . + - _` in uno username. Se il tuo identity provider invia uno username contenente qualsiasi altro carattere, DefectDojo rifiuta quell'utente con un errore che indica il problema, invece di memorizzare silenziosamente uno username diverso. Memorizzare uno username alterato comprometterebbe la capacità del tuo provider di ritrovare in seguito l'account. + +**Indirizzo email.** SCIM non lo richiede, e DefectDojo crea comunque l'utente senza di esso. Tieni presente che le notifiche di DefectDojo, inclusi report pianificati e avvisi, non hanno alcuna destinazione per un utente privo di indirizzo email. Mappa l'attributo `emails` a meno che tu non abbia un motivo per non farlo. + +SCIM non imposta mai password e non concede mai lo stato di superuser o staff. Se il tuo identity provider è configurato per inviare password, DefectDojo le ignora. Gli utenti forniti in questo modo accedono tramite SSO. + +## Gruppi + +SCIM gestisce solo i gruppi che ha creato. I gruppi creati nell'interfaccia di DefectDojo, o arrivati tramite il group mapping di SAML o Azure AD, sono invisibili a SCIM e non possono essere rinominati, svuotati o eliminati dal tuo identity provider. + +Questo è importante perché il push dei gruppi è per natura una sostituzione completa. Se un identity provider potesse adottare un gruppo esistente, la sua sincronizzazione successiva sostituirebbe l'appartenenza accuratamente scelta di quel gruppo con qualunque cosa contenga la directory. Il push di un gruppo il cui nome è già utilizzato fallisce quindi con un messaggio che spiega il conflitto. Per cedere un gruppo esistente al tuo identity provider, rinomina uno dei due, oppure elimina il gruppo DefectDojo e lascia che il provider lo ricrei. + +All'interno di un gruppo gestito da SCIM, l'appartenenza appartiene al tuo identity provider e i ruoli appartengono a DefectDojo: + +* A un membro appena aggiunto viene assegnato il ruolo **Reader**. +* Se promuovi qualcuno a un ruolo superiore in DefectDojo, le sincronizzazioni successive non modificano quel ruolo. +* Chiunque venga aggiunto manualmente a un gruppo gestito da SCIM viene rimosso alla sincronizzazione successiva, perché l'identity provider è la fonte di verità su chi appartiene al gruppo. + +Eliminare un gruppo tramite SCIM rimuove il gruppo e le relative appartenenze. Non elimina mai le persone che ne facevano parte. + +## Protezione dell'accesso amministrativo + +Per impostazione predefinita, SCIM non disattiva un account superuser. L'errore più comune in qualsiasi configurazione di provisioning è un identity provider con un ambito più ampio del previsto, e i superuser sono il modo per rientrare in DefectDojo quando qualcosa va storto. + +Se vuoi che il tuo identity provider gestisca anche i superuser, abilita **Allow SCIM to deactivate superusers** nella pagina delle impostazioni SCIM. Anche in questo caso, DefectDojo rifiuta di disattivare l'ultimo superuser attivo rimasto, così il provisioning non può lasciare l'istanza priva di un amministratore. + +## Limitazioni + +* Un identity provider per istanza DefectDojo. +* Il filtraggio è supportato su `userName`, `displayName`, `externalId` e `id`, usando un singolo confronto di uguaglianza. Questo copre ciò che Okta ed Entra inviano quando abbinano i record. Filtri più complessi vengono rifiutati con un errore che lo indica. +* Le operazioni bulk, l'ordinamento e l'endpoint `/Me` non sono implementati. +* Le appartenenze ai gruppi vengono gestite tramite l'endpoint Groups. Inviare l'appartenenza a un gruppo su un record utente non ha alcun effetto, in linea con il comportamento di entrambi i provider. + +## Risoluzione dei problemi + +**Il test di connessione segnala "not found".** SCIM è disattivato, oppure l'istanza non ne ha la licenza. Verifica che **Enable SCIM Provisioning** sia attivo e che il tuo abbonamento includa il SSO. L'intero indirizzo SCIM si comporta come se non esistesse finché entrambe le condizioni non sono vere. + +**Il test di connessione segnala un errore di autenticazione.** Il token è errato, oppure è stato revocato. Generane uno nuovo e aggiorna il tuo identity provider. In Okta, verifica che il valore inizi con `Bearer ` e uno spazio; in Entra, verifica che non sia così. + +**Il provisioning di un utente fallisce con un errore relativo allo username.** Lo username contiene caratteri non consentiti da DefectDojo. Cambia l'attributo che il tuo identity provider mappa su `userName`, il più delle volte facendolo corrispondere all'indirizzo email dell'utente o allo user principal name. + +**Il push di un gruppo fallisce, segnalando che esiste già un gruppo con quel nome.** Un gruppo DefectDojo con quel nome è stato creato altrove. Consulta [Gruppi](#groups) più sopra. + +**Il provisioning di un membro del gruppo fallisce.** La persona non è ancora stata fornita a DefectDojo. Assegnala all'applicazione, e l'appartenenza andrà a buon fine al ciclo successivo. + +**Inizia da Diagnostics.** Le richieste SCIM rifiutate vengono registrate in **Connect > Diagnostics**, con l'endpoint, lo stato e il messaggio restituito da DefectDojo. Questo è di solito più rapido che leggere il log del tuo identity provider, ed è l'unico punto che mostra entrambi i lati dello scambio. Il provisioning riuscito non viene registrato lì; le modifiche a utenti e gruppi compaiono invece nella cronologia di audit. + +**Tutto segnala successo, ma non compare nulla in DefectDojo.** Verifica che il Tenant URL termini con `/scim/v2` senza slash finale, e che il tuo identity provider stia effettivamente raggiungendo la tua istanza. La colonna **Last Used** nel pannello SCIM Tokens mostra se è arrivata una qualche richiesta. + +**Utenti DefectDojo Pro:** se la tua istanza limita l'accesso in base all'indirizzo IP, aggiungi gli indirizzi del tuo identity provider all'allowlist del firewall prima di configurare SCIM. Consulta [Regole del firewall](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings). diff --git a/docs/content/admin/sso/PRO__scim.pt-br.md b/docs/content/admin/sso/PRO__scim.pt-br.md new file mode 100644 index 0000000000..d76309eb0b --- /dev/null +++ b/docs/content/admin/sso/PRO__scim.pt-br.md @@ -0,0 +1,148 @@ +--- +title: Provisionamento SCIM +description: Provisione e desprovisione usuários do DefectDojo Pro a partir do seu + identity provider +weight: 19 +audience: pro +--- + +O DefectDojo Pro oferece suporte ao SCIM 2.0, que permite que seu identity provider crie, atualize e desative usuários do DefectDojo diretamente. Sem ele, o DefectDojo só toma conhecimento de um usuário quando esse usuário faz login, então remover alguém do seu identity provider impede logins futuros, mas deixa a conta do DefectDojo ativa. + +O SCIM é independente do single sign-on e o complementa. O SSO decide quem pode fazer login; o SCIM mantém a própria lista de contas sincronizada com o seu diretório. A maioria dos clientes configura os dois: SAML ou OIDC para autenticação, SCIM para provisionamento. + +A configuração do SCIM só pode ser feita por um **Superuser**. + +## O que o SCIM faz no DefectDojo + +Ao conectar um identity provider via SCIM, ele pode: + +* criar usuários do DefectDojo quando alguém é atribuído ao aplicativo +* atualizar nomes e endereços de e-mail quando eles mudam no diretório +* desativar usuários quando eles são desatribuídos ou saem da organização +* criar grupos e adicionar e remover seus membros + +Desativar um usuário via SCIM faz duas coisas ao mesmo tempo. A conta é marcada como inativa, para que o usuário não possa mais fazer login, e os tokens de API do DefectDojo desse usuário são excluídos. O offboarding, portanto, fecha as duas portas em uma única etapa, que é o principal motivo para usar o SCIM em vez de depender apenas do seu identity provider. + +O registro do usuário em si é mantido. Achados, notas e o histórico fazem referência às pessoas que os criaram, então o DefectDojo desativa a conta em vez de excluí-la. Se a mesma pessoa retornar, reativá-la pelo seu identity provider restaura o acesso sem afetar esse histórico. + +## Configuração + +1. Acesse **Connect > Authorization** e selecione **SCIM Provisioning**. O SCIM aparece listado junto com seus provedores de login porque se conecta ao mesmo identity provider, e é marcado como **Provisioning** para diferenciá-lo dos provedores que colocam um botão na página de login. + +2. Marque **Enable SCIM Provisioning** e envie. Enquanto isso estiver desativado, os endpoints do SCIM se comportam como se não existissem, de modo que um teste de conexão do seu identity provider reporta o endereço como não encontrado. + +3. Copie a **Tenant URL** exibida na página. Ela se parece com isto: + + ``` + https://.cloud.defectdojo.com/scim/v2 + ``` + +4. No painel **SCIM Tokens**, dê ao token um nome que indique onde ele será usado, por exemplo "Okta production", e depois selecione **Generate Token**. + +5. Copie o token da caixa de diálogo e cole-o no seu identity provider. O DefectDojo armazena apenas um hash do token, então ele não pode ser exibido novamente. Se você o perder, gere outro e revogue o antigo. + +Você pode manter mais de um token ativo ao mesmo tempo. Para fazer o rodízio, gere um novo token, atualize seu identity provider e depois revogue o antigo. Não há nenhuma janela em que o provisionamento pare de funcionar. + +O painel de tokens registra quando cada token foi usado pela última vez, o que é uma forma rápida de confirmar que seu identity provider está realmente alcançando o DefectDojo. + +## Okta + +1. No Okta Admin Console, acesse **Applications > Browse App Catalog** e adicione **SCIM 2.0 Test App (Header Auth)**. Se você já tiver um aplicativo SAML para o DefectDojo, pode habilitar o provisionamento nesse aplicativo em vez disso. + +2. Abra a aba **Provisioning** e selecione **Configure API Integration**. + +3. Defina **SCIM 2.0 Base Url** com a Tenant URL que você copiou acima. + +4. Defina **API Token** como `Bearer `, incluindo a palavra `Bearer` e um único espaço. Esse tipo de aplicativo envia o valor literalmente como o cabeçalho Authorization. + +5. Selecione **Test API Credentials** e depois salve. + +6. Em **Provisioning > To App**, habilite **Create Users**, **Update User Attributes** e **Deactivate Users**. + +7. Atribua pessoas ou grupos ao aplicativo. O Okta primeiro procura cada pessoa no DefectDojo pelo nome de usuário e só cria uma conta quando não encontra nenhuma, então qualquer pessoa que já tenha uma conta do DefectDojo é vinculada em vez de duplicada. + +Para enviar grupos também, abra a aba **Push Groups** e adicione os grupos que você quer que o DefectDojo espelhe. Veja [Grupos](#groups) abaixo para saber o que o DefectDojo faz com eles. + +## Microsoft Entra ID + +1. No Entra admin center, acesse **Enterprise applications > New application > Create your own application** e escolha a opção non-gallery. Se você já tiver um aplicativo para o DefectDojo, use-o. + +2. Abra **Provisioning** e defina **Provisioning Mode** como **Automatic**. + +3. Defina **Tenant URL** com a Tenant URL que você copiou acima. + +4. Defina **Secret Token** com o seu token SCIM. O Entra o envia como um bearer token, então não adicione a palavra `Bearer` aqui. + +5. Selecione **Test Connection** e depois salve. + +6. Atribua usuários e grupos em **Users and groups** e inicie o provisionamento. + +O Entra provisiona em um ciclo de aproximadamente 40 minutos. Enquanto você estiver configurando, **Provision on demand** aplica um único usuário ou grupo imediatamente, o que torna muito mais rápido confirmar que a configuração funciona. + +## O que o DefectDojo armazena + +O DefectDojo mapeia um pequeno conjunto de atributos SCIM e ignora o restante. + +| Atributo SCIM | Campo do DefectDojo | +|---|---| +| `userName` | Username | +| `name.givenName` | First name | +| `name.familyName` | Last name | +| `emails` | Email address | +| `active` | Se a conta está habilitada | +| `externalId` | Mantido para que seu identity provider possa corresponder o registro posteriormente | + +Atributos que o DefectDojo não modela, incluindo números de telefone, cargos e a extensão enterprise do SCIM, são aceitos e ignorados em vez de rejeitados. Mapear atributos extras no seu identity provider é inofensivo. + +Dois atributos merecem atenção especial: + +**Username.** O DefectDojo permite letras, dígitos e os caracteres `@ . + - _` em um nome de usuário. Se o seu identity provider enviar um nome de usuário contendo qualquer outra coisa, o DefectDojo rejeita esse usuário com um erro indicando o problema, em vez de silenciosamente armazenar um nome de usuário diferente. Armazenar um nome de usuário alterado impediria que seu provedor conseguisse localizar a conta posteriormente. + +**Email address.** O SCIM não exige um, e o DefectDojo criará o usuário sem ele. Tenha em mente que as notificações do DefectDojo, incluindo relatórios agendados e alertas, não têm para onde ir para um usuário sem endereço de e-mail. Mapeie o atributo `emails`, a menos que você tenha um motivo para não fazê-lo. + +O SCIM nunca define senhas e nunca concede status de superuser ou staff. Se o seu identity provider estiver configurado para enviar senhas, o DefectDojo as ignora. Usuários provisionados dessa forma fazem login pelo SSO. + +## Grupos + +O SCIM gerencia apenas os grupos que ele criou. Grupos criados por você na interface do DefectDojo, ou que chegaram por meio do mapeamento de grupos do SAML ou do Azure AD, são invisíveis para o SCIM e não podem ser renomeados, esvaziados ou excluídos pelo seu identity provider. + +Isso importa porque o push de grupo é, por natureza, uma substituição completa. Se um identity provider pudesse adotar um grupo existente, sua próxima sincronização substituiria a associação cuidadosamente escolhida desse grupo pelo que quer que o diretório contenha. Por isso, enviar um grupo cujo nome já está em uso falha com uma mensagem explicando o conflito. Para transferir um grupo existente para o seu identity provider, renomeie um dos dois, ou exclua o grupo do DefectDojo e deixe o provedor recriá-lo. + +Dentro de um grupo gerenciado pelo SCIM, a associação pertence ao seu identity provider e as roles pertencem ao DefectDojo: + +* Um membro recém-adicionado recebe a role **Reader**. +* Se você promover alguém a uma role superior no DefectDojo, sincronizações posteriores não alteram essa role. +* Qualquer pessoa adicionada manualmente a um grupo gerenciado pelo SCIM é removida na próxima sincronização, porque o identity provider é a fonte da verdade sobre quem pertence ao grupo. + +Excluir um grupo via SCIM remove o grupo e suas associações. Isso nunca exclui as pessoas que faziam parte dele. + +## Protegendo o acesso de administrador + +Por padrão, o SCIM não desativa uma conta de superuser. A falha comum em qualquer configuração de provisionamento é um identity provider com escopo mais amplo do que o pretendido, e os superusers são a forma de você voltar a acessar o DefectDojo quando algo dá errado. + +Se você quiser que seu identity provider também gerencie superusers, habilite **Allow SCIM to deactivate superusers** na página de configurações do SCIM. Mesmo assim, o DefectDojo se recusa a desativar o último superuser ativo restante, de modo que o provisionamento não pode deixar a instância sem um administrador. + +## Limitações + +* Um identity provider por instância do DefectDojo. +* A filtragem é suportada em `userName`, `displayName`, `externalId` e `id`, usando uma única comparação de igualdade. Isso cobre o que o Okta e o Entra enviam ao corresponder registros. Filtros mais complexos são rejeitados com um erro informando isso. +* Operações em massa, ordenação e o endpoint `/Me` não estão implementados. +* As associações a grupos são gerenciadas por meio do endpoint Groups. Enviar a associação a grupo em um registro de usuário não tem efeito, o que corresponde ao comportamento dos dois provedores. + +## Solução de problemas + +**O teste de conexão reporta "not found".** O SCIM está desativado, ou a instância não tem licença para ele. Verifique se **Enable SCIM Provisioning** está ativado e se a sua assinatura inclui SSO. Todo o endereço do SCIM se comporta como se não existisse até que ambas as condições sejam verdadeiras. + +**O teste de conexão reporta uma falha de autenticação.** O token está errado ou foi revogado. Gere um novo e atualize seu identity provider. No Okta, verifique se o valor começa com `Bearer ` e um espaço; no Entra, verifique se não começa. + +**Um usuário falha ao ser provisionado com um erro sobre o nome de usuário.** O nome de usuário contém caracteres que o DefectDojo não permite. Altere o atributo que seu identity provider mapeia para `userName`, geralmente para o endereço de e-mail do usuário ou o user principal name. + +**Um grupo falha ao ser enviado, informando que já existe um grupo com esse nome.** Um grupo do DefectDojo com esse nome foi criado em outro lugar. Veja [Grupos](#groups) acima. + +**Um membro de grupo falha ao ser provisionado.** A pessoa ainda não foi provisionada no DefectDojo. Atribua-a ao aplicativo, e a associação terá sucesso no próximo ciclo. + +**Comece pelo Diagnostics.** As requisições SCIM recusadas são registradas em **Connect > Diagnostics**, com o endpoint, o status e a mensagem que o DefectDojo enviou de volta. Isso geralmente é mais rápido do que ler o log do seu identity provider, e é o único lugar que mostra os dois lados da troca. O provisionamento bem-sucedido não é registrado ali; as alterações em usuários e grupos aparecem no histórico de auditoria. + +**Tudo reporta sucesso, mas nada aparece no DefectDojo.** Verifique se a Tenant URL termina em `/scim/v2` sem barra final, e se o seu identity provider está realmente alcançando sua instância. A coluna **Last Used** no painel SCIM Tokens mostra se alguma requisição chegou. + +**Usuários do DefectDojo Pro:** se a sua instância restringe o acesso por endereço IP, adicione os endereços do seu identity provider à allowlist do firewall antes de configurar o SCIM. Veja [Firewall Rules](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings). diff --git a/docs/content/admin/sso/PRO__scim.zh-hans.md b/docs/content/admin/sso/PRO__scim.zh-hans.md new file mode 100644 index 0000000000..53fc278c97 --- /dev/null +++ b/docs/content/admin/sso/PRO__scim.zh-hans.md @@ -0,0 +1,147 @@ +--- +title: SCIM 预配 +description: 通过身份提供程序为 DefectDojo Pro 用户进行预配和取消预配 +weight: 19 +audience: pro +--- + +DefectDojo Pro 支持 SCIM 2.0，可让您的身份提供程序直接创建、更新和停用 DefectDojo 用户。如果没有 SCIM，DefectDojo 只有在用户登录时才能获知该用户的存在，因此从身份提供程序中移除某人只会阻止其后续登录，但其 DefectDojo 账户仍会保持活动状态。 + +SCIM 与单点登录相互独立又互为补充。SSO 决定谁可以登录；SCIM 则使账户列表本身与您的目录保持同步。大多数客户会同时配置两者：使用 SAML 或 OIDC 进行身份验证，使用 SCIM 进行预配。 + +SCIM 配置只能由**超级用户**执行。 + +## SCIM 在 DefectDojo 中的作用 + +当您通过 SCIM 连接身份提供程序后，它可以： + +* 在有人被分配该应用程序时创建 DefectDojo 用户 +* 在目录中的姓名和电子邮件地址发生变化时进行更新 +* 在用户被取消分配或离开组织时将其停用 +* 创建组，并添加或移除组成员 + +通过 SCIM 停用用户会同时完成两件事：账户被标记为不活动，用户将无法再登录，同时该用户的 DefectDojo API 令牌也会被删除。因此，离职处理可以一步同时关闭这两扇门，这也是相较于仅依赖身份提供程序而言，使用 SCIM 的主要原因。 + +用户记录本身会被保留。发现项、备注和历史记录都会引用创建它们的人员，因此 DefectDojo 会停用账户而不是删除它。如果同一个人后来回归，通过身份提供程序重新激活即可恢复访问权限，而不会影响这些历史记录。 + +## 设置 + +1. 打开 **Connect > Authorization** 并选择 **SCIM Provisioning**。SCIM 与您的登录提供程序列在一起，因为它连接到同一个身份提供程序，并被标记为 **Provisioning**，以便与那些会在登录页面上添加按钮的提供程序区分开来。 + +2. 勾选 **Enable SCIM Provisioning** 并提交。在此选项关闭期间，SCIM 端点表现得如同不存在一样，因此来自您身份提供程序的连接测试会报告该地址未找到。 + +3. 复制页面上显示的 **Tenant URL**，格式如下： + + ``` + https://.cloud.defectdojo.com/scim/v2 + ``` + +4. 在 **SCIM Tokens** 面板中，为令牌起一个能说明其用途的名称，例如 "Okta production"，然后选择 **Generate Token**。 + +5. 从对话框中复制该令牌，并粘贴到您的身份提供程序中。DefectDojo 只存储该令牌的哈希值，因此无法再次显示。如果丢失，请生成新令牌并撤销旧令牌。 + +您可以同时保留多个有效令牌。若要轮换令牌，请先生成新令牌、更新您的身份提供程序，然后再撤销旧令牌。这样就不会出现预配功能中断的窗口期。 + +令牌面板会记录每个令牌最后一次被使用的时间，这是确认您的身份提供程序是否确实在访问 DefectDojo 的快捷方法。 + +## Okta + +1. 在 Okta 管理控制台中，进入 **Applications > Browse App Catalog**，添加 **SCIM 2.0 Test App (Header Auth)**。如果您已经为 DefectDojo 配置了 SAML 应用程序，也可以直接在该应用程序上启用预配功能。 + +2. 打开 **Provisioning** 选项卡，选择 **Configure API Integration**。 + +3. 将 **SCIM 2.0 Base Url** 设置为上文复制的 Tenant URL。 + +4. 将 **API Token** 设置为 `Bearer `，包括单词 `Bearer` 和一个空格。此应用类型会将该值原样作为 Authorization 头发送。 + +5. 选择 **Test API Credentials**，然后保存。 + +6. 在 **Provisioning > To App** 下，启用 **Create Users**、**Update User Attributes** 和 **Deactivate Users**。 + +7. 将人员或组分配给该应用程序。Okta 会先按用户名在 DefectDojo 中查找每个人，只有在找不到时才会创建账户，因此已拥有 DefectDojo 账户的用户会被关联，而不会被重复创建。 + +若要同时推送组，请打开 **Push Groups** 选项卡，添加您希望 DefectDojo 镜像的组。有关 DefectDojo 如何处理这些组，请参见下文的[组](#groups)。 + +## Microsoft Entra ID + +1. 在 Entra 管理中心，进入 **Enterprise applications > New application > Create your own application**，选择非目录（non-gallery）选项。如果您已经为 DefectDojo 配置了应用程序，直接使用该应用程序即可。 + +2. 打开 **Provisioning**，将 **Provisioning Mode** 设置为 **Automatic**。 + +3. 将 **Tenant URL** 设置为上文复制的 Tenant URL。 + +4. 将 **Secret Token** 设置为您的 SCIM 令牌。Entra 会将其作为 bearer 令牌发送，因此这里不要添加单词 `Bearer`。 + +5. 选择 **Test Connection**，然后保存。 + +6. 在 **Users and groups** 下分配用户和组，并启动预配。 + +Entra 的预配周期约为 40 分钟。在配置过程中，**Provision on demand** 可以立即应用单个用户或组，这能让您更快地确认配置是否生效。 + +## DefectDojo 存储的内容 + +DefectDojo 只映射一小部分 SCIM 属性，其余的会被忽略。 + +| SCIM attribute | DefectDojo field | +|---|---| +| `userName` | 用户名 | +| `name.givenName` | 名 | +| `name.familyName` | 姓 | +| `emails` | 电子邮件地址 | +| `active` | 账户是否启用 | +| `externalId` | 保留下来，供您的身份提供程序日后匹配该记录 | + +DefectDojo 未建模的属性，包括电话号码、职位名称以及 SCIM 企业扩展，会被接受并忽略，而不是被拒绝。在您的身份提供程序中映射额外的属性是无害的。 + +有两个属性值得特别关注： + +**用户名（Username）。** DefectDojo 的用户名只允许包含字母、数字以及字符 `@ . + - _`。如果您的身份提供程序发送的用户名包含其他字符，DefectDojo 会拒绝该用户，并给出说明问题的错误信息，而不是悄悄存储一个不同的用户名。存储被更改后的用户名会导致您的提供程序之后无法找到该账户。 + +**电子邮件地址（Email address）。** SCIM 并不要求提供电子邮件地址，DefectDojo 也会在没有它的情况下创建用户。但请注意，对于没有电子邮件地址的用户，DefectDojo 的通知（包括计划报告和告警）将无处可发。除非有特殊原因，否则请映射 `emails` 属性。 + +SCIM 从不设置密码，也从不授予超级用户或职员（staff）身份。如果您的身份提供程序配置为发送密码，DefectDojo 会忽略它们。以这种方式预配的用户通过 SSO 登录。 + +## 组 + +SCIM 只管理由它创建的组。您在 DefectDojo 界面中创建的组，或通过 SAML 或 Azure AD 组映射生成的组，对 SCIM 而言是不可见的，您的身份提供程序无法重命名、清空或删除这些组。 + +这一点很重要，因为组推送本质上是一次完整替换。如果身份提供程序可以"接管"一个已有的组，那么它下一次同步时就会用目录中的内容替换掉该组原本精心维护的成员关系。因此，推送一个名称已被占用的组会失败，并显示说明冲突的消息。若要将某个现有组交给您的身份提供程序管理，请将两者之一重命名，或者删除 DefectDojo 中的组，让提供程序重新创建它。 + +在一个由 SCIM 管理的组内，成员关系归属于您的身份提供程序，而角色归属于 DefectDojo： + +* 新添加的成员会被赋予 **Reader** 角色。 +* 如果您在 DefectDojo 中将某人提升为更高的角色，后续的同步不会改动该角色。 +* 任何被手动添加到 SCIM 管理组中的人，都会在下一次同步时被移除，因为身份提供程序才是"谁属于该组"的权威来源。 + +通过 SCIM 删除一个组会移除该组及其成员关系，但绝不会删除组内的人员本身。 + +## 保护管理员账户的访问权限 + +默认情况下，SCIM 不会停用超级用户账户。任何预配方案中最常见的故障，都是身份提供程序的授权范围超出预期，而超级用户正是在出现问题时用来重新进入 DefectDojo 的手段。 + +如果您希望身份提供程序也能管理超级用户，请在 SCIM 设置页面启用 **Allow SCIM to deactivate superusers**。即便启用该选项，DefectDojo 仍会拒绝停用最后一个仍处于活动状态的超级用户，因此预配操作不可能让实例失去管理员。 + +## 限制 + +* 每个 DefectDojo 实例仅支持一个身份提供程序。 +* 过滤功能支持基于 `userName`、`displayName`、`externalId` 和 `id` 的单一相等比较，这涵盖了 Okta 和 Entra 在匹配记录时发送的内容。更复杂的过滤条件会被拒绝，并返回相应的错误信息。 +* 未实现批量操作、排序以及 `/Me` 端点。 +* 组成员关系通过 Groups 端点进行管理。在用户记录上发送组成员信息不会产生任何效果，这与两家提供程序的实际行为一致。 + +## 故障排查 + +**连接测试报告"未找到"。** SCIM 已关闭，或该实例未获得相应许可。请检查 **Enable SCIM Provisioning** 是否已开启，以及您的订阅是否包含 SSO。在两者都满足之前，整个 SCIM 地址都会表现得如同不存在一样。 + +**连接测试报告身份验证失败。** 令牌错误，或已被撤销。请生成新令牌并更新您的身份提供程序。在 Okta 中，请检查该值是否以 `Bearer ` 及一个空格开头；在 Entra 中，请检查它是否不包含该前缀。 + +**某用户预配失败，并报告与用户名相关的错误。** 用户名中包含 DefectDojo 不允许的字符。请更改您的身份提供程序映射到 `userName` 的属性，最常见的做法是改用该用户的电子邮件地址或用户主体名称。 + +**某个组推送失败，报告已存在同名的组。** 说明该名称的 DefectDojo 组是在别处创建的。请参见上文的[组](#groups)。 + +**某个组成员预配失败。** 说明该人员尚未被预配到 DefectDojo。请将其分配给该应用程序，其成员关系会在下一个周期成功建立。 + +**从 Diagnostics 开始排查。** 被拒绝的 SCIM 请求会记录在 **Connect > Diagnostics** 下，包含端点、状态以及 DefectDojo 返回的消息。这通常比查看您的身份提供程序日志更快，也是唯一能同时看到交互双方情况的位置。成功的预配不会记录在此处；用户和组的变更会显示在审计历史中。 + +**一切都显示成功，但 DefectDojo 中却什么都没出现。** 请检查 Tenant URL 是否以 `/scim/v2` 结尾且没有多余的斜杠，并确认您的身份提供程序确实能够访问您的实例。SCIM Tokens 面板中的 **Last Used** 列会显示是否已收到任何请求。 + +**DefectDojo Pro 用户：** 如果您的实例按 IP 地址限制访问，请在配置 SCIM 之前，将您身份提供程序的地址添加到防火墙白名单中。参见[防火墙规则](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings)。 diff --git a/docs/content/admin/sso/_index.it.md b/docs/content/admin/sso/_index.it.md new file mode 100644 index 0000000000..253f1585a3 --- /dev/null +++ b/docs/content/admin/sso/_index.it.md @@ -0,0 +1,76 @@ +--- +title: Single Sign-On +description: DefectDojo Pro supporta SAML e una vasta gamma di provider OAuth per + il Single Sign-On +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2026-04-30 00:00:00+00:00 +draft: false +weight: 8 +collapsed: true +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +pro-feature: true +aliases: +- /it/admin/user_management/configure_sso/ +- /it/admin/sso/os__saml/ +- /it/admin/sso/os__auth0/ +- /it/admin/sso/os__azure_ad/ +- /it/admin/sso/os__github_enterprise/ +- /it/admin/sso/os__gitlab/ +- /it/admin/sso/os__google/ +- /it/admin/sso/os__keycloak/ +- /it/admin/sso/os__oidc/ +- /it/admin/sso/os__okta/ +- /it/admin/sso/os__remote_user/ +--- + +Il Single Sign-On è una funzionalità di **DefectDojo Pro**. A partire da DefectDojo 3.0, l'intera superficie SSO — SAML, OIDC e i provider OAuth inclusi — è disponibile solo in DefectDojo Pro. DefectDojo open source utilizza l'accesso locale con username/password e il flusso di reimpostazione della password. + +Se utilizzi DefectDojo open source e desideri il SSO, dovrai passare a [DefectDojo Pro](https://defectdojo.com); la migrazione è descritta nelle [note di aggiornamento della 3.0](/releases/os_upgrading/3.0/#sso-providers-are-available-in-defectdojo-pro-only). Gli account utente e le appartenenze ai gruppi esistenti vengono preservati durante l'aggiornamento. Per il controllo degli accessi su DefectDojo open source, consulta la pagina [Utenti autorizzati](/admin/user_management/os__authorized_users/). + +## Visualizzare cosa è configurato + +**[Authorization Connectors](/admin/sso/pro__authorization_connectors/)** elenca in un'unica pagina tutti i provider supportati — quali sono configurati, quali sono abilitati e quale protocollo utilizza ciascuno — e ti porta direttamente al modulo di impostazioni di ognuno di essi. Parti da lì se vuoi conoscere lo stato di questa istanza piuttosto che configurare un provider specifico. + +## Provider SSO supportati (DefectDojo Pro) + +DefectDojo Pro supporta SAML e i seguenti provider OAuth. Ogni guida illustra la configurazione lato provider e la corrispondente configurazione nell'interfaccia **Enterprise Settings** di Pro. + +* **[Auth0](/admin/sso/pro__auth0/)** +* **[Azure Active Directory](/admin/sso/pro__azure_ad/)** +* **[GitHub Enterprise](/admin/sso/pro__github_enterprise/)** +* **[GitLab](/admin/sso/pro__gitlab/)** +* **[Google](/admin/sso/pro__google/)** +* **[KeyCloak](/admin/sso/pro__keycloak/)** +* **[Okta](/admin/sso/pro__okta/)** +* **[OIDC (OpenID Connect)](/admin/sso/pro__oidc/)** +* **[SAML](/admin/sso/pro__saml/)** +* **[LDAP](/admin/sso/pro__ldap/)** + +## Provisioning degli utenti dalla tua directory (DefectDojo Pro) + +I provider sopra indicati decidono chi può accedere. **[SCIM Provisioning](/admin/sso/pro__scim/)** mantiene l'elenco degli account allineato alla tua directory, così gli utenti vengono creati quando entrano a far parte dell'organizzazione, aggiornati quando cambiano i loro dati e disattivati (insieme ai loro token API) quando la lasciano. + +La configurazione del SSO in DefectDojo Pro può essere eseguita solo da un **Superuser**. + +**Utenti DefectDojo Pro:** aggiungi gli indirizzi IP dei tuoi servizi SAML o SSO alla whitelist del Firewall prima di configurare il SSO. Consulta [Regole del firewall](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings) per maggiori informazioni. + +## Disabilitare l'accesso con Username / Password + +Una volta configurato il SSO in DefectDojo Pro, potresti voler disabilitare il tradizionale modulo di accesso con username/password. Deseleziona **Allow Login via Username and Password** in **Enterprise Settings > Login Settings**. + +![image](images/pro_login_settings.png) + +### Accesso di riserva + +Se la tua integrazione SSO smette di funzionare, puoi sempre tornare al modulo di accesso standard aggiungendo quanto segue al tuo URL di DefectDojo: + +`/login?force_login_form` + +Ti consigliamo di mantenere almeno un account amministratore con username e password configurati come riserva. diff --git a/docs/content/admin/sso/_index.pt-br.md b/docs/content/admin/sso/_index.pt-br.md new file mode 100644 index 0000000000..db2b0dbd02 --- /dev/null +++ b/docs/content/admin/sso/_index.pt-br.md @@ -0,0 +1,76 @@ +--- +title: Single Sign-On +description: O DefectDojo Pro oferece suporte a SAML e a uma variedade de provedores + OAuth para Single Sign-On +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2026-04-30 00:00:00+00:00 +draft: false +weight: 8 +collapsed: true +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +pro-feature: true +aliases: +- /pt-br/admin/user_management/configure_sso/ +- /pt-br/admin/sso/os__saml/ +- /pt-br/admin/sso/os__auth0/ +- /pt-br/admin/sso/os__azure_ad/ +- /pt-br/admin/sso/os__github_enterprise/ +- /pt-br/admin/sso/os__gitlab/ +- /pt-br/admin/sso/os__google/ +- /pt-br/admin/sso/os__keycloak/ +- /pt-br/admin/sso/os__oidc/ +- /pt-br/admin/sso/os__okta/ +- /pt-br/admin/sso/os__remote_user/ +--- + +Single Sign-On é um recurso do **DefectDojo Pro**. A partir do DefectDojo 3.0, a superfície de SSO — SAML, OIDC e os provedores OAuth integrados — está disponível somente no DefectDojo Pro. O DefectDojo open-source usa login local por nome de usuário/senha e o fluxo de redefinição de senha. + +Se você estiver usando o DefectDojo open-source e quiser SSO, será necessário migrar para o [DefectDojo Pro](https://defectdojo.com); a migração está descrita nas [notas de atualização do 3.0](/releases/os_upgrading/3.0/#sso-providers-are-available-in-defectdojo-pro-only). As contas de usuário e associações de grupo existentes são preservadas na atualização. Para controle de acesso no DefectDojo open-source, veja a página [Usuários Autorizados](/admin/user_management/os__authorized_users/). + +## Vendo o que está configurado + +**[Authorization Connectors](/admin/sso/pro__authorization_connectors/)** lista todos os provedores suportados em uma única página — quais estão configurados, quais estão habilitados e qual protocolo cada um utiliza — e leva você diretamente ao formulário de configurações de qualquer um deles. Comece por ali se quiser saber o estado desta instância, em vez de configurar um provedor específico. + +## Provedores de SSO suportados (DefectDojo Pro) + +O DefectDojo Pro oferece suporte a SAML e aos seguintes provedores OAuth. Cada guia percorre a configuração no lado do provedor e a configuração correspondente na interface **Enterprise Settings** do Pro. + +* **[Auth0](/admin/sso/pro__auth0/)** +* **[Azure Active Directory](/admin/sso/pro__azure_ad/)** +* **[GitHub Enterprise](/admin/sso/pro__github_enterprise/)** +* **[GitLab](/admin/sso/pro__gitlab/)** +* **[Google](/admin/sso/pro__google/)** +* **[KeyCloak](/admin/sso/pro__keycloak/)** +* **[Okta](/admin/sso/pro__okta/)** +* **[OIDC (OpenID Connect)](/admin/sso/pro__oidc/)** +* **[SAML](/admin/sso/pro__saml/)** +* **[LDAP](/admin/sso/pro__ldap/)** + +## Provisionando usuários a partir do seu diretório (DefectDojo Pro) + +Os provedores acima decidem quem pode fazer login. **[SCIM Provisioning](/admin/sso/pro__scim/)** mantém a própria lista de contas sincronizada com o seu diretório, de modo que os usuários sejam criados quando entram, atualizados quando seus dados mudam e desativados (junto com seus tokens de API) quando saem. + +A configuração de SSO no DefectDojo Pro só pode ser feita por um **Superuser**. + +**Usuários do DefectDojo Pro:** adicione os endereços IP dos seus serviços SAML ou SSO à whitelist do Firewall antes de configurar o SSO. Veja [Firewall Rules](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings) para mais informações. + +## Desabilitando o login por Nome de usuário / Senha + +Depois que o SSO estiver configurado no DefectDojo Pro, você pode querer desabilitar o formulário tradicional de login por nome de usuário/senha. Desmarque **Allow Login via Username and Password** em **Enterprise Settings > Login Settings**. + +![image](images/pro_login_settings.png) + +### Fallback de login + +Se a sua integração de SSO parar de funcionar, você sempre pode voltar ao formulário de login padrão adicionando o seguinte à URL do seu DefectDojo: + +`/login?force_login_form` + +Recomendamos manter pelo menos uma conta de administrador com nome de usuário e senha configurados como fallback. diff --git a/docs/content/admin/sso/_index.zh-hans.md b/docs/content/admin/sso/_index.zh-hans.md new file mode 100644 index 0000000000..2cc085873e --- /dev/null +++ b/docs/content/admin/sso/_index.zh-hans.md @@ -0,0 +1,75 @@ +--- +title: 单点登录 +description: DefectDojo Pro 支持通过 SAML 和多种 OAuth 提供程序实现单点登录 +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2026-04-30 00:00:00+00:00 +draft: false +weight: 8 +collapsed: true +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +pro-feature: true +aliases: +- /zh-hans/admin/user_management/configure_sso/ +- /zh-hans/admin/sso/os__saml/ +- /zh-hans/admin/sso/os__auth0/ +- /zh-hans/admin/sso/os__azure_ad/ +- /zh-hans/admin/sso/os__github_enterprise/ +- /zh-hans/admin/sso/os__gitlab/ +- /zh-hans/admin/sso/os__google/ +- /zh-hans/admin/sso/os__keycloak/ +- /zh-hans/admin/sso/os__oidc/ +- /zh-hans/admin/sso/os__okta/ +- /zh-hans/admin/sso/os__remote_user/ +--- + +单点登录是 **DefectDojo Pro** 的功能。从 DefectDojo 3.0 起，SSO 相关能力——SAML、OIDC 以及内置的 OAuth 提供程序——仅在 DefectDojo Pro 中提供。开源版 DefectDojo 使用本地用户名/密码登录及密码重置流程。 + +如果您正在运行开源版 DefectDojo 并希望使用 SSO，需要切换到 [DefectDojo Pro](https://defectdojo.com)；迁移方法请参见 [3.0 升级说明](/releases/os_upgrading/3.0/#sso-providers-are-available-in-defectdojo-pro-only)。升级后，现有的用户账户和组成员关系都会被保留。有关开源版 DefectDojo 的访问控制，请参见[已授权用户](/admin/user_management/os__authorized_users/)页面。 + +## 查看当前配置 + +**[Authorization Connectors](/admin/sso/pro__authorization_connectors/)** 会在一个页面中列出所有受支持的提供程序——哪些已配置、哪些已启用、各自使用什么协议——并可直接跳转到其中任意一个的设置表单。如果您想了解此实例的当前状态，而不是配置某个特定的提供程序，可以从这里开始。 + +## 受支持的 SSO 提供程序（DefectDojo Pro） + +DefectDojo Pro 支持 SAML 以及以下 OAuth 提供程序。每份指南都会介绍提供程序端的设置步骤，以及在 Pro 版 **Enterprise Settings** 界面中对应的配置方式。 + +* **[Auth0](/admin/sso/pro__auth0/)** +* **[Azure Active Directory](/admin/sso/pro__azure_ad/)** +* **[GitHub Enterprise](/admin/sso/pro__github_enterprise/)** +* **[GitLab](/admin/sso/pro__gitlab/)** +* **[Google](/admin/sso/pro__google/)** +* **[KeyCloak](/admin/sso/pro__keycloak/)** +* **[Okta](/admin/sso/pro__okta/)** +* **[OIDC (OpenID Connect)](/admin/sso/pro__oidc/)** +* **[SAML](/admin/sso/pro__saml/)** +* **[LDAP](/admin/sso/pro__ldap/)** + +## 通过目录预配用户（DefectDojo Pro） + +上述提供程序决定谁可以登录。**[SCIM Provisioning](/admin/sso/pro__scim/)** 则使账户列表本身与您的目录保持同步，因此用户在加入时会被创建，在信息变更时会被更新，在离开时会被停用（同时其 API 令牌也会被删除）。 + +DefectDojo Pro 中的 SSO 配置只能由**超级用户**执行。 + +**DefectDojo Pro 用户：** 在设置 SSO 之前，请先将您的 SAML 或 SSO 服务的 IP 地址添加到防火墙白名单中。更多信息请参见[防火墙规则](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings)。 + +## 禁用用户名/密码登录 + +在 DefectDojo Pro 中配置好 SSO 后，您可能希望禁用传统的用户名/密码登录表单。在 **Enterprise Settings > Login Settings** 下取消勾选 **Allow Login via Username and Password**。 + +![image](images/pro_login_settings.png) + +### 登录回退方式 + +如果您的 SSO 集成出现故障，您始终可以通过在 DefectDojo URL 后追加以下内容，返回标准登录表单： + +`/login?force_login_form` + +我们建议至少保留一个配置了用户名和密码的管理员账户，作为回退方案。 diff --git a/docs/content/admin/user_management/OS__audit_logging.it.md b/docs/content/admin/user_management/OS__audit_logging.it.md new file mode 100644 index 0000000000..04f2576b85 --- /dev/null +++ b/docs/content/admin/user_management/OS__audit_logging.it.md @@ -0,0 +1,17 @@ +--- +title: Log di audit +description: Accedi ai log di audit per gli oggetti di DefectDojo +weight: 1 +audience: opensource +aliases: +- /it/en/customize_dojo/user_management/audit_logging +--- + +I log di audit di DefectDojo sono accessibili in diversi modi. + +## Log dei singoli oggetti +* Ogni oggetto di DefectDojo ha una Object History associata, accessibile tramite l'interfaccia utente. Queste cronologie vengono registrate per Asset, Engagement, Test, Riscontri ed Endpoint, oltre che per le Accettazioni del rischio. + +Nell'interfaccia Classic (Open-Source), i Log degli oggetti si trovano nel menu ☰ (hamburger) nella vista di un oggetto. + +![immagine](images/auditlogs_ss6.png) diff --git a/docs/content/admin/user_management/OS__audit_logging.pt-br.md b/docs/content/admin/user_management/OS__audit_logging.pt-br.md new file mode 100644 index 0000000000..5b4c37e46f --- /dev/null +++ b/docs/content/admin/user_management/OS__audit_logging.pt-br.md @@ -0,0 +1,17 @@ +--- +title: Logs de Auditoria +description: Acesse os logs de auditoria dos objetos do DefectDojo +weight: 1 +audience: opensource +aliases: +- /pt-br/en/customize_dojo/user_management/audit_logging +--- + +Os logs de auditoria do DefectDojo podem ser acessados de algumas formas diferentes. + +## Logs individuais de objeto +* Cada objeto do DefectDojo tem um Histórico do Objeto associado, que pode ser acessado pela interface. Esses históricos são registrados para Ativos, Engajamentos, Testes, Achados e Endpoints, além das Aceitações de risco. + +Na interface Clássica (Open Source), os Logs de Objeto ficam no menu ☰ hambúrguer na visualização de um objeto. + +![image](images/auditlogs_ss6.png) diff --git a/docs/content/admin/user_management/OS__audit_logging.zh-hans.md b/docs/content/admin/user_management/OS__audit_logging.zh-hans.md new file mode 100644 index 0000000000..2604a8a9f7 --- /dev/null +++ b/docs/content/admin/user_management/OS__audit_logging.zh-hans.md @@ -0,0 +1,17 @@ +--- +title: 审计日志 +description: 访问 DefectDojo 对象的审计日志 +weight: 1 +audience: opensource +aliases: +- /zh-hans/en/customize_dojo/user_management/audit_logging +--- + +DefectDojo 的审计日志可以通过几种不同的方式访问。 + +## 单个对象的日志 +* DefectDojo 的每个对象都有一份关联的对象历史记录（Object History），可通过 UI 访问。系统会为资产（Assets）、测试活动（Engagements）、测试（Tests）、发现项（Findings）和端点（Endpoints），以及风险接受（Risk Acceptances）记录这些历史。 + +在经典（开源）用户界面中，可以在对象视图内的 ☰ 汉堡菜单下找到对象日志。 + +![图片](images/auditlogs_ss6.png) diff --git a/docs/content/admin/user_management/OS__authorized_users.it.md b/docs/content/admin/user_management/OS__authorized_users.it.md new file mode 100644 index 0000000000..8bceb0d16c --- /dev/null +++ b/docs/content/admin/user_management/OS__authorized_users.it.md @@ -0,0 +1,61 @@ +--- +title: Permessi Open Source +description: Come viene concesso l'accesso a Prodotti e Tipi di prodotto in DefectDojo + open source +weight: 1 +audience: opensource +--- + +DefectDojo open source controlla l'accesso a Prodotti e Tipi di prodotto con il modello **Authorized Users**. Ogni Prodotto e Tipo di prodotto ha un pannello Authorized Users che elenca le persone che possono vedere quel record e i dati annidati al suo interno. + +Se utilizzi DefectDojo Pro, questo articolo non si applica alla tua installazione — Pro utilizza un sistema basato sui ruoli più ricco, descritto in [Permessi in DefectDojo](../about_perms_and_roles/). + +## Come viene concesso l'accesso + +Esistono due elenchi, ed è sufficiente che un utente compaia in uno solo di essi per ottenere l'accesso: + +- **L'elenco Authorized Users di un Prodotto** concede l'accesso a quel singolo Prodotto, oltre a tutto ciò che è annidato al suo interno (i suoi Engagement, Test, Riscontri ed Endpoint). +- **L'elenco Authorized Users di un Tipo di prodotto** concede l'accesso al Tipo di prodotto stesso **e si propaga a cascata a ogni Prodotto sottostante**. Un utente autorizzato su un Tipo di prodotto non deve essere aggiunto anche a ogni Prodotto figlio — è già coperto. + +Non esistono ruoli, gruppi o ruoli globali. Un utente è presente nell'elenco (oppure è un superuser/membro dello staff — vedi sotto), oppure non può vedere il Prodotto. + +## Superuser e staff bypassano gli elenchi + +Gli utenti contrassegnati come **superuser** o **staff** in DefectDojo possono vedere e agire su ogni Prodotto e Tipo di prodotto indipendentemente dagli elenchi Authorized Users. Gli elenchi esistono per concedere l'accesso agli utenti non staff; non limitano lo staff o i superuser. + +Il primo account creato su un'installazione nuova di DefectDojo è automaticamente un superuser. + +## Chi può modificare gli elenchi + +Solo gli utenti **superuser** o **staff** vedono i controlli per aggiungere o rimuovere persone da un pannello Authorized Users. Chiunque altro abbia accesso a un Prodotto o Tipo di prodotto vede il pannello come un elenco di sola lettura — utile per scoprire chi altro fa parte del team, ma non per modificarne l'appartenenza. + +## Dove si trova il pannello + +Il pannello Authorized Users compare in due pagine nell'interfaccia classica: + +- La **pagina dei dettagli del Prodotto** ha un pannello Authorized Users per quel Prodotto. Supporta due azioni per gli utenti staff: + - **Aggiungere un utente all'elenco Authorized Users del Prodotto** + - **Rimuovere un utente dall'elenco Authorized Users del Prodotto** +- La **pagina dei dettagli del Tipo di prodotto** ha un pannello Authorized Users per quel Tipo di prodotto, con le due azioni corrispondenti: + - **Aggiungere un utente all'elenco Authorized Users del Tipo di prodotto** + - **Rimuovere un utente dall'elenco Authorized Users del Tipo di prodotto** + +Quando rimuovi un utente dall'elenco di un Tipo di prodotto, viene rimossa anche la cascata — perde l'accesso a ogni Prodotto figlio, a meno che non sia ancora presente nell'elenco di uno specifico Prodotto, oppure sia staff/superuser. + +## Scegliere tra accesso a livello di Prodotto o di Tipo di prodotto + +Alcune regole pratiche: + +- Se una persona deve vedere ogni Prodotto sotto una categoria (ad esempio, ogni Prodotto di proprietà di un determinato team), inseriscila nell'elenco del **Tipo di prodotto** e lascia che sia la cascata a occuparsi del resto. +- Se una persona deve vedere solo uno specifico Prodotto, inseriscila nell'elenco di quel **Prodotto**. +- Se ti accorgi di aggiungere la stessa persona a molti singoli Prodotti sotto un unico Tipo di prodotto, è un segnale che dovresti invece aggiungerla al Tipo di prodotto. + +## Provenendo da una versione precedente di DefectDojo + +DefectDojo open source è tornato al modello Authorized Users nella versione 3.0. Se stai eseguendo l'aggiornamento da una release che utilizzava il sistema Members / Groups / Global Roles, il tuo accesso esistente viene riportato automaticamente in Authorized Users dall'aggiornamento — non è necessaria alcuna mappatura manuale. + +L'aggiornamento include un comando di gestione di sola lettura, `preview_legacy_authorization_migration`, che riassume cosa cambierebbe un aggiornamento a fronte di una copia del tuo database. Il flusso di lavoro consigliato è installare la 3.0 in un ambiente di staging con uno snapshot della produzione, eseguire il comando, rivedere il riepilogo e quindi aggiornare la produzione. + +Se ti stai muovendo nella direzione opposta — da open source a DefectDojo Pro — Pro include un comando `reconcile_authorized_users_to_rbac` che riporta l'accesso Authorized Users nell'RBAC di Pro. Supporta `--dry-run` ed è idempotente. + +Per maggiori dettagli su entrambi i percorsi, consulta le [note di aggiornamento della 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization). diff --git a/docs/content/admin/user_management/OS__authorized_users.pt-br.md b/docs/content/admin/user_management/OS__authorized_users.pt-br.md new file mode 100644 index 0000000000..cbb7d77795 --- /dev/null +++ b/docs/content/admin/user_management/OS__authorized_users.pt-br.md @@ -0,0 +1,61 @@ +--- +title: Permissões do Open Source +description: Como o acesso a Produtos e Tipos de Produto é concedido no DefectDojo + open source +weight: 1 +audience: opensource +--- + +O DefectDojo open source controla o acesso a Produtos e Tipos de Produto com o modelo de **Usuários Autorizados**. Cada Produto e Tipo de Produto tem um painel de Usuários Autorizados listando as pessoas que podem ver aquele registro e os dados aninhados sob ele. + +Se você está usando o DefectDojo Pro, este artigo não se aplica à sua instalação — o Pro usa um sistema baseado em papéis mais completo, abordado em [Permissões no DefectDojo](../about_perms_and_roles/). + +## Como o acesso é concedido + +Existem duas listas, e um usuário só precisa aparecer em uma delas para obter acesso: + +- **A lista de Usuários Autorizados de um Produto** concede acesso a esse Produto específico, além de tudo o que está aninhado sob ele (seus Engajamentos, Testes, Achados e Endpoints). +- **A lista de Usuários Autorizados de um Tipo de Produto** concede acesso ao próprio Tipo de Produto **e se propaga para todos os Produtos sob ele**. Um usuário autorizado em um Tipo de Produto não precisa também ser adicionado a cada Produto filho — ele já está coberto. + +Não existem papéis, grupos ou papéis globais. Um usuário está na lista (ou é superusuário/membro da equipe — veja abaixo), ou não consegue ver o Produto. + +## Superusuários e membros da equipe ignoram as listas + +Usuários marcados como **superusuário** ou **membro da equipe (staff)** no DefectDojo podem ver e atuar em todos os Produtos e Tipos de Produto, independentemente das listas de Usuários Autorizados. As listas existem para conceder acesso a usuários que não são da equipe; elas não restringem membros da equipe ou superusuários. + +A primeira conta criada em uma instalação nova do DefectDojo é automaticamente um superusuário. + +## Quem pode editar as listas + +Somente usuários **superusuário** ou **membro da equipe** veem os controles para adicionar ou remover pessoas de um painel de Usuários Autorizados. Todos os demais que têm acesso a um Produto ou Tipo de Produto veem o painel como uma lista somente leitura — útil para descobrir quem mais está na equipe, mas não para alterar a associação. + +## Onde o painel fica + +O painel de Usuários Autorizados aparece em duas páginas na interface clássica: + +- A **página de detalhes do Produto** tem um painel de Usuários Autorizados para aquele Produto. Ela oferece duas ações para usuários da equipe: + - **Adicionar um usuário à lista de Usuários Autorizados do Produto** + - **Remover um usuário da lista de Usuários Autorizados do Produto** +- A **página de detalhes do Tipo de Produto** tem um painel de Usuários Autorizados para aquele Tipo de Produto, com as duas ações correspondentes: + - **Adicionar um usuário à lista de Usuários Autorizados do Tipo de Produto** + - **Remover um usuário da lista de Usuários Autorizados do Tipo de Produto** + +Quando você remove um usuário da lista de um Tipo de Produto, a propagação também é removida — ele perde o acesso a todos os Produtos filhos, a menos que ainda esteja na lista de um Produto específico, ou seja membro da equipe/superusuário. + +## Escolhendo entre acesso por Produto ou por Tipo de Produto + +Algumas regras práticas: + +- Se uma pessoa deve ver todos os Produtos de uma categoria (por exemplo, todos os Produtos de uma determinada equipe), coloque-a na lista do **Tipo de Produto** e deixe a propagação cuidar do resto. +- Se uma pessoa deve ver apenas um Produto específico, coloque-a na lista daquele **Produto**. +- Se você perceber que está adicionando a mesma pessoa a vários Produtos individuais dentro de um mesmo Tipo de Produto, isso é um sinal de que deveria adicioná-la ao Tipo de Produto em vez disso. + +## Vindo de uma versão anterior do DefectDojo + +O DefectDojo open source voltou ao modelo de Usuários Autorizados na versão 3.0. Se você está atualizando a partir de uma versão que tinha o sistema de Membros / Grupos / Papéis Globais, seu acesso existente é migrado automaticamente para Usuários Autorizados pela própria atualização — não é necessário nenhum mapeamento manual. + +A atualização vem com um comando de gerenciamento somente leitura, `preview_legacy_authorization_migration`, que resume o que uma atualização mudaria em uma cópia do seu banco de dados. O fluxo de trabalho recomendado é instalar a versão 3.0 em um ambiente de staging com um snapshot da produção, executar o comando, revisar o resumo e só então atualizar a produção. + +Se você está indo na direção contrária — do open source para o DefectDojo Pro — o Pro vem com um comando `reconcile_authorized_users_to_rbac` que traz o acesso de Usuários Autorizados para o RBAC do Pro. Ele suporta `--dry-run` e é idempotente. + +Para mais detalhes sobre os dois caminhos, veja as [notas de atualização da versão 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization). diff --git a/docs/content/admin/user_management/OS__authorized_users.zh-hans.md b/docs/content/admin/user_management/OS__authorized_users.zh-hans.md new file mode 100644 index 0000000000..a0c640e149 --- /dev/null +++ b/docs/content/admin/user_management/OS__authorized_users.zh-hans.md @@ -0,0 +1,60 @@ +--- +title: 开源版权限 +description: 开源版 DefectDojo 中如何授予对产品和产品类型的访问权限 +weight: 1 +audience: opensource +--- + +开源版 DefectDojo 通过**已授权用户（Authorized Users）**模型来控制对产品和产品类型的访问。每个产品和产品类型都有一个已授权用户面板，列出可以查看该记录及其下嵌套数据的人员。 + +如果你使用的是 DefectDojo Pro，本文不适用于你的安装环境——Pro 使用一套更完善的基于角色的系统，详见 [DefectDojo 中的权限](../about_perms_and_roles/)。 + +## 如何授予访问权限 + +共有两份名单，用户只需出现在其中一份上即可获得访问权限： + +- **产品的已授权用户名单**授予对该单个产品的访问权限，以及嵌套在其下的所有内容（其测试活动、测试、发现项和端点）。 +- **产品类型的已授权用户名单**授予对该产品类型本身的访问权限，**并会级联到其下的每一个产品**。已被授权访问某个产品类型的用户，无需再逐一添加到每个子产品中——他们已经被覆盖了。 + +这里没有角色、没有组，也没有全局角色。用户要么在名单上（或者是超级用户/职员——见下文），要么就无法看到该产品。 + +## 超级用户和职员可绕过名单 + +在 DefectDojo 中被标记为**超级用户（superuser）**或**职员（staff）**的用户，无论已授权用户名单如何，都可以查看并操作每一个产品和产品类型。这些名单的作用是为非职员用户授予访问权限，而不会限制职员或超级用户。 + +在全新安装的 DefectDojo 上创建的第一个账户会自动成为超级用户。 + +## 谁可以编辑名单 + +只有**超级用户**或**职员**用户才能看到用于在已授权用户面板中添加或移除人员的操作控件。其他所有能够访问某个产品或产品类型的人，看到的都是一份只读名册——可用来查看团队中还有谁，但无法用来更改成员身份。 + +## 该面板的位置 + +已授权用户面板出现在经典 UI 的两个页面上： + +- **产品详情页**上有该产品的已授权用户面板。它为职员用户提供两项操作： + - **将用户添加到该产品的已授权用户名单** + - **将用户从该产品的已授权用户名单中移除** +- **产品类型详情页**上有该产品类型的已授权用户面板，同样提供相应的两项操作： + - **将用户添加到该产品类型的已授权用户名单** + - **将用户从该产品类型的已授权用户名单中移除** + +当你将某用户从产品类型的名单中移除时，级联授权也会一并移除——除非该用户仍在某个具体产品的名单上，或者本身是职员/超级用户，否则他们将失去对所有子产品的访问权限。 + +## 在产品级和产品类型级访问权限之间做选择 + +几条经验法则： + +- 如果某人应该能看到某个类别下的所有产品（例如某个特定团队拥有的所有产品），把他们加入**产品类型**名单，剩下的交给级联机制处理即可。 +- 如果某人只应该看到某一个特定的产品，把他们加入该**产品**的名单。 +- 如果你发现自己在把同一个人反复添加到某个产品类型下的多个单独产品中，这就说明你应该改为将其添加到该产品类型。 + +## 从旧版本 DefectDojo 升级而来 + +DefectDojo 开源版在 3.0 版本中恢复使用了已授权用户模型。如果你正在从具有成员 / 组 / 全局角色系统的版本升级，你现有的访问权限会在升级过程中自动迁移到已授权用户模型中——无需手动映射。 + +此次升级附带了一个只读的管理命令 `preview_legacy_authorization_migration`，它会针对你数据库的副本，汇总升级将带来的变更。推荐的做法是：在预发布环境中安装 3.0 版本并使用一份生产环境快照，运行该命令，审查汇总结果，然后再升级生产环境。 + +如果你是朝相反方向迁移——从开源版迁移到 DefectDojo Pro——Pro 附带了一个 `reconcile_authorized_users_to_rbac` 命令，可以将已授权用户的访问权限迁移到 Pro 的 RBAC 中。该命令支持 `--dry-run`，且是幂等的。 + +有关这两条路径的更多详情，请参阅 [3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。 diff --git a/docs/content/admin/user_management/OS__creating_new_users.it.md b/docs/content/admin/user_management/OS__creating_new_users.it.md new file mode 100644 index 0000000000..3076ea4ca8 --- /dev/null +++ b/docs/content/admin/user_management/OS__creating_new_users.it.md @@ -0,0 +1,43 @@ +--- +title: Creazione di un nuovo utente +description: Come inserire un nuovo utente nella tua istanza di DefectDojo +audience: opensource +weight: 1 +--- + +Questa pagina descrive il flusso di lavoro consigliato per l'onboarding e l'aggiunta di nuovi utenti a un'istanza di DefectDojo. Gli utenti di DefectDojo possono essere utilizzati sia come account standard gestiti da persone, sia come account di servizio. + +L'amministratore che crea l'account è responsabile della consegna delle credenziali iniziali (nome utente e password) al nuovo utente. + +## Flusso di lavoro consigliato + +1. **Crea l'account utente** in DefectDojo (solo Superuser): + * Vai su **👤 Users → Users** per aprire la tabella All Users. + * Fai clic sull'icona 🛠️ (chiave inglese e cacciavite incrociati). + * Inserisci il nome e l'indirizzo email del nuovo utente. + * Imposta una password temporanea. + * Invia il modulo. + +2. **Assegna i permessi** come opportuno — appartenenza a Prodotto/Tipo di prodotto, Configuration Permissions, Global Role o stato di Superuser. Per i dettagli, vedi [Impostare i permessi di un utente](../set_user_permissions/). Un nuovo utente senza alcuna assegnazione non potrà vedere nessun Prodotto o Riscontro. + +3. **Invia le credenziali al nuovo utente fuori banda** (via email, lo strumento di chat del tuo team, o comunque tu condivida normalmente i segreti). Includi: + * L'URL dell'istanza DefectDojo. + * Il nome utente (in genere il loro indirizzo email). + * La password temporanea appena impostata. + * Una nota che li invita a cambiare la password e ad attivare l'MFA (se la tua istanza utilizza l'MFA) al primo accesso. + +4. **Il nuovo utente accede e sostituisce la credenziale.** Può: + * Accedere con la password temporanea e poi cambiarla dal proprio menu profilo, oppure + * Usare il link **I forgot my password** nella pagina di accesso per impostare direttamente una password senza usare quella temporanea. La password temporanea è comunque necessaria perché esista il record iniziale dell'account, ma l'utente non deve ricordarla se utilizza il flusso di reimpostazione della password. + +5. **Il nuovo utente configura l'MFA** dal proprio menu profilo. Consigliamo vivamente di richiedere l'MFA per tutti gli utenti sulle istanze che non sono dietro SSO. + +## Utenti SSO + +Se la tua istanza è configurata con [SSO](../configure_sso/), il flusso di lavoro è diverso — gli utenti vengono in genere creati al primo accesso dall'Identity Provider, e devi solo concedere loro l'appartenenza a un gruppo o i ruoli in un secondo momento. + +Se sei passato a DefectDojo open source (dove SSO è disponibile solo in Pro) e gli utenti SSO esistenti non riescono più ad accedere, consulta [Riattivare l'accesso per gli utenti SSO](../os__sso_user_local_login_fallback/). + +## Ripristino da un token MFA perso + +Se un utente perde l'accesso al proprio dispositivo MFA, consulta la [sezione sul ripristino dell'MFA](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes) della guida alla risoluzione dei problemi di connettività. Al momento non esiste un modo per rimuovere l'MFA da un account senza un codice MFA — la soluzione alternativa è creare un nuovo account per l'utente e riconcedere gli stessi permessi. diff --git a/docs/content/admin/user_management/OS__creating_new_users.pt-br.md b/docs/content/admin/user_management/OS__creating_new_users.pt-br.md new file mode 100644 index 0000000000..8606e2791c --- /dev/null +++ b/docs/content/admin/user_management/OS__creating_new_users.pt-br.md @@ -0,0 +1,43 @@ +--- +title: Criando um novo usuário +description: Como integrar um novo usuário à sua instância do DefectDojo +audience: opensource +weight: 1 +--- + +Esta página descreve o fluxo de integração recomendado para adicionar novos usuários a uma instância do DefectDojo. Usuários do DefectDojo podem ser usados tanto como contas padrão, operadas por humanos, quanto como contas de serviço. + +O administrador que cria a conta é responsável por entregar as credenciais iniciais (usuário e senha) ao novo usuário. + +## Fluxo de trabalho recomendado + +1. **Crie a conta de usuário** no DefectDojo (somente Superusuário): + * Navegue até **👤 Users → Users** para abrir a tabela All Users. + * Clique no ícone 🛠️ (chave inglesa e chave de fenda cruzadas). + * Digite o nome e o endereço de e-mail do novo usuário. + * Defina uma senha temporária. + * Envie o formulário. + +2. **Atribua as permissões** conforme apropriado — associação a Produto/Tipo de Produto, Permissões de Configuração, Papel Global ou status de Superusuário. Veja [Definir as permissões de um usuário](../set_user_permissions/) para mais detalhes. Um novo usuário sem nenhuma atribuição não conseguirá ver nenhum Produto ou Achado. + +3. **Envie as credenciais ao novo usuário por um canal separado** (por e-mail, pela ferramenta de chat da sua equipe, ou da forma como você costuma compartilhar segredos). Inclua: + * A URL da instância do DefectDojo. + * O nome de usuário (normalmente o e-mail dele). + * A senha temporária que você acabou de definir. + * Uma observação de que ele deve trocar a senha e ativar o MFA (se a sua instância usar MFA) no primeiro login. + +4. **O novo usuário faz login e troca a credencial.** Ele pode: + * Fazer login com a senha temporária e depois trocá-la pelo menu de perfil, ou + * Usar o link **Esqueci minha senha** na página de login para definir uma senha diretamente, sem usar a temporária. A senha temporária ainda é necessária para que o registro inicial da conta exista, mas o usuário não precisa memorizá-la se usar o fluxo de redefinição de senha. + +5. **O novo usuário configura o MFA** pelo menu de perfil. Recomendamos fortemente exigir MFA para todos os usuários em instâncias que não estejam atrás de um SSO. + +## Usuários de SSO + +Se a sua instância estiver configurada com [SSO](../configure_sso/), o fluxo é diferente — os usuários normalmente são criados no primeiro login a partir do Provedor de Identidade, e você só precisa conceder a eles associação a grupos ou papéis depois. + +Se você migrou para o DefectDojo open source (onde o SSO é exclusivo do Pro) e os usuários de SSO existentes não conseguem mais fazer login, veja [Reativando o login para usuários de SSO](../os__sso_user_local_login_fallback/). + +## Recuperando-se de um token de MFA perdido + +Se um usuário perder o acesso ao dispositivo de MFA, veja a [seção de recuperação de MFA](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes) do guia de solução de problemas de conectividade. Atualmente não há como remover o MFA de uma conta sem um código de MFA — a solução alternativa é criar uma nova conta para o usuário e conceder novamente as mesmas permissões. diff --git a/docs/content/admin/user_management/OS__creating_new_users.zh-hans.md b/docs/content/admin/user_management/OS__creating_new_users.zh-hans.md new file mode 100644 index 0000000000..27f5e8e845 --- /dev/null +++ b/docs/content/admin/user_management/OS__creating_new_users.zh-hans.md @@ -0,0 +1,43 @@ +--- +title: 创建新用户 +description: 如何在你的 DefectDojo 实例上引导新用户加入 +audience: opensource +weight: 1 +--- + +本页介绍了向 DefectDojo 实例添加新用户时推荐的入职流程。DefectDojo 用户既可以作为标准的、由真人操作的账户，也可以作为服务账户使用。 + +创建账户的管理员负责将初始凭据（用户名和密码）交付给新用户。 + +## 推荐流程 + +1. 在 DefectDojo 中**创建用户账户**（仅限超级用户）： + * 导航到 **👤 Users → Users** 打开"所有用户"表。 + * 点击 🛠️（交叉扳手和螺丝刀）图标。 + * 输入新用户的姓名和电子邮件地址。 + * 设置一个临时密码。 + * 提交表单。 + +2. 根据需要**分配权限**——产品/产品类型成员身份、配置权限、全局角色，或超级用户身份。详情参见 [设置用户的权限](../set_user_permissions/)。如果新用户没有被分配任何权限，将无法看到任何产品或发现项。 + +3. **通过带外方式将凭据发送给新用户**（通过电子邮件、团队的聊天工具，或你们平时共享敏感信息的其他方式）。需要包含： + * DefectDojo 实例的 URL。 + * 用户名（通常是他们的电子邮件地址）。 + * 你刚刚设置的临时密码。 + * 提醒他们在首次登录时应更改密码，并启用 MFA（如果你的实例使用 MFA）。 + +4. **新用户登录并轮换凭据。** 他们可以： + * 使用临时密码登录，然后从个人资料菜单中修改密码，或者 + * 使用登录页面上的 **I forgot my password（忘记密码）**链接，直接设置密码而无需使用临时密码。初始账户记录仍然需要那个临时密码才能存在，但如果用户走密码重置流程，就不需要记住它。 + +5. **新用户从个人资料菜单中配置 MFA。** 对于没有部署在 SSO 之后的实例，我们强烈建议要求所有用户都启用 MFA。 + +## SSO 用户 + +如果你的实例配置了 [SSO](../configure_sso/)，流程会有所不同——用户通常会在首次通过身份提供商登录时自动创建，此后你只需要为他们授予组成员身份或角色即可。 + +如果你已迁移到开源版 DefectDojo（其中 SSO 仅限 Pro 版），且现有的 SSO 用户无法再登录，请参阅 [为 SSO 用户重新启用登录](../os__sso_user_local_login_fallback/)。 + +## 找回丢失的 MFA 令牌 + +如果用户无法再访问其 MFA 设备，请参阅连接故障排查指南中的 [MFA 找回部分](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes)。目前还没有办法在没有 MFA 代码的情况下移除账户上的 MFA——变通方法是为该用户新建一个账户，并重新授予相同的权限。 diff --git a/docs/content/admin/user_management/OS__sso_user_local_login_fallback.it.md b/docs/content/admin/user_management/OS__sso_user_local_login_fallback.it.md new file mode 100644 index 0000000000..4d60259299 --- /dev/null +++ b/docs/content/admin/user_management/OS__sso_user_local_login_fallback.it.md @@ -0,0 +1,58 @@ +--- +title: Riattivare l'accesso per gli utenti SSO (Open Source) +description: Assegna una password locale agli utenti creati tramite SSO dopo il passaggio + a Open Source, dove SSO è una funzionalità disponibile solo in Pro +audience: opensource +weight: 2 +--- + +## Quando si applica + +SSO (SAML, OIDC, OAuth) è una funzionalità di [DefectDojo Pro](https://defectdojo.com). Se esegui l'aggiornamento a DefectDojo open source 3.x (o in altro modo abbandoni Pro), le opzioni di accesso SSO vengono rimosse e gli utenti creati tramite SSO non possono più accedere. Ai loro account non è mai stata assegnata una password locale, e l'interfaccia utente e l'API non ti permetteranno di impostarne una: DefectDojo li rileva come account SSO e blocca la modifica. + +**Non** è necessario eliminare e ricreare questi utenti (il che farebbe perdere la loro cronologia, i permessi e la proprietà degli oggetti). Assegna invece a ciascun account una password locale sul backend e forza una reimpostazione della password al successivo accesso. + +Per maggiori informazioni sul fatto che SSO sia disponibile solo in Pro, consulta la [sezione SSO](/admin/sso/) e le [note di aggiornamento della 3.0](/releases/os_upgrading/3.0/#sso-providers-are-available-in-defectdojo-pro-only). + +## Perché succede + +DefectDojo open source si autentica solo rispetto al database utenti locale di Django. Decide se un account è un "utente SSO" esclusivamente in base al fatto che l'account abbia una password utilizzabile. Gli account creati tramite SSO sono stati creati con una password *non utilizzabile*, quindi: + +* l'accesso locale fallisce (non c'è alcuna password da verificare), e +* il controllo **Force password reset** nell'interfaccia utente e nell'API è bloccato, con un messaggio che indica che l'utente è autorizzato tramite SSO. + +Impostare una password reale risolve entrambe le condizioni contemporaneamente: l'account può accedere localmente e il flag di reimpostazione forzata diventa impostabile. + +## La soluzione alternativa + +Esegui questi passaggi dalla shell Django all'interno del container `uwsgi`: + +```bash +docker compose exec -it uwsgi ./manage.py shell +``` + +### Esempio per un singolo utente + +```python +from dojo.user.models import Dojo_User, UserContactInfo + +u = Dojo_User.objects.get(username="alice@example.com") +u.set_password("") # makes the account a local login account +u.save() + +uci, _ = UserContactInfo.objects.get_or_create(user=u) +uci.force_password_reset = True # force a change on next login +uci.save() +``` + +## Cosa fa l'utente successivamente + +Consegna la password temporanea a ciascun utente fuori banda (email, la chat del tuo team, o comunque tu condivida normalmente i segreti). Al successivo accesso, DefectDojo li reindirizza alla pagina **Change Password** e non permetterà loro di andare altrove finché non impostano la propria password. Il flag di reimpostazione forzata si azzera automaticamente una volta fatto. + +Se la tua istanza ha il flusso "I forgot my password" abilitato (`DD_FORGOT_PASSWORD`, attivo per impostazione predefinita) e l'email configurata, gli utenti possono invece usare il link **I forgot my password** nella pagina di accesso una volta che il loro account ha una password utilizzabile, e impostare una password senza bisogno di quella temporanea. + +## Note + +* **Kubernetes:** esegui invece la shell nel pod Django, ad esempio `kubectl exec -it deploy/defectdojo-django -c uwsgi -- ./manage.py shell` (adatta i nomi di deployment e container alla tua release). +* Scegli una password robusta e usa e getta. Con `force_password_reset = True` l'utente non può mantenerla, quindi deve solo sopravvivere a un accesso. +* Mantieni almeno un account amministratore locale funzionante, così da non restare mai bloccato fuori. diff --git a/docs/content/admin/user_management/OS__sso_user_local_login_fallback.pt-br.md b/docs/content/admin/user_management/OS__sso_user_local_login_fallback.pt-br.md new file mode 100644 index 0000000000..3f11af5715 --- /dev/null +++ b/docs/content/admin/user_management/OS__sso_user_local_login_fallback.pt-br.md @@ -0,0 +1,58 @@ +--- +title: Reativando o login para usuários de SSO (Open Source) +description: Defina uma senha local para usuários provisionados via SSO após migrar + para o Open Source, onde o SSO é um recurso exclusivo do Pro +audience: opensource +weight: 2 +--- + +## Quando isso se aplica + +O SSO (SAML, OIDC, OAuth) é um recurso do [DefectDojo Pro](https://defectdojo.com). Se você atualizar para o DefectDojo open source 3.x (ou de alguma outra forma deixar de usar o Pro), as opções de login via SSO são removidas, e os usuários que foram provisionados por SSO não conseguem mais fazer login. As contas deles nunca receberam uma senha local, e a interface e a API não permitem definir uma para eles: o DefectDojo os detecta como contas de SSO e bloqueia a alteração. + +Você **não** precisa excluir e recriar esses usuários (o que faria você perder o histórico, as permissões e a propriedade dos objetos deles). Em vez disso, defina uma senha local para cada conta no backend e force uma redefinição de senha no próximo login. + +Veja a [seção de SSO](/admin/sso/) e as [notas de atualização da versão 3.0](/releases/os_upgrading/3.0/#sso-providers-are-available-in-defectdojo-pro-only) para entender o contexto de o SSO ser exclusivo do Pro. + +## Por que isso acontece + +O DefectDojo open source autentica apenas contra o banco de dados local de usuários do Django. Ele decide se uma conta é uma "usuária de SSO" unicamente pelo fato de a conta ter ou não uma senha utilizável. As contas provisionadas via SSO foram criadas com uma senha *inutilizável*, então: + +* o login local falha (não há senha para verificar), e +* o controle **Forçar redefinição de senha** na interface e na API fica bloqueado, com uma mensagem informando que o usuário está autorizado via SSO. + +Definir uma senha real resolve as duas condições de uma vez: a conta passa a conseguir fazer login localmente, e a flag de redefinição forçada passa a poder ser definida. + +## A solução alternativa + +Execute estes passos a partir do shell do Django dentro do container `uwsgi`: + +```bash +docker compose exec -it uwsgi ./manage.py shell +``` + +### Exemplo para um único usuário + +```python +from dojo.user.models import Dojo_User, UserContactInfo + +u = Dojo_User.objects.get(username="alice@example.com") +u.set_password("") # makes the account a local login account +u.save() + +uci, _ = UserContactInfo.objects.get_or_create(user=u) +uci.force_password_reset = True # force a change on next login +uci.save() +``` + +## O que o usuário faz em seguida + +Entregue a senha temporária a cada usuário por um canal separado (e-mail, o chat da sua equipe, ou da forma como você costuma compartilhar segredos). No próximo login, o DefectDojo os redireciona para a página **Alterar senha** e não permite que eles vão a nenhum outro lugar até definirem sua própria senha. A flag de redefinição forçada é limpa automaticamente assim que isso acontece. + +Se a sua instância tiver o fluxo "Esqueci minha senha" habilitado (`DD_FORGOT_PASSWORD`, ativado por padrão) e o e-mail configurado, os usuários podem, em vez disso, usar o link **Esqueci minha senha** na página de login depois que a conta tiver uma senha utilizável, e definir uma senha sem precisar da temporária. + +## Observações + +* **Kubernetes:** execute o shell no pod do Django, por exemplo `kubectl exec -it deploy/defectdojo-django -c uwsgi -- ./manage.py shell` (ajuste os nomes do deployment e do container para a sua versão). +* Escolha uma senha temporária forte. Com `force_password_reset = True` o usuário não pode mantê-la, então ela só precisa sobreviver a um login. +* Mantenha pelo menos uma conta de administrador local funcionando para que você nunca fique bloqueado. diff --git a/docs/content/admin/user_management/OS__sso_user_local_login_fallback.zh-hans.md b/docs/content/admin/user_management/OS__sso_user_local_login_fallback.zh-hans.md new file mode 100644 index 0000000000..0fa5087f8e --- /dev/null +++ b/docs/content/admin/user_management/OS__sso_user_local_login_fallback.zh-hans.md @@ -0,0 +1,57 @@ +--- +title: 为 SSO 用户重新启用登录（开源版） +description: 在迁移到开源版（SSO 仅为 Pro 版功能）之后，为通过 SSO 创建的用户设置本地密码 +audience: opensource +weight: 2 +--- + +## 适用场景 + +SSO（SAML、OIDC、OAuth）是 [DefectDojo Pro](https://defectdojo.com) 的功能。如果你升级到开源版 DefectDojo 3.x（或以其他方式脱离 Pro 版），SSO 登录选项会被移除，此前通过 SSO 创建的用户将无法再登录。他们的账户从未被设置过本地密码，而 UI 和 API 也不允许你为其设置密码：DefectDojo 会将它们识别为 SSO 账户并阻止这一更改。 + +你**不需要**删除并重新创建这些用户（那样会丢失他们的历史记录、权限和对象归属）。相反，只需在后端为每个账户设置一个本地密码，并强制其在下次登录时重置密码。 + +关于 SSO 仅限 Pro 版这一背景，请参阅 [SSO 章节](/admin/sso/) 和 [3.0 升级说明](/releases/os_upgrading/3.0/#sso-providers-are-available-in-defectdojo-pro-only)。 + +## 为什么会出现这种情况 + +开源版 DefectDojo 只针对 Django 的本地用户数据库进行身份验证。它判断某个账户是否为"SSO 用户"，唯一依据就是该账户是否拥有一个可用的密码。通过 SSO 创建的账户在创建时被设置了一个*不可用*的密码，因此： + +* 本地登录会失败（没有可供校验的密码），并且 +* UI 和 API 中的**强制密码重置（Force password reset）**控件会被阻止，并提示该用户是通过 SSO 进行身份验证的。 + +设置一个真实的密码可以同时清除这两个限制：账户可以进行本地登录，并且强制重置标志也变得可以设置。 + +## 变通方法 + +在 `uwsgi` 容器内的 Django shell 中执行以下步骤： + +```bash +docker compose exec -it uwsgi ./manage.py shell +``` + +### 单个用户示例 + +```python +from dojo.user.models import Dojo_User, UserContactInfo + +u = Dojo_User.objects.get(username="alice@example.com") +u.set_password("") # makes the account a local login account +u.save() + +uci, _ = UserContactInfo.objects.get_or_create(user=u) +uci.force_password_reset = True # force a change on next login +uci.save() +``` + +## 用户接下来要做什么 + +通过带外方式（电子邮件、团队聊天工具，或你们平时共享敏感信息的其他方式）将临时密码发送给每位用户。在他们下次登录时，DefectDojo 会将其重定向到**修改密码（Change Password）**页面，并且在他们设置好自己的密码之前，不允许前往任何其他页面。一旦完成设置，强制重置标志会自动清除。 + +如果你的实例启用了"忘记密码"流程（`DD_FORGOT_PASSWORD`，默认开启）并配置了电子邮件，那么在账户拥有可用密码之后，用户也可以改用登录页面上的 **I forgot my password（忘记密码）**链接，无需使用临时密码即可设置新密码。 + +## 说明 + +* **Kubernetes：** 改为在 Django pod 中运行该 shell，例如 `kubectl exec -it deploy/defectdojo-django -c uwsgi -- ./manage.py shell`（请根据你的发布版本调整部署和容器名称）。 +* 请选择一个强度足够的一次性密码。由于设置了 `force_password_reset = True`，用户无法保留这个密码，因此它只需要能撑过一次登录即可。 +* 请至少保留一个可用的本地管理员账户，以确保你不会被锁在外面。 diff --git a/docs/content/admin/user_management/PRO__audit_log_index.it.md b/docs/content/admin/user_management/PRO__audit_log_index.it.md new file mode 100644 index 0000000000..246c248cfc --- /dev/null +++ b/docs/content/admin/user_management/PRO__audit_log_index.it.md @@ -0,0 +1,132 @@ +--- +title: Registrazione degli audit +description: Ogni azione di creazione, modifica ed eliminazione che DefectDojo registra + nel proprio log di audit, oltre a cosa viene acquisito e come configurare la conservazione. +draft: false +weight: 4 +--- + +DefectDojo registra una cronologia di controllo (audit trail) delle modifiche ai propri dati. Ogni oggetto monitorato registra automaticamente eventi di **create**, **update** e **delete**, e le tabelle di relazione (molti-a-molti) registrano eventi di **add** e **remove**. + +## Come funziona + +Il tracciamento degli audit è guidato da trigger di database registrati per ciascun modello. Per ogni +oggetto monitorato, possono scattare tre tipi di evento: + +| Tipo di evento | Quando scatta | Azione | +| ------------- | ----------------------------------------------------------------------------- | ---------- | +| `InsertEvent` | Viene creato un nuovo record | **Create** | +| `UpdateEvent` | Un record cambia — solo quando il valore di un campo reale cambia effettivamente | **Update** | +| `DeleteEvent` | Un record viene eliminato | **Delete** | + +Le tabelle di relazione molti-a-molti (tag, revisori, intervalli IP del firewall) tracciano +solo **add** (`InsertEvent`) e **remove** (`DeleteEvent`) — non esiste un +"update" per una riga di relazione. + +### Cosa viene acquisito con ogni evento + +- **Who** — l'utente che ha eseguito l'azione, ricavato dal contesto della richiesta. +- **When** — un timestamp. +- **Source IP** — l'indirizzo remoto, rispettando le catene di proxy `X-Forwarded-For`. +- **Before/after snapshot** — i valori completi dei campi del record. +- **Context / label** — raggruppa gli eventi originati dalla stessa richiesta. L'etichetta + `initial_backfill` contrassegna i record storici importati quando il tracciamento è stato + attivato per la prima volta. + +Gli eventi prodotti dai job in background vengono ricollegati al contesto della +richiesta di origine, così un'azione completata in modo asincrono viene comunque +attribuita all'utente che l'ha avviata. + +## Core (Open Source) — azioni monitorate + +| Oggetto | Create | Update | Delete | Note | +| ------------------------------ | :----: | :----: | :----: | ---------------------------------------------- | +| Utente | ✅ | ✅ | ✅ | `password` esclusa dagli snapshot | +| Tipo di prodotto | ✅ | ✅ | ✅ | | +| Prodotto | ✅ | ✅ | ✅ | | +| Engagement | ✅ | ✅ | ✅ | | +| Test | ✅ | ✅ | ✅ | | +| Riscontro | ✅ | ✅ | ✅ | | +| Gruppo di Riscontri | ✅ | ✅ | ✅ | | +| Modello di Riscontro | ✅ | ✅ | ✅ | | +| Accettazione del rischio | ✅ | ✅ | ✅ | | +| Endpoint | ✅ | ✅ | ✅ | | +| Posizione | ✅ | ✅ | ✅ | | +| URL | ✅ | ✅ | ✅ | | +| Webhook di Notifica | ✅ | ✅ | ✅ | `header_name` / `header_value` esclusi (segreti) | + +### Core — eventi di relazione (add / remove) + +| Relazione | Add | Remove | +| ---------------------------------- | :-: | :----: | +| Riscontro → Revisori | ✅ | ✅ | +| Riscontro → Tag | ✅ | ✅ | +| Riscontro → Tag ereditati | ✅ | ✅ | +| Prodotto → Tag | ✅ | ✅ | +| Engagement → Tag | ✅ | ✅ | +| Engagement → Tag ereditati | ✅ | ✅ | +| Test → Tag | ✅ | ✅ | +| Test → Tag ereditati | ✅ | ✅ | +| Endpoint → Tag | ✅ | ✅ | +| Endpoint → Tag ereditati | ✅ | ✅ | +| Modello di Riscontro → Tag | ✅ | ✅ | +| App Analysis (Technology) → Tag | ✅ | ✅ | +| Objects/Product → Tag | ✅ | ✅ | + +## Pro — azioni monitorate + +| Oggetto | Create | Update | Delete | Note | +| --------------------------------- | :----: | :----: | :----: | ------------------------------ | +| Enhanced Finding | ✅ | ✅ | ✅ | Companion Pro del Riscontro | +| Regola | ✅ | ✅ | ✅ | Motore delle regole | +| Azione della regola | ✅ | ✅ | ✅ | | +| Condizione dell'azione della regola | ✅ | ✅ | ✅ | | +| Voce di filtro della regola | ✅ | ✅ | ✅ | | +| Operazione del motore delle regole | ✅ | ✅ | ✅ | | +| Messaggio dell'operazione del motore delle regole | ✅ | ✅ | ✅ | | +| Attività pianificata | ✅ | ✅ | ✅ | | +| Esecuzione dell'attività pianificata | ✅ | ✅ | ✅ | | +| Policy di mitigazione | ✅ | ✅ | ✅ | | +| Impostazione configurabile | ✅ | ✅ | ✅ | Modifiche alla configurazione di sistema | +| Stato Feature Flag | ✅ | ✅ | ✅ | Attivazione/disattivazione flag + pin di sistema | +| Definizione Feature Flag | ✅ | ✅ | ✅ | Sincronizzazione di metadata / registro | +| Cloud Firewall | ✅ | ✅ | ✅ | campo `locked` escluso | +| Maschera IP Firewall | ✅ | ✅ | ✅ | | + +### Pro — RBAC / permessi + +| Oggetto | Create | Update | Delete | +| ----------------------------- | :----: | :----: | :----: | +| Gruppo | ✅ | ✅ | ✅ | +| Ruolo | ✅ | ✅ | ✅ | +| Appartenenza al gruppo | ✅ | ✅ | ✅ | +| Ruolo globale | ✅ | ✅ | ✅ | +| Assegnazione gruppo al prodotto | ✅ | ✅ | ✅ | +| Assegnazione gruppo al tipo di prodotto | ✅ | ✅ | ✅ | +| Membro del prodotto | ✅ | ✅ | ✅ | +| Membro del tipo di prodotto | ✅ | ✅ | ✅ | + +### Pro — eventi di relazione (add / remove) + +| Relazione | Add | Remove | +| --------------------------- | :-: | :----: | +| Cloud Firewall → Intervalli IP | ✅ | ✅ | + +## Configurazione e conservazione (On-Premise Controls) + +| Impostazione | Variabile d'ambiente | Predefinito | Effetto | +| -------------------- | -------------------------------------- | ------------------ | ------------------------------------------------------------------ | +| Abilita la registrazione degli audit | `DD_ENABLE_AUDITLOG` | `True` | Quando è `False`, tutti i trigger di cronologia sono disabilitati e nessun evento viene registrato | +| Periodo di conservazione | `DD_AUDITLOG_FLUSH_RETENTION_PERIOD` | `-1` (mai eliminare) | Mesi di cronologia da conservare; gli eventi più vecchi vengono eliminati in blocco dal job di pulizia | +| Dimensione del batch di pulizia | `DD_AUDITLOG_FLUSH_BATCH_SIZE` | `1000` | Righe eliminate per batch durante la pulizia | +| Numero massimo di batch di pulizia | `DD_AUDITLOG_FLUSH_MAX_BATCHES` | `100` | Limite al numero di batch per ogni esecuzione di pulizia | + +## Note e limitazioni + +- **I segreti non vengono mai acquisiti.** Le password degli utenti e i valori degli header dei + webhook di notifica sono esplicitamente esclusi dagli snapshot degli eventi. +- **Gli update vengono registrati solo in caso di modifica reale.** Un salvataggio che non altera alcun + valore di campo non produce alcun evento di update; i campi gestiti automaticamente come + il solo `last_updated` non ne fanno scattare uno. +- **Gli eventi di autenticazione non vengono acquisiti qui.** Solo le modifiche + ai dati. Le attività di login, logout e tentativo di accesso fallito sono gestite separatamente e non fanno parte di questo log di audit. diff --git a/docs/content/admin/user_management/PRO__audit_log_index.pt-br.md b/docs/content/admin/user_management/PRO__audit_log_index.pt-br.md new file mode 100644 index 0000000000..48c167fefb --- /dev/null +++ b/docs/content/admin/user_management/PRO__audit_log_index.pt-br.md @@ -0,0 +1,134 @@ +--- +title: Log de Auditoria +description: Toda ação de criação, atualização e exclusão que o DefectDojo registra + no seu log de auditoria, além do que é capturado e como configurar a retenção. +draft: false +weight: 4 +--- + +O DefectDojo registra uma trilha de auditoria das alterações em seus dados. Todo objeto rastreado +registra automaticamente eventos de **criação**, **atualização** e **exclusão**, e as tabelas de relacionamento +(muitos-para-muitos) registram eventos de **adição** e **remoção**. + +## Como funciona + +O rastreamento de auditoria é conduzido por triggers de banco de dados registrados por modelo. Para cada +objeto rastreado, três tipos de evento podem ser disparados: + +| Tipo de evento | Quando é disparado | Ação | +| ------------- | ----------------------------------------------------------------------------- | ---------- | +| `InsertEvent` | Um novo registro é criado | **Criação** | +| `UpdateEvent` | Um registro é alterado — apenas quando o valor de um campo realmente muda | **Atualização** | +| `DeleteEvent` | Um registro é excluído | **Exclusão** | + +As tabelas de relacionamento muitos-para-muitos (tags, revisores, faixas de IP do firewall) rastreiam +apenas **adição** (`InsertEvent`) e **remoção** (`DeleteEvent`) — não existe +"atualização" para uma linha de relacionamento. + +### O que é capturado em cada evento + +- **Quem** — o usuário que executou a ação, obtido do contexto da requisição. +- **Quando** — um timestamp. +- **IP de origem** — o endereço remoto, respeitando as cadeias de proxy `X-Forwarded-For`. +- **Snapshot antes/depois** — os valores completos dos campos do registro. +- **Contexto / rótulo** — agrupa eventos originados da mesma requisição. O rótulo + `initial_backfill` marca registros históricos importados quando o rastreamento foi + ativado pela primeira vez. + +Eventos produzidos por jobs em segundo plano são reconectados ao contexto da +requisição de origem, de modo que uma ação concluída de forma assíncrona ainda é +atribuída ao usuário que a disparou. + +## Core (Open Source) — ações rastreadas + +| Objeto | Criação | Atualização | Exclusão | Notas | +| ------------------------------ | :----: | :----: | :----: | ---------------------------------------------- | +| Usuário | ✅ | ✅ | ✅ | `password` excluído dos snapshots | +| Tipo de Produto | ✅ | ✅ | ✅ | | +| Produto | ✅ | ✅ | ✅ | | +| Engajamento | ✅ | ✅ | ✅ | | +| Teste | ✅ | ✅ | ✅ | | +| Achado | ✅ | ✅ | ✅ | | +| Grupo de Achados | ✅ | ✅ | ✅ | | +| Modelo de Achado | ✅ | ✅ | ✅ | | +| Aceitação de risco | ✅ | ✅ | ✅ | | +| Endpoint | ✅ | ✅ | ✅ | | +| Localização | ✅ | ✅ | ✅ | | +| URL | ✅ | ✅ | ✅ | | +| Webhook de Notificação | ✅ | ✅ | ✅ | `header_name` / `header_value` excluídos (segredos) | + +### Core — eventos de relacionamento (adição / remoção) + +| Relacionamento | Adição | Remoção | +| ---------------------------------- | :-: | :----: | +| Achado → Revisores | ✅ | ✅ | +| Achado → Tags | ✅ | ✅ | +| Achado → Tags Herdadas | ✅ | ✅ | +| Produto → Tags | ✅ | ✅ | +| Engajamento → Tags | ✅ | ✅ | +| Engajamento → Tags Herdadas | ✅ | ✅ | +| Teste → Tags | ✅ | ✅ | +| Teste → Tags Herdadas | ✅ | ✅ | +| Endpoint → Tags | ✅ | ✅ | +| Endpoint → Tags Herdadas | ✅ | ✅ | +| Modelo de Achado → Tags | ✅ | ✅ | +| App Analysis (Tecnologia) → Tags | ✅ | ✅ | +| Objects/Product → Tags | ✅ | ✅ | + +## Pro — ações rastreadas + +| Objeto | Criação | Atualização | Exclusão | Notas | +| --------------------------------- | :----: | :----: | :----: | ------------------------------ | +| Achado Aprimorado | ✅ | ✅ | ✅ | Complemento Pro do Achado | +| Regra | ✅ | ✅ | ✅ | Mecanismo de regras | +| Ação de Regra | ✅ | ✅ | ✅ | | +| Condição de Ação de Regra | ✅ | ✅ | ✅ | | +| Entrada de Filtro de Regra | ✅ | ✅ | ✅ | | +| Operação do Mecanismo de Regras | ✅ | ✅ | ✅ | | +| Mensagem de Operação do Mecanismo de Regras | ✅ | ✅ | ✅ | | +| Tarefa Agendada | ✅ | ✅ | ✅ | | +| Execução de Tarefa Agendada | ✅ | ✅ | ✅ | | +| Política de Mitigação | ✅ | ✅ | ✅ | | +| Configuração Ajustável | ✅ | ✅ | ✅ | Alterações de configuração do sistema | +| Estado do Feature Flag | ✅ | ✅ | ✅ | Ativação/desativação de flags + fixações do sistema | +| Definição do Feature Flag | ✅ | ✅ | ✅ | Metadados / sincronização de registro | +| Firewall de Nuvem | ✅ | ✅ | ✅ | Campo `locked` excluído | +| Máscara de IP do Firewall | ✅ | ✅ | ✅ | | + +### Pro — RBAC / permissões + +| Objeto | Criação | Atualização | Exclusão | +| ----------------------------- | :----: | :----: | :----: | +| Grupo | ✅ | ✅ | ✅ | +| Papel | ✅ | ✅ | ✅ | +| Associação a Grupo | ✅ | ✅ | ✅ | +| Papel Global | ✅ | ✅ | ✅ | +| Atribuição de Grupo a Produto | ✅ | ✅ | ✅ | +| Atribuição de Grupo a Tipo de Produto | ✅ | ✅ | ✅ | +| Membro do Produto | ✅ | ✅ | ✅ | +| Membro do Tipo de Produto | ✅ | ✅ | ✅ | + +### Pro — eventos de relacionamento (adição / remoção) + +| Relacionamento | Adição | Remoção | +| --------------------------- | :-: | :----: | +| Firewall de Nuvem → Faixas de IP | ✅ | ✅ | + +## Configuração e retenção (Controles On-Premise) + +| Configuração | Variável de ambiente | Padrão | Efeito | +| -------------------- | ------------------------------------- | ------------------ | ------------------------------------------------------------------ | +| Ativar log de auditoria | `DD_ENABLE_AUDITLOG` | `True` | Quando definido como `False`, todos os triggers de histórico são desativados e nenhum evento é registrado | +| Período de retenção | `DD_AUDITLOG_FLUSH_RETENTION_PERIOD` | `-1` (nunca limpa) | Meses de histórico a manter; eventos mais antigos são excluídos em lotes pelo job de limpeza | +| Tamanho do lote de limpeza | `DD_AUDITLOG_FLUSH_BATCH_SIZE` | `1000` | Linhas excluídas por lote durante a limpeza | +| Máximo de lotes de limpeza | `DD_AUDITLOG_FLUSH_MAX_BATCHES` | `100` | Limite do número de lotes por execução de limpeza | + +## Observações e limitações + +- **Segredos nunca são capturados.** As senhas de usuário e os valores de cabeçalho dos webhooks de notificação + são explicitamente excluídos dos snapshots de eventos. +- **As atualizações só são registradas quando há uma mudança real.** Um salvamento que não altera nenhum + valor de campo não gera um evento de atualização; campos gerenciados automaticamente, como + `last_updated` isoladamente, não disparam um evento. +- **Eventos de autenticação não são capturados aqui.** Apenas + mudanças de dados. As atividades de login, logout e tentativas de login malsucedidas são tratadas separadamente e não fazem parte deste log de auditoria. diff --git a/docs/content/admin/user_management/PRO__audit_log_index.zh-hans.md b/docs/content/admin/user_management/PRO__audit_log_index.zh-hans.md new file mode 100644 index 0000000000..ba8906a9e8 --- /dev/null +++ b/docs/content/admin/user_management/PRO__audit_log_index.zh-hans.md @@ -0,0 +1,122 @@ +--- +title: 审计日志 +description: DefectDojo 审计日志中记录的每一次创建、更新和删除操作，以及所捕获的内容和保留期限的配置方法。 +draft: false +weight: 4 +--- + +DefectDojo 会记录其数据变更的审计跟踪。每个被跟踪的对象都会自动记录**创建（create）**、**更新（update）**和**删除（delete）**事件，而关系（多对多）表则记录**添加（add）**和**移除（remove）**事件。 + +## 工作原理 + +审计跟踪由针对每个模型注册的数据库触发器驱动。对于每个被跟踪的对象，可能触发三种事件类型： + +| 事件类型 | 触发时机 | 操作 | +| ------------- | ----------------------------------------------------------------------------- | ---------- | +| `InsertEvent` | 新建一条记录时 | **创建（Create）** | +| `UpdateEvent` | 记录发生变化时——仅当某个字段的值确实发生了变化 | **更新（Update）** | +| `DeleteEvent` | 删除一条记录时 | **删除（Delete）** | + +多对多关系表（标签、审阅人、防火墙 IP 范围）只跟踪**添加**（`InsertEvent`）和**移除**（`DeleteEvent`）——关系行没有"更新"这一说。 + +### 每个事件都会捕获的内容 + +- **Who（操作者）** — 执行操作的用户，取自请求上下文。 +- **When（时间）** — 一个时间戳。 +- **Source IP（来源 IP）** — 远程地址，会遵循 `X-Forwarded-For` 代理链。 +- **Before/after snapshot（变更前后快照）** — 该记录的完整字段值。 +- **Context / label（上下文/标签）** — 将源自同一请求的事件归为一组。标签 + `initial_backfill` 用于标记在审计跟踪首次启用时导入的历史记录。 + +后台任务产生的事件会被追溯拼接回其源请求的上下文，因此即使某个操作是异步完成的，依然会归属于触发它的用户。 + +## 核心版（开源）— 已跟踪的操作 + +| 对象 | 创建 | 更新 | 删除 | 说明 | +| ------------------------------ | :----: | :----: | :----: | ---------------------------------------------- | +| User（用户） | ✅ | ✅ | ✅ | 快照中排除 `password` 字段 | +| Product Type（产品类型） | ✅ | ✅ | ✅ | | +| Product（产品） | ✅ | ✅ | ✅ | | +| Engagement（测试活动） | ✅ | ✅ | ✅ | | +| Test（测试） | ✅ | ✅ | ✅ | | +| Finding（发现项） | ✅ | ✅ | ✅ | | +| Finding Group（发现项组） | ✅ | ✅ | ✅ | | +| Finding Template（发现项模板） | ✅ | ✅ | ✅ | | +| Risk Acceptance（风险接受） | ✅ | ✅ | ✅ | | +| Endpoint（端点） | ✅ | ✅ | ✅ | | +| Location（位置） | ✅ | ✅ | ✅ | | +| URL | ✅ | ✅ | ✅ | | +| Notification Webhook（通知 Webhook） | ✅ | ✅ | ✅ | 排除 `header_name` / `header_value`（敏感信息） | + +### 核心版 — 关系（添加/移除）事件 + +| 关系 | 添加 | 移除 | +| ---------------------------------- | :-: | :----: | +| Finding → Reviewers（发现项 → 审阅人） | ✅ | ✅ | +| Finding → Tags（发现项 → 标签） | ✅ | ✅ | +| Finding → Inherited Tags（发现项 → 继承标签） | ✅ | ✅ | +| Product → Tags（产品 → 标签） | ✅ | ✅ | +| Engagement → Tags（测试活动 → 标签） | ✅ | ✅ | +| Engagement → Inherited Tags（测试活动 → 继承标签） | ✅ | ✅ | +| Test → Tags（测试 → 标签） | ✅ | ✅ | +| Test → Inherited Tags（测试 → 继承标签） | ✅ | ✅ | +| Endpoint → Tags（端点 → 标签） | ✅ | ✅ | +| Endpoint → Inherited Tags（端点 → 继承标签） | ✅ | ✅ | +| Finding Template → Tags（发现项模板 → 标签） | ✅ | ✅ | +| App Analysis (Technology) → Tags（应用分析（技术）→ 标签） | ✅ | ✅ | +| Objects/Product → Tags（对象/产品 → 标签） | ✅ | ✅ | + +## Pro 版 — 已跟踪的操作 + +| 对象 | 创建 | 更新 | 删除 | 说明 | +| --------------------------------- | :----: | :----: | :----: | ------------------------------ | +| Enhanced Finding（增强型发现项） | ✅ | ✅ | ✅ | Finding 在 Pro 版中的配套对象 | +| Rule（规则） | ✅ | ✅ | ✅ | 规则引擎 | +| Rule Action（规则动作） | ✅ | ✅ | ✅ | | +| Rule Action Condition（规则动作条件） | ✅ | ✅ | ✅ | | +| Rule Filter Entry（规则筛选条目） | ✅ | ✅ | ✅ | | +| Rules Engine Operation（规则引擎操作） | ✅ | ✅ | ✅ | | +| Rules Engine Operation Message（规则引擎操作消息） | ✅ | ✅ | ✅ | | +| Scheduled Task（计划任务） | ✅ | ✅ | ✅ | | +| Scheduled Task Run（计划任务运行） | ✅ | ✅ | ✅ | | +| Mitigation Policy（缓解策略） | ✅ | ✅ | ✅ | | +| Tunable Setting（可调设置） | ✅ | ✅ | ✅ | 系统配置变更 | +| Feature Flag State（功能开关状态） | ✅ | ✅ | ✅ | 开关切换 + 系统固定项 | +| Feature Flag Definition（功能开关定义） | ✅ | ✅ | ✅ | 元数据/注册表同步 | +| Cloud Firewall（云防火墙） | ✅ | ✅ | ✅ | 排除 `locked` 字段 | +| Firewall IP Mask（防火墙 IP 掩码） | ✅ | ✅ | ✅ | | + +### Pro 版 — RBAC/权限 + +| 对象 | 创建 | 更新 | 删除 | +| ----------------------------- | :----: | :----: | :----: | +| Group（组） | ✅ | ✅ | ✅ | +| Role（角色） | ✅ | ✅ | ✅ | +| Group Membership（组成员身份） | ✅ | ✅ | ✅ | +| Global Role（全局角色） | ✅ | ✅ | ✅ | +| Product Group Assignment（产品组分配） | ✅ | ✅ | ✅ | +| Product Type Group Assignment（产品类型组分配） | ✅ | ✅ | ✅ | +| Product Member（产品成员） | ✅ | ✅ | ✅ | +| Product Type Member（产品类型成员） | ✅ | ✅ | ✅ | + +### Pro 版 — 关系（添加/移除）事件 + +| 关系 | 添加 | 移除 | +| --------------------------- | :-: | :----: | +| Cloud Firewall → IP Ranges（云防火墙 → IP 范围） | ✅ | ✅ | + +## 配置与保留（本地部署控制项） + +| 设置项 | 环境变量 | 默认值 | 作用 | +| -------------------- | -------------------------------------- | ------------------ | ------------------------------------------------------------------ | +| 启用审计日志 | `DD_ENABLE_AUDITLOG` | `True` | 设为 `False` 时，所有历史触发器都会被禁用，不再记录任何事件 | +| 保留期限 | `DD_AUDITLOG_FLUSH_RETENTION_PERIOD` | `-1`（永不清理） | 保留历史记录的月数；更早的事件会由清理任务批量删除 | +| 清理批次大小 | `DD_AUDITLOG_FLUSH_BATCH_SIZE` | `1000` | 清理过程中每批删除的行数 | +| 单次清理最大批次数 | `DD_AUDITLOG_FLUSH_MAX_BATCHES` | `100` | 每次清理运行的批次数量上限 | + +## 说明与限制 + +- **绝不会捕获敏感信息。** 用户密码和通知 Webhook 的请求头值会被明确排除在事件快照之外。 +- **只有发生真实变更时才会记录更新。** 未改变任何字段值的保存操作不会产生更新事件；仅有 + `last_updated` 等自动维护字段发生变化也不会触发更新事件。 +- **身份验证事件不在此处记录。** 这里只记录数据变更。登录、登出和登录失败等活动由其他机制单独处理，不属于本审计日志的一部分。 diff --git a/docs/content/admin/user_management/PRO__audit_logging.it.md b/docs/content/admin/user_management/PRO__audit_logging.it.md new file mode 100644 index 0000000000..b93921db22 --- /dev/null +++ b/docs/content/admin/user_management/PRO__audit_logging.it.md @@ -0,0 +1,110 @@ +--- +title: Log di audit +description: Accedi ai log di audit per gli oggetti DefectDojo +weight: 1 +audience: pro +--- + +I **Log di audit** forniscono un registro cronologico delle azioni eseguite all'interno di DefectDojo. Garantiscono responsabilità e conformità registrando quale utente ha eseguito quale azione e quando. + +I log di audit sono utili per: +- **Indagini di sicurezza**: determinare chi ha eseguito azioni sensibili. +- **Conformità**: dimostrare una cronologia verificabile per standard come SOC 2, ISO 27001 o requisiti di governance interni. +- **Risoluzione dei problemi**: identificare quando una configurazione o un oggetto è cambiato. +- **Responsabilità**: tracciare l'attività amministrativa e degli utenti sulla piattaforma. + +In sintesi, i Log di audit forniscono un registro centralizzato degli eventi importanti che aiuta gli amministratori a comprendere la cronologia delle attività della propria istanza, al di là della cronologia di un singolo oggetto. + +### Accesso ai Log di audit + +I Log di audit sono accessibili tramite la barra laterale, all'interno del sottomenu Configurazioni. + +![image](images/auditlogs_ss2.png) + +### Autorizzazioni + +L'accesso ai Log di audit è determinato dal ruolo globale di un Utente. + +I ruoli globali API Importer, Reader e Writer non consentono l'accesso ai Log di audit, mentre i ruoli Maintainer e Owner sì. Anche i Superuser hanno accesso ai Log di audit indipendentemente dal proprio ruolo globale. + +Ulteriori informazioni sulle autorizzazioni e sui ruoli globali sono disponibili [qui](/admin/user_management/pro_permissions_overhaul/). + +## Contenuto dei Log di audit + +I Log di audit tracciano una varietà di azioni, tra cui, a titolo esemplificativo ma non esaustivo: +- Interazioni con gli oggetti (ad es. creazione, aggiornamento o eliminazione di oggetti). +- Aggiornamenti alla priorità e al punteggio di rischio di un Riscontro. +- Creazione e modifica dei profili Utente. +- Aggiornamenti del percentile EPSS. + +L'elenco completo delle modifiche e delle azioni registrate nei Log di audit è disponibile [qui](../pro__audit_log_index/). + +## Tabella dei Log di audit + +I Log di audit includono più colonne con vari dati per migliorare la tracciabilità, tra cui: +- **Timestamp**: il momento in cui è avvenuta la modifica. +- **User**: l'utente che ha eseguito l'azione. +- **Action**: quale azione è stata eseguita (ad es. creazione, aggiornamento, eliminazione). +- **Model**: quale aspetto è stato modificato (ad es. Asset, User, Finding, Location, Firewall, URL, ecc.). +- **Object ID**: l'ID univoco di DefectDojo per l'oggetto modificato. +- **Object Name**: il nome dell'oggetto interessato. +- **Changes**: i campi specifici modificati dall'azione, inclusi i valori precedenti e aggiornati. +- **Data**: uno snapshot esatto del record nel momento in cui è stata eseguita l'azione, inclusi tutti i campi, non solo quelli modificati. +- **Context**: dettagli sul contesto di come è avvenuta la modifica, chi l'ha effettuata, da dove nell'app proviene e un'etichetta che indica quale job ha eseguito la modifica (se si trattava di un job automatizzato). +- **URL**: l'URL utilizzato per eseguire l'operazione specifica. Questi percorsi possono fare riferimento alla Vue UI di DefectDojo o alla REST API. Il campo URL non verrà popolato per i processi back-end. +- **IP Address**: l'indirizzo di rete del dispositivo che ha effettuato la modifica. Non verrà popolato per i processi back-end. + +### Cronologia dei Log di audit + +Per impostazione predefinita, i Log di audit mostrano le voci degli ultimi 31 giorni. Le voci più vecchie restano disponibili e possono essere visualizzate modificando il filtro Timestamp. + +![image](images/auditlogs_ss3.gif) + +### Filtrare i Log di audit + +La tabella dei Log di audit include filtri che aiutano a restringere i risultati visualizzati. Ad esempio, se si desidera vedere solo le azioni relative agli Asset, è possibile filtrare per Asset all'interno della tabella. + +![image](images/auditlogs_ss1.png) + +Le colonne all'interno dei Log di audit possono anche essere ordinate in ordine alfabetico, crescente/decrescente o cronologico, a seconda del contenuto della colonna in questione. Le colonne possono inoltre essere trascinate a sinistra o a destra in base alla disposizione preferita. + +![image](images/auditlogs_ss4.gif) + +## Cronologia oggetto + +La **Cronologia oggetto** fornisce un registro cronologico delle modifiche apportate a un singolo oggetto DefectDojo (ad es. Organization, Asset, Engagement, Test, Riscontri, Endpoint e Accettazioni del rischio). Ogni voce include dettagli come timestamp, utente, azione eseguita e le modifiche associate. + +A differenza dei Log di audit, che registrano eventi sull'intera istanza, la Cronologia oggetto riguarda esclusivamente l'attività di un singolo oggetto, rendendo più facile comprendere la cronologia di un oggetto senza dover filtrare eventi di sistema non correlati. + +La Cronologia oggetto è utile per: +- Rivedere l'evoluzione di un oggetto nel tempo. +- Determinare quando è stata effettuata una modifica. +- Identificare quale utente ha apportato una modifica. +- Risolvere modifiche inattese. + +### Accesso alla Cronologia oggetto + +È possibile accedere alla Cronologia oggetto tramite il menu a forma di ingranaggio nell'angolo in alto a destra della visualizzazione di qualsiasi oggetto. Solo gli Utenti con accesso all'oggetto in questione possono visualizzarne la Cronologia oggetto. + +### Log di audit e Cronologia oggetto + +Sebbene le funzioni di Log di audit e Cronologia oggetto si sovrappongano, operano su ambiti diversi. La Cronologia oggetto si concentra sulle modifiche apportate ai singoli oggetti, mentre i Log di audit forniscono un registro a livello di sistema degli eventi significativi in tutta l'istanza DefectDojo, offrendo una visione più ampia e d'insieme dell'attività. + +## Endpoint + +### Endpoint della Cronologia oggetto (solo Pro) + +Gli utenti DefectDojo Pro hanno accesso a un percorso API `/history` per questi oggetti per visualizzare dati simili. Ad esempio: `/api/v2/findings/{id}/history/`. + +### Endpoint dei Log di audit (solo Pro) + +Gli utenti DefectDojo Pro hanno inoltre accesso a un endpoint dedicato `/audit_log` per l'intera istanza. Questo log è accessibile solo da utenti o token API con autorizzazioni superuser. + +Questa API restituisce 31 giorni di log di audit. + +* L'invio di parametri predefiniti o vuoti restituirà gli ultimi 31 giorni di log di audit. + +* Il parametro `window_month` accetta un mese e un anno nel formato MM-YYYY e fornisce i log di audit per quel mese. +* È possibile impostare il parametro `window_start` per limitare questi log a un intervallo più breve, invece di restituire l'intero mese. + +Per ulteriori informazioni, consulta la documentazione API disponibile nella tua istanza: `your-instance.cloud.defectdojo.com/api/v2/oa3/swagger-ui/`. diff --git a/docs/content/admin/user_management/PRO__audit_logging.pt-br.md b/docs/content/admin/user_management/PRO__audit_logging.pt-br.md new file mode 100644 index 0000000000..389db05726 --- /dev/null +++ b/docs/content/admin/user_management/PRO__audit_logging.pt-br.md @@ -0,0 +1,110 @@ +--- +title: Logs de Auditoria +description: Acesse os logs de auditoria de objetos do DefectDojo +weight: 1 +audience: pro +--- + +**Logs de Auditoria** fornecem um registro cronológico das ações realizadas no DefectDojo. Eles garantem responsabilização e conformidade ao registrar qual usuário realizou qual ação e quando. + +Os logs de auditoria são valiosos para: +- **Investigações de segurança**: Determinar quem realizou ações sensíveis. +- **Conformidade**: Demonstrar um histórico auditável para padrões como SOC 2, ISO 27001, ou requisitos internos de governança. +- **Solução de problemas**: Identificar quando uma configuração ou objeto foi alterado. +- **Responsabilização**: Rastrear a atividade administrativa e de usuários em toda a plataforma. + +Em resumo, os Logs de Auditoria fornecem um registro centralizado de eventos importantes que ajuda os administradores a entender o histórico de atividades de sua instância além do histórico de qualquer objeto individual. + +### Acessando os Logs de Auditoria + +Os Logs de Auditoria são acessíveis pela barra lateral, dentro do submenu Configurations. + +![image](images/auditlogs_ss2.png) + +### Permissões + +O acesso aos Logs de Auditoria é determinado pela função global de um Usuário. + +As funções globais de API Importer, Reader e Writer não permitem acesso aos Logs de Auditoria, enquanto as funções Maintainer e Owner permitem. Superusuários também têm acesso aos Logs de Auditoria independentemente de sua função global. + +Mais informações sobre permissões e funções globais podem ser encontradas [aqui](/admin/user_management/pro_permissions_overhaul/). + +## Conteúdo dos Logs de Auditoria + +Os Logs de Auditoria rastreiam uma variedade de ações, incluindo, mas não se limitando a: +- Interações com objetos (por exemplo, criar, atualizar ou excluir objetos). +- Atualizações na prioridade e no risk score de um Achado. +- Criação e edição de perfis de Usuário. +- Atualizações de percentil EPSS. + +A lista completa de alterações e ações capturadas nos Logs de Auditoria pode ser encontrada [aqui](../pro__audit_log_index/). + +## Tabela de Logs de Auditoria + +Os Logs de Auditoria incluem várias colunas com diferentes dados para melhorar a rastreabilidade, incluindo: +- **Timestamp**: O momento em que a alteração ocorreu. +- **User**: O usuário que realizou a ação. +- **Action**: Qual ação foi realizada (por exemplo, criar, atualizar, excluir). +- **Model**: Qual aspecto foi modificado (por exemplo, Asset, User, Finding, Location, Firewall, URL, etc.). +- **Object ID**: O ID exclusivo do DefectDojo para o objeto que foi modificado. +- **Object Name**: O nome do objeto afetado. +- **Changes**: Campos específicos modificados pela ação, incluindo seus valores anteriores e atualizados. +- **Data**: Um snapshot exato do registro no momento em que a ação foi realizada, incluindo todos os campos, não apenas os que foram alterados. +- **Context**: Detalhes sobre como a alteração aconteceu, quem a fez, de onde no aplicativo ela veio, e um rótulo indicando qual job realizou a alteração (se foi um job automatizado). +- **URL**: A URL usada para executar a operação em questão. Esses caminhos podem se referir à Vue UI do DefectDojo, ou à API REST. O campo URL não será preenchido para processos de back-end. +- **IP Address**: O endereço de rede do dispositivo que fez a alteração. Isso não será preenchido para processos de back-end. + +### Linha do Tempo dos Logs de Auditoria + +Por padrão, os Logs de Auditoria exibem entradas dos últimos 31 dias. Entradas mais antigas permanecem disponíveis e podem ser visualizadas ajustando o filtro Timestamp. + +![image](images/auditlogs_ss3.gif) + +### Filtrando os Logs de Auditoria + +A tabela de Logs de Auditoria inclui filtros para ajudar a restringir os resultados exibidos. Por exemplo, se você quisesse ver apenas ações referentes a Assets, poderia filtrar por Assets dentro da tabela. + +![image](images/auditlogs_ss1.png) + +As colunas dentro dos Logs de Auditoria também podem ser organizadas em ordem alfabética, crescente/decrescente, ou cronológica, dependendo do conteúdo da coluna em questão. As colunas também podem ser arrastadas para a esquerda ou para a direita, conforme o arranjo preferido. + +![image](images/auditlogs_ss4.gif) + +## Histórico do Objeto + +O **Histórico do Objeto** fornece um registro cronológico das alterações feitas em um objeto individual do DefectDojo (por exemplo, Organization, Asset, Engagement, Test, Findings, Endpoints e Risk Acceptances). Cada entrada inclui detalhes como o timestamp, o usuário, a ação realizada e as alterações associadas. + +Diferente dos Logs de Auditoria, que registram eventos em toda a instância, o Histórico do Objeto diz respeito estritamente à atividade de um único objeto, facilitando o entendimento do histórico de um objeto sem precisar filtrar eventos de sistema não relacionados. + +O Histórico do Objeto é útil para: +- Revisar a progressão de um objeto ao longo do tempo. +- Determinar quando uma alteração foi feita. +- Identificar qual usuário fez uma modificação. +- Solucionar alterações inesperadas. + +### Acessando o Histórico do Objeto + +O Histórico do Objeto pode ser acessado pelo menu de engrenagem no canto superior direito da visualização de qualquer objeto. Somente Usuários com acesso ao objeto em questão podem visualizar o Histórico do Objeto correspondente. + +### Logs de Auditoria e Histórico do Objeto + +Embora a função dos Logs de Auditoria e do Histórico do Objeto se sobreponha, eles operam em escopos diferentes. O Histórico do Objeto foca nas alterações feitas em objetos individuais, enquanto os Logs de Auditoria fornecem um registro de eventos significativos em toda a sua instância do DefectDojo, oferecendo uma visão mais ampla, de "visão de pássaro", da atividade. + +## Endpoints + +### Endpoint de Histórico do Objeto (Somente Pro) + +Usuários do DefectDojo Pro têm acesso a um caminho de API `/history` para esses objetos, a fim de visualizar dados semelhantes. Por exemplo: `/api/v2/findings/{id}/history/`. + +### Endpoint de Log de Auditoria (Somente Pro) + +Usuários do DefectDojo Pro também têm acesso a um endpoint dedicado `/audit_log` para toda a sua instância. Este log só pode ser acessado por usuários ou tokens de API com permissões de superusuário. + +Esta API retorna 31 dias de logs de auditoria. + +* Enviar parâmetros padrão ou vazios retornará os últimos 31 dias de logs de auditoria. + +* O parâmetro `window_month` recebe um mês e ano no formato MM-YYYY e fornece os logs de auditoria daquele mês. +* Você pode definir o parâmetro `window_start` para limitar esses logs a uma janela mais curta, em vez de retornar o mês inteiro. + +Para mais informações, consulte a documentação da API, localizada em sua instância: `your-instance.cloud.defectdojo.com/api/v2/oa3/swagger-ui/` diff --git a/docs/content/admin/user_management/PRO__audit_logging.zh-hans.md b/docs/content/admin/user_management/PRO__audit_logging.zh-hans.md new file mode 100644 index 0000000000..e64d9f22cd --- /dev/null +++ b/docs/content/admin/user_management/PRO__audit_logging.zh-hans.md @@ -0,0 +1,110 @@ +--- +title: 审计日志 +description: 访问 DefectDojo 对象的审计日志 +weight: 1 +audience: pro +--- + +**审计日志**提供了 DefectDojo 内所执行操作的时间顺序记录。它们通过记录哪个用户在何时执行了何种操作,确保问责制和合规性。 + +审计日志在以下方面很有价值: +- **安全调查**:确定谁执行了敏感操作。 +- **合规性**:为 SOC 2、ISO 27001 等标准或内部治理要求提供可审计的历史记录。 +- **故障排查**:确定配置或对象何时发生变更。 +- **问责制**:跟踪整个平台上的管理和用户活动。 + +简而言之,审计日志提供了重要事件的集中记录,帮助管理员了解其实例的活动历史,而不仅限于任何单个对象的历史记录。 + +### 访问审计日志 + +审计日志可通过侧边栏中"配置(Configurations)"子菜单访问。 + +![image](images/auditlogs_ss2.png) + +### 权限 + +对审计日志的访问权限由用户的全局角色决定。 + +API 导入者(API Importer)、只读者(Reader)和编写者(Writer)全局角色无权访问审计日志,而维护者(Maintainer)和所有者(Owner)角色则可以访问。无论全局角色如何,超级用户也可以访问审计日志。 + +有关权限和全局角色的更多信息,请参见[此处](/admin/user_management/pro_permissions_overhaul/)。 + +## 审计日志内容 + +审计日志跟踪各种操作,包括但不限于: +- 与对象的交互(例如创建、更新或删除对象)。 +- 发现项优先级和风险评分的更新。 +- 用户档案的创建和编辑。 +- EPSS 百分位数的更新。 + +审计日志中记录的变更和操作的完整列表可在[此处](../pro__audit_log_index/)查看。 + +## 审计日志表 + +审计日志包含多个列,提供各种数据以提高可追溯性,包括: +- **时间戳(Timestamp)**:变更发生的时间。 +- **用户(User)**:执行操作的用户。 +- **操作(Action)**:执行了何种操作(例如创建、更新、删除)。 +- **模型(Model)**:修改了哪个方面(例如资产、用户、发现项、位置、防火墙、URL 等)。 +- **对象 ID(Object ID)**:DefectDojo 为被修改对象分配的唯一 ID。 +- **对象名称(Object Name)**:受影响对象的名称。 +- **变更(Changes)**:该操作修改的具体字段,包括其修改前后的值。 +- **数据(Data)**:操作执行时刻记录的精确快照,包含每一个字段,而不仅仅是发生变更的字段。 +- **上下文(Context)**:变更发生方式的周边细节,包括是谁做出的变更、来自应用中的哪个位置,以及一个说明是哪个作业执行了该变更的标签(如果是自动化作业所为)。 +- **URL**:用于执行该特定操作的 URL。这些路径可能指向 DefectDojo 的 Vue UI,也可能指向 REST API。对于后端流程,不会填充 URL 字段。 +- **IP 地址(IP Address)**:发起变更的设备的网络地址。对于后端流程,不会填充此字段。 + +### 审计日志时间线 + +默认情况下,审计日志显示过去 31 天的条目。较早的条目仍然可用,可以通过调整时间戳筛选器查看。 + +![image](images/auditlogs_ss3.gif) + +### 筛选审计日志 + +审计日志表包含筛选器,以帮助缩小显示结果的范围。例如,如果您只想查看与资产相关的操作,可以在表中筛选资产。 + +![image](images/auditlogs_ss1.png) + +审计日志中的列还可以根据相应列的内容按字母顺序、升序/降序或时间顺序排列。也可以根据首选排列方式将列向左或向右拖动。 + +![image](images/auditlogs_ss4.gif) + +## 对象历史记录 + +**对象历史记录**提供了对单个 DefectDojo 对象(例如组织、资产、测试活动、测试、发现项、端点和风险接受)所做变更的时间顺序记录。每条记录都包含时间戳、用户、执行的操作以及相关变更等详细信息。 + +与记录整个实例范围内事件的审计日志不同,对象历史记录仅涉及单个对象的活动,因此更容易在不筛选无关系统事件的情况下了解某个对象的历史记录。 + +对象历史记录适用于以下场景: +- 回顾对象随时间的演变过程。 +- 确定变更发生的时间。 +- 确定是哪个用户进行了修改。 +- 排查意外变更。 + +### 访问对象历史记录 + +可以通过任意对象视图右上角的齿轮菜单访问对象历史记录。只有对相关对象拥有访问权限的用户才能查看该对象的对象历史记录。 + +### 审计日志与对象历史记录 + +尽管审计日志和对象历史记录的功能有所重叠,但它们的作用范围不同。对象历史记录专注于对单个对象所做的变更,而审计日志则提供整个 DefectDojo 实例中重要事件的系统级记录,提供更广泛的、鸟瞰式的活动视图。 + +## 端点 + +### 对象历史记录端点(仅限 Pro) + +DefectDojo Pro 用户可以通过 `/history` API 路径访问这些对象以查看类似的数据。例如:`/api/v2/findings/{id}/history/`。 + +### 审计日志端点(仅限 Pro) + +DefectDojo Pro 用户还可以为其整个实例访问专用的 `/audit_log` 端点。此日志只能由拥有超级用户权限的用户或 API 令牌访问。 + +此 API 返回 31 天的审计日志。 + +* 发送默认或空参数将返回最近 31 天的审计日志。 + +* 参数 `window_month` 接受 MM-YYYY 格式的月份和年份,并提供该月份的审计日志。 +* 您可以设置 `window_start` 参数,将这些日志限制在更短的时间窗口内,而不是返回整个月份的日志。 + +有关更多信息,请参阅位于您实例中的 API 文档:`your-instance.cloud.defectdojo.com/api/v2/oa3/swagger-ui/` diff --git a/docs/content/admin/user_management/PRO__creating_new_users.it.md b/docs/content/admin/user_management/PRO__creating_new_users.it.md new file mode 100644 index 0000000000..2b0d3d54e0 --- /dev/null +++ b/docs/content/admin/user_management/PRO__creating_new_users.it.md @@ -0,0 +1,42 @@ +--- +title: Creare un nuovo utente +description: Come inserire un nuovo utente nella tua istanza DefectDojo +audience: pro +weight: 1 +--- + +Questa pagina descrive il flusso di lavoro consigliato per l'onboarding di nuovi utenti in un'istanza DefectDojo. Gli utenti DefectDojo possono essere utilizzati sia come account standard, gestiti da persone, sia come account di servizio. + +L'amministratore che crea l'account è responsabile della consegna delle credenziali iniziali (nome utente e password) al nuovo utente. + +## Flusso di lavoro consigliato + +1. **Crea l'account utente** in DefectDojo (solo Superuser): + * Vai su **👤 Utenti → ➕ Nuovo utente**. + * Inserisci il nome e l'indirizzo email del nuovo utente. + * Imposta una password temporanea. + * Invia il modulo. + +2. **Assegna le autorizzazioni** in base alle esigenze: appartenenza a Prodotto/Tipo di prodotto, Autorizzazioni di configurazione, Ruolo globale o stato Superuser. Per i dettagli, consulta [Impostare le autorizzazioni di un Utente](../set_user_permissions/). Un nuovo utente senza alcuna assegnazione non potrà visualizzare alcun Prodotto o Riscontro. + +3. **Invia le credenziali al nuovo utente tramite un canale separato** (email, lo strumento di chat del tuo team o qualunque modo tu usi normalmente per condividere segreti). Includi: + * L'URL dell'istanza DefectDojo. + * Il nome utente (in genere il suo indirizzo email). + * La password temporanea appena impostata. + * Una nota che indichi di cambiare la password e abilitare l'MFA (se la tua istanza utilizza l'MFA) al primo accesso. + +4. **Il nuovo utente effettua l'accesso e sostituisce la credenziale.** Può: + * Accedere con la password temporanea e poi cambiarla dal menu del proprio profilo, oppure + * Utilizzare il link **I forgot my password** nella pagina di accesso per impostare direttamente una password senza usare quella temporanea. La password temporanea resta comunque necessaria per l'esistenza del record iniziale dell'account, ma l'utente non deve ricordarla se utilizza il flusso di reimpostazione della password. + +5. **Il nuovo utente configura l'MFA** dal proprio menu del profilo. Consigliamo vivamente di richiedere l'MFA per tutti gli utenti sulle istanze non protette da SSO. + +## Utenti SSO + +Se la tua istanza è configurata con [SSO](../configure_sso/), il flusso di lavoro è diverso: gli utenti vengono in genere creati al primo accesso dall'Identity Provider ed è necessario solo assegnare loro l'appartenenza a un gruppo o i ruoli in un secondo momento. + +## Recupero da un token MFA perso + +Se un utente perde l'accesso al proprio dispositivo MFA, può accedere utilizzando uno dei codici di recupero emessi al momento della registrazione. Se anche questi sono andati persi, un amministratore con accesso al server può rimuovere l'MFA dall'account con `python manage.py remove_mfa --username `, dopodiché l'utente accede con la propria password e si registra nuovamente: le sue autorizzazioni e la sua cronologia vengono preservate, quindi non è necessario creare un account sostitutivo. + +Consulta [Autenticazione a più fattori (MFA)](../pro__mfa/#recovering-a-user-who-has-lost-their-mfa-device) per tutte le opzioni di recupero, e tieni presente che l'accesso al **Cloud Manager** in sé è una questione separata: consulta la [guida alla risoluzione dei problemi di connettività](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes). diff --git a/docs/content/admin/user_management/PRO__creating_new_users.pt-br.md b/docs/content/admin/user_management/PRO__creating_new_users.pt-br.md new file mode 100644 index 0000000000..604dd87b01 --- /dev/null +++ b/docs/content/admin/user_management/PRO__creating_new_users.pt-br.md @@ -0,0 +1,42 @@ +--- +title: Criando um novo usuário +description: Como integrar um novo usuário à sua instância do DefectDojo +audience: pro +weight: 1 +--- + +Esta página descreve o fluxo de integração recomendado para adicionar novos usuários a uma instância do DefectDojo. Usuários do DefectDojo podem ser usados tanto como contas padrão, operadas por humanos, quanto como contas de serviço. + +O administrador que cria a conta é responsável por entregar as credenciais iniciais (nome de usuário e senha) ao novo usuário. + +## Fluxo recomendado + +1. **Crie a conta de usuário** no DefectDojo (somente Superusuário): + * Navegue até **👤 Users → ➕ New User**. + * Insira o nome e o endereço de e-mail do novo usuário. + * Defina uma senha temporária. + * Envie o formulário. + +2. **Atribua as permissões** conforme apropriado — associação a Produto/Tipo de Produto, Permissões de Configuração, Função Global, ou status de Superusuário. Consulte [Definir as permissões de um Usuário](../set_user_permissions/) para mais detalhes. Um novo usuário sem nenhuma atribuição não conseguirá ver nenhum Produto ou Achado. + +3. **Envie as credenciais ao novo usuário por um canal separado** (por e-mail, pela ferramenta de chat da sua equipe, ou da forma como você normalmente compartilha segredos). Inclua: + * A URL da instância do DefectDojo. + * O nome de usuário (geralmente o endereço de e-mail). + * A senha temporária que você acabou de definir. + * Uma observação de que o usuário deve trocar a senha e ativar o MFA (se sua instância usar MFA) no primeiro login. + +4. **O novo usuário faz login e rotaciona a credencial.** Ele pode: + * Fazer login com a senha temporária e depois alterá-la pelo menu de perfil, ou + * Usar o link **I forgot my password** na página de login para definir uma senha diretamente, sem usar a temporária. A senha temporária ainda é necessária para que o registro inicial da conta exista, mas o usuário não precisa memorizá-la se usar o fluxo de redefinição de senha. + +5. **O novo usuário configura o MFA** pelo menu de perfil. Recomendamos fortemente exigir MFA para todos os usuários em instâncias que não estejam atrás de SSO. + +## Usuários SSO + +Se sua instância estiver configurada com [SSO](../configure_sso/), o fluxo é diferente — os usuários normalmente são criados no primeiro login a partir do Provedor de Identidade, e você só precisa conceder a eles associação a grupos ou funções posteriormente. + +## Recuperando-se da perda de um token MFA + +Se um usuário perder o acesso ao seu dispositivo MFA, ele pode fazer login com um dos códigos de recuperação emitidos no momento do cadastro. Se esses também tiverem sido perdidos, um administrador com acesso ao servidor pode limpar o MFA da conta com `python manage.py remove_mfa --username `, após o que o usuário faz login com sua senha e se cadastra novamente — suas permissões e seu histórico são preservados, portanto não é necessário criar uma conta substituta. + +Consulte [Autenticação Multifator](../pro__mfa/#recovering-a-user-who-has-lost-their-mfa-device) para conhecer todas as opções de recuperação, e observe que o acesso ao **Cloud Manager** em si é uma questão separada — consulte o [guia de solução de problemas de conectividade](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes). diff --git a/docs/content/admin/user_management/PRO__creating_new_users.zh-hans.md b/docs/content/admin/user_management/PRO__creating_new_users.zh-hans.md new file mode 100644 index 0000000000..8acf285d7e --- /dev/null +++ b/docs/content/admin/user_management/PRO__creating_new_users.zh-hans.md @@ -0,0 +1,42 @@ +--- +title: 创建新用户 +description: 如何将新用户添加到您的 DefectDojo 实例 +audience: pro +weight: 1 +--- + +本页介绍了将新用户添加到 DefectDojo 实例的推荐入职工作流程。DefectDojo 用户既可以作为标准的、由人工操作的账户使用,也可以作为服务账户使用。 + +创建账户的管理员负责将初始凭据(用户名和密码)提供给新用户。 + +## 推荐工作流程 + +1. 在 DefectDojo 中**创建用户账户**(仅限超级用户): + * 导航到 **👤 用户(Users) → ➕ 新建用户(New User)**。 + * 输入新用户的姓名和电子邮件地址。 + * 设置一个临时密码。 + * 提交表单。 + +2. 根据需要**分配权限**——产品/产品类型成员资格、配置权限、全局角色或超级用户状态。详情请参见[设置用户的权限](../set_user_permissions/)。没有任何分配的新用户将无法查看任何产品或发现项。 + +3. **通过带外方式将凭据发送给新用户**(通过电子邮件、团队的聊天工具,或您通常用来共享机密信息的其他方式)。应包含: + * DefectDojo 实例的 URL。 + * 用户名(通常是其电子邮件地址)。 + * 您刚设置的临时密码。 + * 一条提示,告知其应在首次登录时更改密码并启用 MFA(如果您的实例使用 MFA)。 + +4. **新用户登录并轮换凭据。**他们可以选择: + * 使用临时密码登录,然后从个人资料菜单中更改密码;或者 + * 使用登录页面上的**忘记密码**链接,直接设置密码而无需使用临时密码。初始账户记录的存在仍需要临时密码,但如果用户使用密码重置流程,则无需记住该密码。 + +5. **新用户从其个人资料菜单配置 MFA。**我们强烈建议在未使用 SSO 的实例上,要求所有用户启用 MFA。 + +## SSO 用户 + +如果您的实例配置了 [SSO](../configure_sso/),工作流程会有所不同——用户通常在首次通过身份提供商登录时创建,您之后只需为其授予组成员资格或角色。 + +## 从丢失的 MFA 令牌中恢复 + +如果用户无法访问其 MFA 设备,可以使用注册时颁发的恢复代码之一登录。如果这些代码也丢失了,拥有服务器访问权限的管理员可以使用 `python manage.py remove_mfa --username ` 从账户中清除 MFA,之后用户可以使用密码登录并重新注册——其权限和历史记录会被保留,因此无需创建替代账户。 + +有关完整的恢复选项,请参见[多因素身份验证](../pro__mfa/#recovering-a-user-who-has-lost-their-mfa-device);另请注意,访问 **Cloud Manager** 本身是另一回事——请参见[连接故障排查指南](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes)。 diff --git a/docs/content/admin/user_management/PRO__custom_rbac_roles.it.md b/docs/content/admin/user_management/PRO__custom_rbac_roles.it.md new file mode 100644 index 0000000000..af845cd033 --- /dev/null +++ b/docs/content/admin/user_management/PRO__custom_rbac_roles.it.md @@ -0,0 +1,212 @@ +--- +title: Ruoli RBAC personalizzati +description: Crea i tuoi ruoli scegliendo singole autorizzazioni, utilizzando i cinque + ruoli predefiniti come punti di partenza clonabili +weight: 5 +audience: pro +--- + +> **Funzionalità di DefectDojo Pro.** Il sistema RBAC Members / Groups / Global Roles descritto in questa pagina fa parte di DefectDojo Pro. DefectDojo open source utilizza il modello [Authorized Users](../os__authorized_users/). Consulta quella pagina per il controllo degli accessi in open source e le [note di aggiornamento alla 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se stai passando da un'edizione all'altra. + +DefectDojo Pro include cinque ruoli: **Reader**, **Writer**, **Maintainer**, **Owner** e **API Importer**. Se nessuno di questi è adatto, ora puoi creare un tuo ruolo scegliendo esattamente quali autorizzazioni concede. + +Un ruolo personalizzato funziona ovunque funzioni un ruolo predefinito: come Global Role, come ruolo di un Group, come ruolo di gruppo predefinito e come ruolo di membro su una singola Organization o Asset. + +I cinque ruoli predefiniti diventano **preset bloccati e clonabili**. Le loro autorizzazioni restano invariate (consulta le [tabelle delle autorizzazioni per azione](../user_permission_chart/) per sapere cosa concede ciascuno), non possono essere modificati o eliminati, e clonarne uno è il modo consigliato per creare un nuovo ruolo. + +## Prima di iniziare + +La gestione dei ruoli personalizzati è disattivata per impostazione predefinita. Un **superuser** la attiva da **Settings > Feature Flags**, abilitando **Custom Roles**. Consulta [Feature Flags](/admin/feature_flags/pro__feature_flags/) per sapere come funziona quella pagina. + +Quando la funzionalità è disattivata, la pagina Roles resta comunque leggibile: puoi visualizzare i ruoli predefiniti e le relative autorizzazioni, ma non puoi creare, modificare, clonare o eliminare nulla. + +La gestione dei ruoli richiede lo stato di **superuser** o il Global Role predefinito **Owner**. Questa scelta è intenzionale e non può essere delegata a un ruolo personalizzato: consulta [Cosa sblocca un Global Role personalizzato](#what-a-custom-global-role-unlocks). + +## Apertura della pagina Roles + +Vai su **👤 Utenti > Roles** nella barra laterale sinistra. La voce di menu è visibile ai superuser e a chi detiene il Global Role predefinito Owner. + +![La pagina Roles con l'elenco dei ruoli predefiniti e personalizzati](images/pro_roles_list.png) + +La tabella elenca tutti i ruoli della tua istanza: + +| Colonna | Cosa mostra | +| --- | --- | +| **ID** | L'ID numerico del ruolo. Utile per filtrare la tabella Users o per chiamare l'API. | +| **Name** | Il nome del ruolo. | +| **Description** | Una tua nota su a cosa serve il ruolo. Facoltativa, vuota a meno che qualcuno non la compili. I ruoli predefiniti vengono forniti senza. | +| **Permissions** | Un conteggio delle autorizzazioni concesse. Fai clic per aprire una vista di sola lettura della griglia completa. | +| **Users** | Quanti utenti detengono questo ruolo come Global Role. Fai clic per vederli nella tabella Users. | +| **Type** | **Built-in** per i cinque preset, **Custom** per i ruoli creati da te. | + +Ogni colonna è ordinabile e filtrabile, e la ricerca per parole chiave trova corrispondenze su nome e descrizione. + +## Creazione di un ruolo + +### Clonare un ruolo predefinito (consigliato) + +Clonare permette di partire da un set di autorizzazioni già collaudato invece che da una griglia vuota, il che rende molto più difficile dimenticare per errore un'autorizzazione di cui il ruolo ha bisogno. + +1. Trova il ruolo più vicino a quello che desideri. +2. Apri il suo menu **⋮** e scegli **Clone Role**. +3. Viene creata immediatamente una copia, denominata ` (copy)`, con le stesse autorizzazioni e descrizione del ruolo di origine. +4. Apri il menu **⋮** della copia, scegli **Edit Role**, quindi rinominala e modifica le sue autorizzazioni. + +I ruoli predefiniti possono essere clonati anche se non possono essere modificati. Il clone registra da quale ruolo proviene. + +### Partire da zero + +1. Fai clic su **New Role**. +2. Assegnagli un **Name** (obbligatorio) e facoltativamente una **Description**. +3. Scegli le sue autorizzazioni nella griglia sottostante (vedi la sezione successiva). +4. Fai clic su **Save Role**. + +I nomi dei ruoli devono essere univoci e il controllo ignora la distinzione tra maiuscole e minuscole: se `Triage Lead` esiste già, `triage lead` viene rifiutato. + +## Scelta delle autorizzazioni + +![La griglia delle autorizzazioni nel modulo del ruolo](images/pro_role_permission_grid.png) + +Le autorizzazioni sono raggruppate in tre tabelle più una checklist. + +**Object Permissions** si applicano alle Organization e agli Asset a cui il ruolo è assegnato, e a tutto ciò che è annidato al loro interno. + +| Riga | View | Add | Edit | Delete | +| --- | --- | --- | --- | --- | +| Organization | ☑️ | ☑️ | ☑️ | ☑️ | +| Asset | ☑️ | ☑️ ¹ | ☑️ | ☑️ | +| Engagement | ☑️ | ☑️ | ☑️ | ☑️ | +| Test | ☑️ | ☑️ | ☑️ | ☑️ | +| Finding | ☑️ | ☑️ | ☑️ | ☑️ | +| Finding Group | ☑️ | ☑️ | ☑️ | ☑️ | +| Risk Acceptance | ☑️ | ☑️ | ☑️ | ☑️ | +| Location | ☑️ | ☑️ | ☑️ | ☑️ | +| Component | ☑️ | | | | +| Note | ² | ☑️ | ☑️ | ☑️ | +| Benchmark | ² | | ☑️ | ☑️ | +| Language | ☑️ | ☑️ | ☑️ | ☑️ | +| Technology | ☑️ | ☑️ | ☑️ | ☑️ | +| Asset API Scan Configuration | ☑️ | ☑️ | ☑️ | ☑️ | +| Asset Tracking Files | ☑️ | ☑️ | ☑️ | ☑️ | +| Group | ☑️ | | ☑️ | ☑️ | + +1. **Asset > Add** significa creare un nuovo Asset all'interno di un'Organization a cui il ruolo è assegnato. +2. La View per Note e Benchmark è ereditata: un ruolo che può vedere l'Engagement, il Test, il Finding o l'Asset padre può vedere le sue Note e i suoi Benchmark. Queste celle mostrano un'icona **?** invece di una casella di controllo. + +**Group & Member Permissions** controllano chi può gestire le appartenenze. Le colonne qui sono View, Manage, Add, Add Owner, Edit e Delete. + +| Riga | Azioni disponibili | +| --- | --- | +| Gruppo dell'Organization, Gruppo dell'Asset | View, Add, Add Owner, Edit, Delete | +| Membro dell'Organization, Membro dell'Asset, Membro del Gruppo | Manage, Add Owner, Delete | + +**Global Feature Permissions** condizionano funzionalità Pro a livello di istanza anziché singole Organization o Asset, quindi **hanno effetto solo quando il ruolo viene detenuto come Global Role**. Concederle su un ruolo usato solo come appartenenza a un Asset non ha alcun effetto. + +| Riga | Azioni disponibili | +| --- | --- | +| Report Template | View, Add, Edit, Delete | +| Generated Report | View, Add, Delete | +| Connector, Sensei, Asset Hierarchy, Version Manager, Tuner, Universal Parser, Rule, Integration | View, Edit | +| Mitigation Policy | Edit | +| Audit Log, Metering | View | + +**Additional Permissions** è una checklist di funzionalità che non rientrano in uno schema View/Add/Edit/Delete: + +* **Configure Asset Notifications**: scegli quali notifiche invia un singolo Asset e dove. +* **Import Scan Result**: importa e reimporta i risultati delle scansioni, creando e aggiornando i Riscontri. +* **Share Dashboard Layout**: pubblica un layout della dashboard per altri utenti. Solo Global Role. +* **Share Table Preference**: pubblica una vista tabellare salvata (colonne, filtri, ordinamento). Solo Global Role. +* **View Note History**: vedi chi ha modificato una nota e quando. + +### Come leggere la griglia + +![La vista di sola lettura delle autorizzazioni di un ruolo](images/pro_role_permissions_modal.png) + +| Cosa vedi | Cosa significa | +| --- | --- | +| Una casella di controllo vuota | L'autorizzazione esiste e non è concessa. Fai clic per concederla. | +| Una casella di controllo selezionata | Concessa. | +| Una cella vuota e ombreggiata | L'autorizzazione non esiste per quella riga e azione. Non selezionabile. | +| Un'icona **?** | La View è ereditata da un oggetto padre, quindi qui non c'è nulla da concedere. | +| Un ✔ verde (vista di sola lettura) | Concessa. | +| Una ✘ rossa (vista di sola lettura) | Non concessa. | + +In ogni riga, l'autorizzazione più a sinistra (**View**, o **Manage** nelle righe dei membri) condiziona il resto della riga. Devi concederla prima che le altre celle di quella riga diventino disponibili, perché un ruolo non può modificare o eliminare in modo significativo ciò che non può vedere. Rimuovere questa condizione azzera anche il resto della riga. + +## Modifica, clonazione ed eliminazione + +Il menu **⋮** di ogni riga offre **Edit Role**, **Clone Role**, **Delete Role** e **Role History**. + +I ruoli predefiniti offrono solo **Clone Role**. Non possono essere modificati o eliminati da nessuno, superuser inclusi. Questo mantiene una base di riferimento nota e rende gli aggiornamenti prevedibili. + +L'eliminazione di un ruolo ancora assegnato a qualcuno fallirà. Riassegna o rimuovi prima quelle assegnazioni, poi elimina il ruolo. Le assegnazioni che contano a questo scopo sono le appartenenze a Organization e Asset (sia utente che gruppo), i Global Role, le appartenenze a Group e il ruolo di gruppo predefinito in System Settings. + +L'API può eseguire la riassegnazione per te con una singola chiamata. Consulta [Gestire i ruoli tramite l'API](#managing-roles-through-the-api). + +## Assegnazione di un ruolo personalizzato + +I ruoli personalizzati compaiono in ogni menu a discesa dei ruoli, insieme a quelli predefiniti: + +| Dove | Come | +| --- | --- | +| **Global Role su un utente** | Il campo **Global Role** nel modulo dell'utente. Solo superuser. Consulta [Impostare le autorizzazioni di un Utente](../set_user_permissions/). | +| **Global Role su un gruppo** | Il campo **Global Role** nel modulo del gruppo. Consulta [Condividere le autorizzazioni: gruppi di utenti](../create_user_group/). | +| **Appartenenza a Organization o Asset** | La finestra di dialogo Permissions sull'Organization o sull'Asset, sia per gli utenti che per i gruppi. Consulta [Impostare le autorizzazioni in Pro](../pro_permissions_overhaul/). | +| **Ruolo di gruppo predefinito** | **Default group role** in System Settings, applicato ai nuovi utenti creati. Consulta [Gestire le autorizzazioni predefinite](../about_perms_and_roles/#manage-default-permissions). | +| **Ruolo all'interno di un gruppo** | Il menu a discesa dei ruoli nell'elenco dei membri di un gruppo. Questo menu a discesa offre solo i ruoli che concedono almeno un'autorizzazione Group, quindi un ruolo senza autorizzazioni Group non vi comparirà. | + +Vale la pena conoscere due vincoli: + +* **Il livello Owner è riservato.** Un ruolo personalizzato non può mai essere un ruolo di livello owner. Solo l'Owner predefinito lo è, quindi solo lui possiede il potere implicito di gestire altri Owner. +* **Concedere il ruolo Owner a qualcun altro richiede comunque l'autorizzazione Add Owner corrispondente**, che tu lo faccia su un'Organization, un Asset o un Group. + +## Cosa sblocca un Global Role personalizzato + +Alcune parti dell'interfaccia sono condizionate da un Global Role minimo anziché da una singola autorizzazione. Per far funzionare i ruoli personalizzati con queste condizioni, DefectDojo classifica un Global Role personalizzato rispetto ai livelli predefiniti: un ruolo personalizzato ottiene il livello più alto le cui autorizzazioni copre **completamente**. + +* Un ruolo personalizzato che copre tutto ciò che concede Maintainer viene trattato come Maintainer per quelle condizioni. +* Copri tutto ciò che concede Writer, e viene trattato come Writer. Lo stesso vale per Reader. +* Se non ne copre completamente nessuno, non ottiene alcun livello. Le sue singole autorizzazioni funzionano comunque esattamente come concesse; solo le restrizioni dell'interfaccia basate sul livello restano chiuse. +* **Owner non può mai essere ottenuto in questo modo.** La gestione dei ruoli, e tutto ciò che è condizionato dal Global Role Owner, resta riservata ai superuser e all'Owner predefinito. + +La copertura deve essere completa, il che a volte sorprende. Un ruolo clonato da Maintainer ottiene il livello Maintainer. Se ricostruisci a mano le autorizzazioni di Maintainer e ne ometti una, il ruolo finisce invece al livello Writer. Se a un Global Role personalizzato manca un'interfaccia che ti aspettavi, confrontalo con il livello predefinito nelle [tabelle delle autorizzazioni per azione](../user_permission_chart/). + +## Cronologia dei ruoli + +I ruoli personalizzati mantengono una traccia di audit. Apri **Role History** dal menu **⋮** di un ruolo per vedere quali autorizzazioni sono state concesse o revocate, da chi e quando, insieme alle modifiche su chi detiene il ruolo. + +Ci sono due cose che questa cronologia non mostra: le modifiche al nome e alla descrizione di un ruolo, e le autorizzazioni dei ruoli predefiniti (questi sono precaricati, non vengono mai modificati e quindi non generano mai cronologia). + +La cronologia dei ruoli è un'operazione di lettura, quindi è disponibile indipendentemente dal fatto che la funzionalità Custom Roles sia attiva o meno. + +## Gestire i ruoli tramite l'API + +I ruoli sono disponibili su `/api/v2/roles/`. Le letture sono aperte a qualsiasi utente autenticato, perché i client hanno bisogno dell'elenco dei ruoli per popolare i menu a discesa. Le scritture richiedono lo stato di superuser o il Global Role predefinito Owner, oltre al feature flag Custom Roles. + +| Operazione | Richiesta | +| --- | --- | +| Elenca i ruoli | `GET /api/v2/roles/` | +| Recupera un ruolo | `GET /api/v2/roles/{id}/` | +| Elenca tutte le autorizzazioni assegnabili | `GET /api/v2/roles/permissions_catalog/` | +| Crea un ruolo | `POST /api/v2/roles/` con `name`, `description` facoltativa, e un elenco `permissions` | +| Sostituisce le autorizzazioni di un ruolo | `PATCH /api/v2/roles/{id}/` con un elenco `permissions` | +| Clona un ruolo | `POST /api/v2/roles/{id}/clone/` con `name` e `description` facoltativi | +| Elimina un ruolo | `DELETE /api/v2/roles/{id}/` | +| Elimina un ruolo e sposta le sue assegnazioni | `DELETE /api/v2/roles/{id}/?reassign_to={other_role_id}` | +| Legge la cronologia di un ruolo | `GET /api/v2/roles/{id}/history/` | + +Note: + +* `permissions` **sostituisce** l'elenco delle concessioni del ruolo invece di aggiungersi ad esso. Invia l'intero set con cui vuoi che il ruolo finisca. +* `?reassign_to=` sposta ogni assegnazione del ruolo eliminato al ruolo che indichi, in un'unica transazione. È l'unico modo per riassegnare in blocco: l'interfaccia non lo offre. +* Tentare di modificare o eliminare un ruolo predefinito restituisce `403`. Modificare un valore di autorizzazione sconosciuto, riutilizzare un nome di ruolo esistente o eliminare un ruolo in uso senza `reassign_to` restituisce `400` con una spiegazione. +* `is_owner` non può essere impostato tramite l'API. Inviarlo viene accettato ma ignorato. + +## Cose da sapere + +* **Più ruoli sullo stesso oggetto concedono l'unione delle rispettive autorizzazioni.** Se un utente detiene un ruolo direttamente su un Asset e ne eredita un altro tramite un gruppo, ottiene tutto ciò che entrambi i ruoli concedono. I ruoli aggiungono soltanto autorizzazioni, non le rimuovono mai. +* **Le modifiche alle autorizzazioni vengono recepite al caricamento successivo della pagina**, non istantaneamente nella vista corrente. I job in background possono impiegare fino a 30 secondi, e i dati di autorizzazione in cache fino a 5 minuti, per riflettere una modifica. +* **I menu a discesa dei ruoli elencano fino a 250 ruoli.** Oltre questo limite, alcuni ruoli non compariranno nei menu a discesa, anche se continuano a funzionare. +* **Maintainer e Owner possono aggiungere Organization, ma la griglia non lo mostra.** Per questi due ruoli, quella concessione è memorizzata come concessione a livello globale, e la griglia legge solo le concessioni a livello di oggetto, quindi la loro cella **Organization > Add** risulta come non concessa. Clonare uno dei due ruoli preserva la concessione. +* **La terminologia segue la tua istanza.** Questi documenti usano Organization e Asset, le etichette predefinite. Se nella tua istanza la rietichettatura Organization / Asset è disattivata, le stesse righe riportano invece Product Type e Product. +* **La pagina Roles è di sola lettura per chiunque altro.** Un utente che accede direttamente a `/settings/roles` può vedere i ruoli e le relative autorizzazioni ma non può modificare nulla. I dati sulle autorizzazioni non sono sensibili, e il server applica il vero limite a ogni scrittura. diff --git a/docs/content/admin/user_management/PRO__custom_rbac_roles.pt-br.md b/docs/content/admin/user_management/PRO__custom_rbac_roles.pt-br.md new file mode 100644 index 0000000000..ffd1c333fd --- /dev/null +++ b/docs/content/admin/user_management/PRO__custom_rbac_roles.pt-br.md @@ -0,0 +1,212 @@ +--- +title: Funções RBAC Personalizadas +description: Crie suas próprias funções escolhendo permissões individuais, usando + as cinco funções integradas como pontos de partida clonáveis +weight: 5 +audience: pro +--- + +> **Recurso do DefectDojo Pro.** O sistema de RBAC Members / Groups / Global Roles descrito nesta página faz parte do DefectDojo Pro. O DefectDojo de código aberto usa o modelo [Authorized Users](../os__authorized_users/). Consulte essa página para o controle de acesso no código aberto, e as [notas de atualização da 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) caso você esteja migrando entre edições. + +O DefectDojo Pro vem com cinco funções: **Reader**, **Writer**, **Maintainer**, **Owner** e **API Importer**. Se nenhuma delas for adequada, agora você pode criar sua própria função escolhendo exatamente quais permissões ela concede. + +Uma função personalizada funciona em qualquer lugar onde uma função integrada funciona: como Função Global, como a função de um Grupo, como a função padrão do grupo, e como função de membro em uma Organização ou Asset individual. + +As cinco funções integradas se tornam **predefinições bloqueadas e clonáveis**. Suas permissões não mudam (consulte os [gráficos de permissões de ação](../user_permission_chart/) para saber o que cada uma concede), elas não podem ser editadas nem excluídas, e cloná-las é a forma recomendada de começar uma nova função. + +## Antes de começar + +O gerenciamento de funções personalizadas vem desativado por padrão. Um **superusuário** o ativa em **Settings > Feature Flags**, habilitando **Custom Roles**. Consulte [Feature Flags](/admin/feature_flags/pro__feature_flags/) para saber como essa página funciona. + +Enquanto o recurso estiver desativado, a página Roles ainda pode ser lida: você pode visualizar as funções integradas e suas permissões, mas não pode criar, editar, clonar ou excluir nada. + +Gerenciar funções exige status de **superusuário** ou a Função Global integrada **Owner**. Isso é intencional e não pode ser delegado a uma função personalizada: consulte [O que uma Função Global personalizada desbloqueia](#what-a-custom-global-role-unlocks). + +## Abrindo a página Roles + +Vá até **👤 Users > Roles** na barra lateral esquerda. O item do menu fica visível para superusuários e para quem possui a Função Global integrada Owner. + +![The Roles page listing built-in and custom roles](images/pro_roles_list.png) + +A tabela lista todas as funções da sua instância: + +| Coluna | O que mostra | +| --- | --- | +| **ID** | O id numérico da função. Útil ao filtrar a tabela de Users ou ao chamar a API. | +| **Name** | O nome da função. | +| **Description** | Sua própria anotação sobre a finalidade da função. Opcional, e vazia a menos que alguém a preencha. As funções integradas vêm sem uma. | +| **Permissions** | Uma contagem de permissões concedidas. Clique para abrir uma visualização somente leitura da grade completa. | +| **Users** | Quantos usuários possuem essa função como sua Função Global. Clique para vê-los na tabela de Users. | +| **Type** | **Built-in** para as cinco predefinições, **Custom** para funções criadas por você. | + +Todas as colunas podem ser ordenadas e filtradas, e a busca por palavra-chave corresponde ao nome e à descrição. + +## Criando uma função + +### Clonar uma função integrada (recomendado) + +Clonar parte de um conjunto de permissões já validado, em vez de uma grade vazia, o que torna muito mais difícil esquecer acidentalmente uma permissão de que a função precisa. + +1. Encontre a função mais próxima do que você deseja. +2. Abra seu menu **⋮** e escolha **Clone Role**. +3. Uma cópia é criada imediatamente, chamada ` (copy)`, com as mesmas permissões e descrição da função de origem. +4. Abra o menu **⋮** da cópia, escolha **Edit Role**, depois renomeie-a e ajuste suas permissões. + +Funções integradas podem ser clonadas mesmo não podendo ser editadas. O clone registra de qual função ele se originou. + +### Começar do zero + +1. Clique em **New Role**. +2. Dê a ela um **Name** (obrigatório) e, opcionalmente, uma **Description**. +3. Escolha suas permissões na grade abaixo (veja a próxima seção). +4. Clique em **Save Role**. + +Os nomes das funções devem ser únicos, e a verificação ignora maiúsculas/minúsculas: se `Triage Lead` já existir, `triage lead` será rejeitado. + +## Escolhendo permissões + +![The permission grid in the role form](images/pro_role_permission_grid.png) + +As permissões são agrupadas em três tabelas mais uma lista de verificação. + +**Object Permissions** se aplicam às Organizations e Assets aos quais a função é atribuída, e a tudo o que está aninhado sob eles. + +| Linha | View | Add | Edit | Delete | +| --- | --- | --- | --- | --- | +| Organization | ☑️ | ☑️ | ☑️ | ☑️ | +| Asset | ☑️ | ☑️ ¹ | ☑️ | ☑️ | +| Engagement | ☑️ | ☑️ | ☑️ | ☑️ | +| Test | ☑️ | ☑️ | ☑️ | ☑️ | +| Finding | ☑️ | ☑️ | ☑️ | ☑️ | +| Finding Group | ☑️ | ☑️ | ☑️ | ☑️ | +| Risk Acceptance | ☑️ | ☑️ | ☑️ | ☑️ | +| Location | ☑️ | ☑️ | ☑️ | ☑️ | +| Component | ☑️ | | | | +| Note | ² | ☑️ | ☑️ | ☑️ | +| Benchmark | ² | | ☑️ | ☑️ | +| Language | ☑️ | ☑️ | ☑️ | ☑️ | +| Technology | ☑️ | ☑️ | ☑️ | ☑️ | +| Asset API Scan Configuration | ☑️ | ☑️ | ☑️ | ☑️ | +| Asset Tracking Files | ☑️ | ☑️ | ☑️ | ☑️ | +| Group | ☑️ | | ☑️ | ☑️ | + +1. **Asset > Add** significa criar um novo Asset dentro de uma Organization à qual a função está atribuída. +2. A visualização (View) de Notes e Benchmarks é herdada: uma função que pode ver o Engagement, Test, Finding ou Asset pai pode ver suas Notes e Benchmarks. Essas células mostram um ícone **?** em vez de uma caixa de seleção. + +**Group & Member Permissions** controlam quem pode gerenciar a associação. As colunas aqui são View, Manage, Add, Add Owner, Edit e Delete. + +| Linha | Ações disponíveis | +| --- | --- | +| Organization Group, Asset Group | View, Add, Add Owner, Edit, Delete | +| Organization Member, Asset Member, Group Member | Manage, Add Owner, Delete | + +**Global Feature Permissions** controlam recursos do Pro em toda a instância, e não Organizations ou Assets individuais, portanto **só têm efeito quando a função é mantida como uma Função Global**. Concedê-las em uma função usada apenas como associação de Asset não tem efeito. + +| Linha | Ações disponíveis | +| --- | --- | +| Report Template | View, Add, Edit, Delete | +| Generated Report | View, Add, Delete | +| Connector, Sensei, Asset Hierarchy, Version Manager, Tuner, Universal Parser, Rule, Integration | View, Edit | +| Mitigation Policy | Edit | +| Audit Log, Metering | View | + +**Additional Permissions** é uma lista de verificação de capacidades que não se encaixam no formato View/Add/Edit/Delete: + +* **Configure Asset Notifications**: escolher quais notificações um único Asset envia, e para onde. +* **Import Scan Result**: importar e reimportar resultados de scan, criando e atualizando achados. +* **Share Dashboard Layout**: publicar um layout de painel para outros usuários. Somente Função Global. +* **Share Table Preference**: publicar uma visualização de tabela salva (colunas, filtros, ordem de classificação). Somente Função Global. +* **View Note History**: ver quem alterou uma nota e quando. + +### Como ler a grade + +![The read-only view of a role's permissions](images/pro_role_permissions_modal.png) + +| O que você vê | O que significa | +| --- | --- | +| An empty checkbox | A permissão existe e não está concedida. Clique para concedê-la. | +| A checked checkbox | Concedida. | +| A shaded, empty cell | A permissão não existe para aquela linha e ação. Não é selecionável. | +| A **?** icon | A visualização (View) é herdada de um objeto pai, portanto não há nada para conceder aqui. | +| A green ✔ (read-only view) | Concedida. | +| A red ✘ (read-only view) | Não concedida. | + +Em cada linha, a permissão mais à esquerda (**View**, ou **Manage** nas linhas de membro) controla o restante da linha. Você precisa concedê-la antes que as outras células daquela linha fiquem disponíveis, porque uma função não pode, de forma significativa, editar ou excluir o que não pode ver. Desmarcar essa permissão limpa o restante da linha junto com ela. + +## Editando, clonando e excluindo + +O menu **⋮** de cada linha oferece **Edit Role**, **Clone Role**, **Delete Role** e **Role History**. + +Funções integradas só oferecem **Clone Role**. Elas não podem ser editadas nem excluídas, por ninguém, incluindo superusuários. Isso mantém uma base conhecida estável e torna as atualizações previsíveis. + +Excluir uma função que ainda está atribuída a alguém falhará. Reatribua ou remova essas atribuições primeiro, depois exclua a função. As atribuições que contam para esse fim são associações de Organization e Asset (tanto de usuário quanto de grupo), Funções Globais, associações de Grupo, e a função de grupo padrão em System Settings. + +A API pode fazer essa reatribuição para você em uma única chamada. Consulte [Gerenciando funções pela API](#managing-roles-through-the-api). + +## Atribuindo uma função personalizada + +Funções personalizadas aparecem em todos os menus suspensos de função, junto com as integradas: + +| Onde | Como | +| --- | --- | +| **Global Role em um usuário** | O campo **Global Role** no formulário do usuário. Somente superusuários. Consulte [Definir as permissões de um Usuário](../set_user_permissions/). | +| **Global Role em um grupo** | O campo **Global Role** no formulário do grupo. Consulte [Compartilhar permissões: Grupos de Usuários](../create_user_group/). | +| **Associação de Organization ou Asset** | A caixa de diálogo Permissions na Organization ou Asset, tanto para usuários quanto para grupos. Consulte [Definir permissões no Pro](../pro_permissions_overhaul/). | +| **Função de grupo padrão** | **Default group role** em System Settings, aplicada a usuários recém-criados. Consulte [Gerenciar permissões padrão](../about_perms_and_roles/#manage-default-permissions). | +| **Função dentro de um grupo** | O menu suspenso de função na lista de membros de um grupo. Esse menu suspenso só oferece funções que concedem ao menos uma permissão de Group, portanto uma função sem permissões de Group não aparecerá ali. | + +Duas restrições valem a pena conhecer: + +* **O nível Owner é reservado.** Uma função personalizada nunca pode ser uma função de nível owner. Somente a Owner integrada é, portanto só ela carrega o poder implícito de gerenciar outros Owners. +* **Conceder a função Owner a outra pessoa ainda exige a permissão Add Owner correspondente**, seja em uma Organization, um Asset ou um Grupo. + +## O que uma Função Global personalizada desbloqueia + +Partes da interface são controladas por uma Função Global mínima, em vez de por uma permissão individual. Para que funções personalizadas funcionem com esses controles, o DefectDojo classifica uma Função Global personalizada em relação aos níveis integrados: uma função personalizada alcança o nível mais alto cujas permissões ela cobre **completamente**. + +* Uma função personalizada que cobre tudo o que Maintainer concede é tratada como Maintainer para esses controles. +* Cubra tudo o que Writer concede, e ela é tratada como Writer. O mesmo vale para Reader. +* Não cubra nenhum deles completamente, e ela não alcança nenhum nível. Suas permissões individuais continuam funcionando exatamente como concedidas; apenas os controles de interface baseados em nível permanecem fechados. +* **Owner nunca pode ser alcançado dessa forma.** O gerenciamento de funções, e tudo o mais controlado pela Função Global Owner, permanece restrito a superusuários e à Owner integrada. + +A cobertura precisa ser completa, o que às vezes surpreende as pessoas. Uma função clonada de Maintainer alcança o nível Maintainer. Reconstrua as permissões de Maintainer manualmente, esqueça uma, e a função cai para o nível Writer. Se uma Função Global personalizada estiver sem uma parte da interface que você esperava, compare-a com o nível integrado nos [gráficos de permissões de ação](../user_permission_chart/). + +## Histórico de funções + +Funções personalizadas mantêm uma trilha de auditoria. Abra **Role History** no menu **⋮** de uma função para ver quais permissões foram concedidas ou revogadas, por quem, e quando, junto com alterações em quem possui a função. + +Duas coisas que esse histórico não mostra: alterações no próprio nome e descrição de uma função, e as permissões das funções integradas (essas são pré-carregadas, nunca editadas, e portanto nunca geram histórico). + +O histórico de funções é uma leitura, portanto está disponível independentemente de o recurso Custom Roles estar ativado. + +## Gerenciando funções pela API + +As funções estão disponíveis em `/api/v2/roles/`. As leituras são abertas a qualquer usuário autenticado, pois os clientes precisam da lista de funções para preencher menus suspensos. As gravações exigem status de superusuário ou a Função Global Owner integrada, além do feature flag Custom Roles. + +| Operação | Requisição | +| --- | --- | +| Listar funções | `GET /api/v2/roles/` | +| Obter uma função | `GET /api/v2/roles/{id}/` | +| Listar todas as permissões concedíveis | `GET /api/v2/roles/permissions_catalog/` | +| Criar uma função | `POST /api/v2/roles/` com `name`, `description` opcional, e uma lista de `permissions` | +| Substituir as permissões de uma função | `PATCH /api/v2/roles/{id}/` com uma lista de `permissions` | +| Clonar uma função | `POST /api/v2/roles/{id}/clone/` com `name` e `description` opcionais | +| Excluir uma função | `DELETE /api/v2/roles/{id}/` | +| Excluir uma função e mover suas atribuições | `DELETE /api/v2/roles/{id}/?reassign_to={other_role_id}` | +| Ler o histórico de uma função | `GET /api/v2/roles/{id}/history/` | + +Observações: + +* `permissions` **substitui** a lista de permissões concedidas da função, em vez de adicionar a ela. Envie o conjunto completo que você quer que a função tenha ao final. +* `?reassign_to=` move todas as atribuições da função excluída para a função que você indicar, em uma única transação. Essa é a única forma de reatribuir em massa: a interface não oferece isso. +* Tentar editar ou excluir uma função integrada retorna `403`. Editar um valor de permissão desconhecido, reutilizar um nome de função existente, ou excluir uma função em uso sem `reassign_to` retorna `400` com uma explicação. +* `is_owner` não pode ser definido pela API. Enviá-lo é aceito e ignorado. + +## Coisas a saber + +* **Múltiplas funções no mesmo objeto concedem a união de suas permissões.** Se um usuário possui uma função diretamente em um Asset e herda outra por meio de um grupo, ele obtém tudo o que qualquer uma das funções conceder. As funções só adicionam permissões, nunca as removem. +* **Alterações de permissão são aplicadas no próximo carregamento de página**, não instantaneamente na visualização atual. Jobs em segundo plano podem levar até 30 segundos, e dados de permissão em cache até 5 minutos, para refletir uma edição. +* **Os menus suspensos de função listam até 250 funções.** Além disso, algumas funções não aparecerão nos menus suspensos, embora continuem funcionando. +* **Maintainer e Owner podem adicionar Organizations, mas a grade não mostra isso.** Para essas duas funções, essa concessão é armazenada como uma concessão de escopo global, e a grade só lê concessões de escopo de objeto, portanto a célula **Organization > Add** delas aparece como não concedida. Clonar qualquer uma das duas preserva a concessão. +* **A terminologia segue sua instância.** Esta documentação usa Organization e Asset, os rótulos padrão. Se sua instância desativou a renomeação de Organization / Asset, as mesmas linhas mostram Product Type e Product em vez disso. +* **A página Roles é somente leitura para todos os demais.** Um usuário que acessar `/settings/roles` diretamente pode ver as funções e suas permissões, mas não pode alterar nada. Os dados de permissão não são sensíveis, e o servidor aplica o limite real em cada gravação. diff --git a/docs/content/admin/user_management/PRO__custom_rbac_roles.zh-hans.md b/docs/content/admin/user_management/PRO__custom_rbac_roles.zh-hans.md new file mode 100644 index 0000000000..6c007a8f48 --- /dev/null +++ b/docs/content/admin/user_management/PRO__custom_rbac_roles.zh-hans.md @@ -0,0 +1,211 @@ +--- +title: 自定义 RBAC 角色 +description: 通过选择单项权限构建您自己的角色,并将五种内置角色作为可克隆的起点 +weight: 5 +audience: pro +--- + +> **DefectDojo Pro 功能。** 本页所述的成员 / 组 / 全局角色 RBAC 系统是 DefectDojo Pro 的一部分。开源版 DefectDojo 使用[授权用户](../os__authorized_users/)模型。有关开源版访问控制,请参见该页面;如果您正在版本之间迁移,请参见 [3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。 + +DefectDojo Pro 内置了五种角色:**只读者(Reader)**、**编写者(Writer)**、**维护者(Maintainer)**、**所有者(Owner)** 和 **API 导入者(API Importer)**。如果这些角色都不适合您的需求,您现在可以通过精确选择要授予的权限来构建自己的角色。 + +自定义角色可以在内置角色能够使用的任何地方使用:作为全局角色、作为组的角色、作为默认组角色,以及作为单个组织或资产上的成员角色。 + +这五种内置角色成为**锁定的、可克隆的预设**。它们的权限保持不变(有关每种角色授予的权限,请参见[操作权限图表](../user_permission_chart/)),它们无法被编辑或删除,克隆其中一种角色是创建新角色的推荐方式。 + +## 开始之前 + +自定义角色管理默认处于关闭状态。**超级用户**可以通过启用**设置(Settings) > 功能开关(Feature Flags)** 中的**自定义角色(Custom Roles)** 来开启此功能。有关该页面的工作方式,请参见[功能开关](/admin/feature_flags/pro__feature_flags/)。 + +在该功能关闭时,角色页面仍然可读:您可以查看内置角色及其权限,但无法创建、编辑、克隆或删除任何内容。 + +管理角色需要**超级用户**状态或内置的**所有者(Owner)** 全局角色。这是刻意设计的,不能委派给自定义角色:请参见[自定义全局角色可解锁的功能](#what-a-custom-global-role-unlocks)。 + +## 打开角色页面 + +前往左侧边栏中的 **👤 用户(Users) > 角色(Roles)**。该菜单项对超级用户和拥有内置所有者全局角色的用户可见。 + +![列出内置角色和自定义角色的角色页面](images/pro_roles_list.png) + +该表列出了您实例中的每个角色: + +| 列 | 显示内容 | +| --- | --- | +| **ID** | 角色的数字 ID。在筛选用户表或调用 API 时很有用。 | +| **名称(Name)** | 角色名称。 | +| **描述(Description)** | 您对该角色用途的说明。此项为可选,除非有人填写,否则为空。内置角色不附带此说明。 | +| **权限(Permissions)** | 已授予权限的数量。点击可打开完整权限网格的只读视图。 | +| **用户(Users)** | 有多少用户将此角色作为其全局角色持有。点击可在用户表中查看这些用户。 | +| **类型(Type)** | 五种预设角色为**内置(Built-in)**,您创建的角色为**自定义(Custom)**。 | + +每一列都可排序和筛选,关键字搜索会匹配名称和描述。 + +## 创建角色 + +### 克隆内置角色(推荐) + +克隆操作让您从一套已知可用的权限集开始,而不是从空白网格开始,这样就更不容易意外遗漏角色所需的权限。 + +1. 找到与您需求最接近的角色。 +2. 打开其 **⋮** 菜单,选择**克隆角色(Clone Role)**。 +3. 系统会立即创建一个副本,命名为 ` (copy)`,其权限和描述与来源角色相同。 +4. 打开该副本的 **⋮** 菜单,选择**编辑角色(Edit Role)**,然后重命名并调整其权限。 + +内置角色虽然无法编辑,但可以被克隆。克隆出的角色会记录其来源角色。 + +### 从零开始创建 + +1. 点击**新建角色(New Role)**。 +2. 为其填写**名称(Name)**(必填)和可选的**描述(Description)**。 +3. 在下方的网格中选择其权限(参见下一节)。 +4. 点击**保存角色(Save Role)**。 + +角色名称必须唯一,且检查时不区分大小写:如果已存在 `Triage Lead`,则 `triage lead` 会被拒绝。 + +## 选择权限 + +![角色表单中的权限网格](images/pro_role_permission_grid.png) + +权限分为三张表加一份清单。 + +**对象权限(Object Permissions)** 适用于角色所分配到的组织和资产,以及它们下属的所有内容。 + +| 行 | 查看 | 添加 | 编辑 | 删除 | +| --- | --- | --- | --- | --- | +| 组织 | ☑️ | ☑️ | ☑️ | ☑️ | +| 资产 | ☑️ | ☑️ ¹ | ☑️ | ☑️ | +| 测试活动 | ☑️ | ☑️ | ☑️ | ☑️ | +| 测试 | ☑️ | ☑️ | ☑️ | ☑️ | +| 发现项 | ☑️ | ☑️ | ☑️ | ☑️ | +| 发现项组 | ☑️ | ☑️ | ☑️ | ☑️ | +| 风险接受 | ☑️ | ☑️ | ☑️ | ☑️ | +| 位置 | ☑️ | ☑️ | ☑️ | ☑️ | +| 组件 | ☑️ | | | | +| 备注 | ² | ☑️ | ☑️ | ☑️ | +| 基准 | ² | | ☑️ | ☑️ | +| 语言 | ☑️ | ☑️ | ☑️ | ☑️ | +| 技术 | ☑️ | ☑️ | ☑️ | ☑️ | +| 资产 API 扫描配置 | ☑️ | ☑️ | ☑️ | ☑️ | +| 资产跟踪文件 | ☑️ | ☑️ | ☑️ | ☑️ | +| 组 | ☑️ | | ☑️ | ☑️ | + +1. **资产(Asset) > 添加(Add)** 是指在角色所分配到的组织内创建新资产。 +2. 备注和基准的查看权限是继承而来的:能够查看父级测试活动、测试、发现项或资产的角色,就能查看其备注和基准。这些单元格显示的是 **?** 图标,而不是复选框。 + +**组与成员权限(Group & Member Permissions)** 控制谁可以管理成员资格。此处的列为查看、管理、添加、添加所有者和编辑、删除。 + +| 行 | 可用操作 | +| --- | --- | +| 组织组、资产组 | 查看、添加、添加所有者、编辑、删除 | +| 组织成员、资产成员、组成员 | 管理、添加所有者、删除 | + +**全局功能权限(Global Feature Permissions)** 控制的是实例范围内的 Pro 功能,而非单个组织或资产,因此**只有当角色作为全局角色持有时才会生效**。在仅用作资产成员资格的角色上授予这些权限不会产生任何效果。 + +| 行 | 可用操作 | +| --- | --- | +| 报告模板 | 查看、添加、编辑、删除 | +| 已生成报告 | 查看、添加、删除 | +| 连接器、Sensei、资产层级结构、版本管理器、调优器、通用解析器、规则、集成 | 查看、编辑 | +| 缓解策略 | 编辑 | +| 审计日志、计量 | 查看 | + +**附加权限(Additional Permissions)** 是一份不符合查看/添加/编辑/删除模式的功能清单: + +* **配置资产通知**:选择单个资产发送哪些通知,以及发送到何处。 +* **导入扫描结果**:导入和重新导入扫描结果,创建和更新发现项。 +* **共享仪表板布局**:向其他用户发布仪表板布局。仅限全局角色。 +* **共享表格偏好设置**:发布已保存的表格视图(列、筛选器、排序顺序)。仅限全局角色。 +* **查看备注历史记录**:查看谁在何时更改了备注。 + +### 如何读懂网格 + +![角色权限的只读视图](images/pro_role_permissions_modal.png) + +| 您看到的内容 | 含义 | +| --- | --- | +| 空复选框 | 该权限存在但未被授予。点击即可授予。 | +| 已勾选的复选框 | 已授予。 | +| 阴影处理的空单元格 | 该行和操作不存在此权限,不可选择。 | +| **?** 图标 | 查看权限继承自父对象,因此此处无需授予。 | +| 绿色 ✔(只读视图) | 已授予。 | +| 红色 ✘(只读视图) | 未授予。 | + +在每一行中,最左侧的权限(**查看**,或成员行中的**管理**)是该行其余权限的前提条件。您必须先授予该权限,该行中的其他单元格才会变为可用,因为角色无法对看不到的内容进行有意义的编辑或删除。清除该前提权限会同时清除该行的其余权限。 + +## 编辑、克隆和删除 + +每一行的 **⋮** 菜单都提供**编辑角色(Edit Role)**、**克隆角色(Clone Role)**、**删除角色(Delete Role)** 和**角色历史记录(Role History)**。 + +内置角色仅提供**克隆角色**选项。任何人(包括超级用户)都无法编辑或删除它们。这样可以保持一个已知的基准不变,并使升级过程可预测。 + +删除仍被分配给任何人的角色将会失败。请先重新分配或移除这些分配,然后再删除该角色。计入此项的分配包括组织和资产成员资格(用户和组均计入)、全局角色、组成员资格,以及系统设置中的默认组角色。 + +API 可以通过单次调用为您完成重新分配。请参见[通过 API 管理角色](#managing-roles-through-the-api)。 + +## 分配自定义角色 + +自定义角色会与内置角色一起出现在每个角色下拉列表中: + +| 位置 | 方式 | +| --- | --- | +| **用户上的全局角色** | 用户表单上的**全局角色**字段。仅限超级用户。请参见[设置用户的权限](../set_user_permissions/)。 | +| **组上的全局角色** | 组表单上的**全局角色**字段。请参见[共享权限:用户组](../create_user_group/)。 | +| **组织或资产成员资格** | 组织或资产上的权限对话框,适用于用户和组。请参见 [Pro 中的权限设置](../pro_permissions_overhaul/)。 | +| **默认组角色** | 系统设置中的**默认组角色**,应用于新创建的用户。请参见[管理默认权限](../about_perms_and_roles/#manage-default-permissions)。 | +| **组内角色** | 组成员列表中的角色下拉列表。此下拉列表仅提供至少授予一项组权限的角色,因此没有任何组权限的角色不会出现在其中。 | + +有两个限制值得了解: + +* **所有者级别被保留。** 自定义角色永远不能成为所有者级别的角色。只有内置的所有者角色才是,因此只有它拥有管理其他所有者的隐含权力。 +* **将所有者角色授予他人仍需要相应的添加所有者权限**,无论是在组织、资产还是组上进行操作。 + +## 自定义全局角色可解锁的功能 + +部分界面功能是基于最低全局角色而非单项权限来控制访问的。为了让自定义角色能够与这些限制协同工作,DefectDojo 会将自定义全局角色与内置层级进行对比排名:自定义角色会获得其权限**完全**覆盖的最高层级。 + +* 完全覆盖维护者所授予的全部权限的自定义角色,在这些限制中会被视为维护者。 +* 完全覆盖编写者所授予的权限,则会被视为编写者。只读者同理。 +* 若都无法完全覆盖,则不会获得任何层级。其各项权限仍会按所授予的方式正常工作;只是基于层级的界面限制仍会保持关闭状态。 +* **所有者层级永远无法通过此方式获得。** 角色管理以及其他所有基于所有者全局角色进行限制的功能,仍仅限超级用户和内置的所有者角色使用。 + +覆盖必须是完整的,这有时会让人感到意外。从维护者克隆而来的角色会获得维护者层级。若手动重建维护者的权限时遗漏了一项,该角色则会落到编写者层级。如果自定义全局角色缺少您预期中的界面功能,请将其与[操作权限图表](../user_permission_chart/)中的内置层级进行对比。 + +## 角色历史记录 + +自定义角色会保留审计跟踪。从角色的 **⋮** 菜单打开**角色历史记录(Role History)**,即可查看哪些权限被授予或撤销、由谁操作、何时操作,以及持有该角色的用户发生的变更。 + +该历史记录不会显示以下两项内容:角色自身名称和描述的变更,以及内置角色的权限(这些权限是预置的,从不被编辑,因此不会产生历史记录)。 + +角色历史记录属于只读内容,因此无论自定义角色功能是否开启,都可以查看。 + +## 通过 API 管理角色 + +角色可通过 `/api/v2/roles/` 访问。读取操作对任何已通过身份验证的用户开放,因为客户端需要角色列表来填充下拉菜单。写入操作需要超级用户状态或内置的所有者全局角色,并且需要启用自定义角色功能开关。 + +| 操作 | 请求 | +| --- | --- | +| 列出角色 | `GET /api/v2/roles/` | +| 获取单个角色 | `GET /api/v2/roles/{id}/` | +| 列出所有可授予的权限 | `GET /api/v2/roles/permissions_catalog/` | +| 创建角色 | `POST /api/v2/roles/`,带 `name`、可选的 `description` 和 `permissions` 列表 | +| 替换角色的权限 | `PATCH /api/v2/roles/{id}/`,带 `permissions` 列表 | +| 克隆角色 | `POST /api/v2/roles/{id}/clone/`,带可选的 `name` 和 `description` | +| 删除角色 | `DELETE /api/v2/roles/{id}/` | +| 删除角色并转移其分配 | `DELETE /api/v2/roles/{id}/?reassign_to={other_role_id}` | +| 读取角色的历史记录 | `GET /api/v2/roles/{id}/history/` | + +说明: + +* `permissions` 会**替换**角色的授权列表,而不是在其基础上追加。请发送您希望该角色最终拥有的完整权限集合。 +* `?reassign_to=` 会在一次事务中,将被删除角色的所有分配转移到您指定的角色。这是批量重新分配的唯一方式:界面未提供此功能。 +* 尝试编辑或删除内置角色会返回 `403`。编辑未知的权限值、重复使用已存在的角色名称,或在未指定 `reassign_to` 的情况下删除正在使用中的角色,都会返回 `400` 并附带说明。 +* `is_owner` 无法通过 API 设置。提交该字段会被接受但会被忽略。 + +## 须知事项 + +* **同一对象上的多个角色会授予其权限的并集。** 如果用户直接在某资产上持有一个角色,又通过组继承了另一个角色,那么该用户会获得两个角色所授予的全部权限。角色只会增加权限,永远不会移除权限。 +* **权限变更会在下次页面加载时生效**,而不会在当前视图中立即生效。后台作业最多可能需要 30 秒,缓存的权限数据最多可能需要 5 分钟,才能反映出某项编辑。 +* **角色下拉列表最多显示 250 个角色。** 超过此数量后,部分角色将不会出现在下拉列表中,但它们仍会继续正常工作。 +* **维护者和所有者可以添加组织,但网格中不会显示此项。** 对于这两种角色,该授权以全局范围的授权形式存储,而网格只读取对象范围的授权,因此其**组织 > 添加**单元格显示为未授予。克隆这两种角色中的任意一种都会保留该授权。 +* **术语遵循您实例的设置。** 本文档使用默认标签“组织”和“资产”。如果您的实例关闭了组织/资产的重新标记功能,同样的行会显示为“产品类型”和“产品”。 +* **角色页面对其他所有人都是只读的。** 直接访问 `/settings/roles` 的用户可以查看角色及其权限,但无法更改任何内容。权限数据并不敏感,服务器会在每次写入时强制执行真正的边界检查。 diff --git a/docs/content/admin/user_management/PRO__mfa.it.md b/docs/content/admin/user_management/PRO__mfa.it.md new file mode 100644 index 0000000000..4267fe5a45 --- /dev/null +++ b/docs/content/admin/user_management/PRO__mfa.it.md @@ -0,0 +1,85 @@ +--- +title: Autenticazione a più fattori (MFA) +description: Configura l'MFA sul tuo account, rendila obbligatoria in tutta l'istanza + e recupera un utente che ha perso il proprio dispositivo +audience: pro +weight: 3 +--- + +L'autenticazione a più fattori aggiunge un secondo passaggio all'accesso: dopo la password, DefectDojo richiede un codice a sei cifre generato da un'app di autenticazione. Consigliamo vivamente di richiederla per tutti gli utenti sulle istanze non protette da SSO. + +L'MFA di DefectDojo Pro utilizza un'**app di autenticazione TOTP**: Google Authenticator, 1Password, Authy o qualsiasi altra app in grado di scansionare un codice QR standard. Non è prevista alcuna opzione via email o SMS. + +## Configurare l'MFA sul tuo account + +1. Vai su **Connect \> Authorization \> MFA Settings**. +2. In **Personal Multi-Factor Authentication Settings**, fai clic su **Set Up MFA**. +3. Scansiona il codice QR con la tua app di autenticazione. Se non riesci a scansionarlo, la schermata di configurazione mostra anche la chiave in formato testo, che puoi digitare manualmente nella tua app. +4. Inserisci il codice a sei cifre mostrato dalla tua app e fai clic su **Verify & enable**. +5. DefectDojo mostra i tuoi **codici di recupero**. Salvali in un posto sicuro prima di continuare, vedi sotto. Fai clic su **Copy codes**, conservali, quindi fai clic su **I've saved them. Continue**. + +Da quel momento l'MFA è attiva. Al prossimo accesso, DefectDojo richiederà un codice dopo la password. + +### Codici di recupero + +Quando abiliti l'MFA ti vengono forniti **dieci codici di recupero monouso**. Ognuno può essere usato una sola volta, al posto di un codice dell'app di autenticazione, e viene consumato all'uso. + +Vengono mostrati **una sola volta**, nella schermata finale della configurazione. In seguito, la pagina MFA Settings mostra solo quanti te ne restano, non i codici stessi. + +Se perdi i codici di recupero, o ne vuoi un nuovo set dopo averne usati diversi, fai clic su **Regenerate Recovery Codes** nella pagina MFA Settings. Questo **sostituisce tutti i codici esistenti**: quelli salvati in precedenza smettono di funzionare immediatamente, quindi salva subito il nuovo set. + +I codici di recupero sono ciò che ti permette di rientrare quando perdi il telefono, quindi conservali in un posto separato dal dispositivo su cui gira la tua app di autenticazione. + +### Disattivare l'MFA + +**Disable MFA** nella pagina MFA Settings la disattiva per il tuo account. Devi solo essere connesso: non ti verrà chiesto un codice per confermare. + +Se il tuo amministratore ha reso l'MFA obbligatoria, ti verrà chiesto di configurarla di nuovo al prossimo accesso. + +## Accedere con l'MFA + +Dopo aver inserito nome utente e password, DefectDojo richiede il tuo codice a sei cifre. Se non hai la tua app di autenticazione, inserisci invece uno dei tuoi **codici di recupero** nello stesso campo: quel codice verrà quindi consumato. + +## Richiedere l'MFA per tutti + +I superuser possono rendere l'MFA obbligatoria su tutta l'istanza: + +1. Vai su **Connect \> Authorization \> MFA Settings**. +2. Nella scheda **MFA Settings** (visibile solo ai Superuser), seleziona **Require Multi-Factor Authentication Globally**. +3. Invia. + +Questa opzione è **disattivata per impostazione predefinita**. + +Una volta attivata, qualsiasi utente che non si è ancora registrato viene inviato alla schermata di configurazione dell'MFA al prossimo accesso e **non può saltarla**. Completa la registrazione, salva i codici di recupero e arriva alla destinazione originariamente prevista. + +### Utenti SSO + +L'MFA è applicata da DefectDojo, non delegata al tuo identity provider. Con l'MFA globale obbligatoria, anche gli utenti che accedono tramite SSO vengono inviati a configurare l'MFA dopo che il loro provider li restituisce a DefectDojo, e viene richiesto loro un codice negli accessi successivi. + +Non esiste un'impostazione per esentare gli utenti SSO. Se il tuo identity provider applica già una propria MFA, valuta consapevolmente se vuoi entrambe: attivare l'MFA globale significherà due richieste per gli utenti SSO. + +## Recuperare un utente che ha perso il proprio dispositivo MFA + +Procedi in quest'ordine: + +1. **Usa un codice di recupero.** Se l'utente ha ancora i codici di recupero, ne inserisce uno al posto di un codice dell'app in fase di accesso, poi configura di nuovo l'MFA da zero. +2. **Se è ancora connesso da qualche parte,** può andare su **MFA Settings** e fare clic su **Disable MFA** senza bisogno di un codice, quindi registrarsi di nuovo. +3. **Chiedi a un amministratore di rimuovere la sua MFA.** Con accesso al server, un amministratore può rimuovere l'MFA da un account: + + ``` + python manage.py remove_mfa --username + ``` + + Il comando accetta anche `--user-id` o `--email` al posto di `--username` (ne è richiesto esattamente uno; `--email` non distingue tra maiuscole e minuscole). Chiede conferma prima di applicare la modifica. L'utente può quindi accedere con la sola password e registrarsi di nuovo. + + Si tratta di un comando shell, quindi richiede accesso al container o all'host di DefectDojo. Non esiste un pulsante equivalente nell'interfaccia né un endpoint nell'API. Su **DefectDojo Cloud**, contatta [DefectDojo Support](mailto:support@defectdojo.com) per farlo eseguire. + +Creare un account sostitutivo **non** è necessario: rimuovere l'MFA preserva le autorizzazioni, la cronologia e le assegnazioni esistenti dell'utente. + +## MFA e l'API + +Quando un utente ha l'MFA abilitata, le richieste a `/api/v2/api-token-auth/` (l'endpoint che scambia un nome utente e una password con un token API) devono includere anche un codice MFA, in un campo `mfa_code` accanto alle credenziali. È accettato sia un codice TOTP corrente sia un codice di recupero non utilizzato; passare qui un codice di recupero lo **consuma**. + +Un codice mancante o errato restituisce lo stesso errore generico *"Unable to log in with provided credentials"* di una password errata, quindi se le richieste di token iniziano a fallire dopo che un utente ha abilitato l'MFA, questa è la prima cosa da controllare. + +**I token API esistenti continuano a funzionare.** Abilitare o disabilitare l'MFA non revoca né ruota i token già emessi: il controllo MFA si applica al momento dell'emissione di un token, non a ogni richiesta effettuata con esso. Le automazioni di lunga durata che già possiedono un token non sono influenzate dalla registrazione di un utente all'MFA. diff --git a/docs/content/admin/user_management/PRO__mfa.pt-br.md b/docs/content/admin/user_management/PRO__mfa.pt-br.md new file mode 100644 index 0000000000..cffbe3a8f0 --- /dev/null +++ b/docs/content/admin/user_management/PRO__mfa.pt-br.md @@ -0,0 +1,85 @@ +--- +title: Autenticação Multifator (MFA) +description: Configure o MFA em sua própria conta, exija-o em toda a sua instância + e recupere um usuário que perdeu o dispositivo +audience: pro +weight: 3 +--- + +A autenticação multifator adiciona uma segunda etapa ao login: depois da sua senha, o DefectDojo solicita um código de seis dígitos de um aplicativo autenticador. Recomendamos fortemente exigi-la para todos os usuários em instâncias que não estejam atrás de SSO. + +O MFA do DefectDojo Pro usa um **aplicativo autenticador TOTP** — Google Authenticator, 1Password, Authy, ou qualquer outro aplicativo que leia um QR code padrão. Não há opção de e-mail ou SMS. + +## Configurando o MFA na sua conta + +1. Vá até **Connect \> Authorization \> MFA Settings**. +2. Em **Personal Multi-Factor Authentication Settings**, clique em **Set Up MFA**. +3. Leia o QR code com seu aplicativo autenticador. Se você não conseguir ler o código, a tela de configuração também mostra a chave em formato de texto, que você pode digitar manualmente no seu aplicativo. +4. Digite o código de seis dígitos exibido pelo seu aplicativo, e clique em **Verify & enable**. +5. O DefectDojo mostra seus **códigos de recuperação**. Salve-os em um local seguro antes de continuar — veja abaixo. Clique em **Copy codes**, guarde-os, depois clique em **I've saved them. Continue**. + +O MFA fica ativo a partir desse momento. Na próxima vez que você fizer login, o DefectDojo pedirá um código depois da sua senha. + +### Códigos de recuperação + +Você recebe **dez códigos de recuperação de uso único** ao ativar o MFA. Cada um pode ser usado uma vez, no lugar de um código do seu aplicativo autenticador, e é consumido ao ser usado. + +Eles são exibidos **uma única vez**, na tela final de configuração. Depois disso, a página MFA Settings mostra apenas quantos códigos ainda restam, não os códigos em si. + +Se você perder seus códigos de recuperação — ou quiser um novo conjunto depois de usar vários — clique em **Regenerate Recovery Codes** na página MFA Settings. Isso **substitui todos os seus códigos existentes**: qualquer código salvo anteriormente para de funcionar imediatamente, então salve o novo conjunto assim que possível. + +Os códigos de recuperação são o que permite que você volte a acessar a conta quando perde o celular, então guarde-os em um local separado do dispositivo que executa seu aplicativo autenticador. + +### Desativando o MFA + +**Disable MFA** na página MFA Settings o desativa para sua própria conta. Você só precisa estar logado — não é solicitado nenhum código para confirmar. + +Se o seu administrador tiver tornado o MFA obrigatório, você será solicitado a configurá-lo novamente no próximo login. + +## Fazendo login com MFA + +Depois de digitar seu nome de usuário e senha, o DefectDojo solicita seu código de seis dígitos. Se você não tiver seu aplicativo autenticador, digite um dos seus **códigos de recuperação** no mesmo campo — esse código é então consumido. + +## Exigindo MFA para todos + +Superusuários podem tornar o MFA obrigatório em toda a instância: + +1. Vá até **Connect \> Authorization \> MFA Settings**. +2. No card **MFA Settings** — visível apenas para Superusuários — marque **Require Multi-Factor Authentication Globally**. +3. Envie o formulário. + +Isso vem **desativado por padrão**. + +Uma vez ativado, qualquer usuário que ainda não tenha se cadastrado é enviado para a tela de configuração de MFA no próximo login, e **não pode pular essa etapa**. O usuário conclui o cadastro, salva seus códigos de recuperação, e chega ao destino original. + +### Usuários SSO + +O MFA é aplicado pelo DefectDojo, e não delegado ao seu provedor de identidade. Com o MFA global exigido, os usuários que fazem login via SSO também são enviados para configurar o MFA depois que o provedor os retorna ao DefectDojo, e são solicitados a fornecer um código nos logins seguintes. + +Não há uma configuração para isentar usuários de SSO. Se o seu provedor de identidade já aplica seu próprio MFA, decida deliberadamente se você quer os dois — ativar o MFA global significa duas solicitações para usuários de SSO. + +## Recuperando um usuário que perdeu o dispositivo de MFA + +Siga estas etapas em ordem: + +1. **Use um código de recuperação.** Se o usuário ainda tiver seus códigos de recuperação, ele digita um deles em vez de um código do aplicativo no login, e depois configura o MFA novamente do zero. +2. **Se ele ainda estiver logado em algum lugar,** pode ir até **MFA Settings** e clicar em **Disable MFA** sem precisar de um código, depois se cadastrar novamente. +3. **Peça a um administrador para limpar o MFA dele.** Com acesso ao servidor, um administrador pode remover o MFA de uma conta: + + ``` + python manage.py remove_mfa --username + ``` + + O comando também aceita `--user-id` ou `--email` em vez de `--username` (exatamente um é obrigatório; `--email` não diferencia maiúsculas de minúsculas). Ele pede confirmação antes de fazer a alteração. O usuário pode então fazer login apenas com a senha e se cadastrar novamente. + + Este é um comando de shell, portanto requer acesso ao container ou host do DefectDojo. Não há um botão equivalente na interface, nem um endpoint na API. No **DefectDojo Cloud**, entre em contato com o [Suporte do DefectDojo](mailto:support@defectdojo.com) para que ele seja executado. + +Criar uma conta substituta **não** é necessário — limpar o MFA preserva as permissões, o histórico e as atribuições existentes do usuário. + +## MFA e a API + +Quando um usuário tem o MFA ativado, as requisições para `/api/v2/api-token-auth/` — o endpoint que troca um nome de usuário e senha por um token de API — também devem incluir um código de MFA, em um campo `mfa_code` junto com as credenciais. Tanto um código TOTP atual quanto um código de recuperação não utilizado são aceitos; usar um código de recuperação aqui o **consome**. + +Um código ausente ou incorreto retorna o mesmo erro genérico *"Unable to log in with provided credentials"* de uma senha incorreta, então, se as requisições de token começarem a falhar depois que um usuário ativar o MFA, esse é o primeiro ponto a verificar. + +**Os tokens de API existentes continuam funcionando.** Ativar ou desativar o MFA não revoga nem rotaciona tokens já emitidos — a verificação de MFA se aplica no momento em que um token é emitido, não em cada requisição feita com ele. Uma automação de longa duração que já possui um token não é afetada quando um usuário se cadastra no MFA. diff --git a/docs/content/admin/user_management/PRO__mfa.zh-hans.md b/docs/content/admin/user_management/PRO__mfa.zh-hans.md new file mode 100644 index 0000000000..bb1ff5ee88 --- /dev/null +++ b/docs/content/admin/user_management/PRO__mfa.zh-hans.md @@ -0,0 +1,84 @@ +--- +title: 多因素身份验证(MFA) +description: 在您自己的账户上设置 MFA、在整个实例中强制要求 MFA,并帮助丢失设备的用户恢复访问 +audience: pro +weight: 3 +--- + +多因素身份验证在登录时增加了一个额外步骤:在输入密码之后,DefectDojo 会要求您从身份验证器应用中获取一个六位数代码。我们强烈建议在未使用 SSO 的实例上,要求所有用户启用此功能。 + +DefectDojo Pro 的 MFA 使用**基于 TOTP 的身份验证器应用**——Google Authenticator、1Password、Authy,或任何其他可以扫描标准二维码的应用。没有电子邮件或短信选项。 + +## 在您的账户上设置 MFA + +1. 前往 **Connect \> Authorization \> MFA Settings**。 +2. 在**个人多因素身份验证设置(Personal Multi-Factor Authentication Settings)** 下,点击**设置 MFA(Set Up MFA)**。 +3. 使用您的身份验证器应用扫描二维码。如果无法扫描,设置界面也会以文本形式显示密钥,您可以手动将其输入到应用中。 +4. 输入应用显示的六位数代码,然后点击**验证并启用(Verify & enable)**。 +5. DefectDojo 会显示您的**恢复代码**。在继续之前,请将其保存到安全的地方——详见下文。点击**复制代码(Copy codes)**,保存好后再点击**我已保存,继续(I've saved them. Continue)**。 + +从这一刻起,MFA 即生效。下次登录时,DefectDojo 会在您输入密码后要求提供代码。 + +### 恢复代码 + +启用 MFA 时,系统会为您颁发**十个一次性恢复代码**。每个代码只能使用一次,可以替代身份验证器应用中的代码使用,使用后即失效。 + +这些代码**仅显示一次**,即在最后的设置界面上。此后,MFA 设置页面只会显示您还剩多少个代码,而不会显示代码本身。 + +如果您丢失了恢复代码——或者在使用了几个之后想要一套新的——请在 MFA 设置页面点击**重新生成恢复代码(Regenerate Recovery Codes)**。这会**替换您现有的所有代码**:之前保存的任何代码都会立即失效,因此请立刻保存新的一套代码。 + +恢复代码是您在丢失手机时重新登录的途径,因此请将它们存放在运行身份验证器应用的设备之外的地方。 + +### 关闭 MFA + +在 MFA 设置页面点击**禁用 MFA(Disable MFA)** 会为您自己的账户关闭该功能。您只需处于登录状态即可——系统不会要求您输入代码进行确认。 + +如果您的管理员已将 MFA 设为强制要求,您在下次登录时将被要求重新进行设置。 + +## 使用 MFA 登录 + +在输入用户名和密码后,DefectDojo 会要求提供您的六位数代码。如果您没有身份验证器应用,可以在同一字段中输入一个**恢复代码**代替——该代码随即会被使用。 + +## 为所有人强制要求 MFA + +超级用户可以在整个实例范围内将 MFA 设为强制要求: + +1. 前往 **Connect \> Authorization \> MFA Settings**。 +2. 在 **MFA 设置(MFA Settings)** 卡片中——仅超级用户可见——勾选**全局要求多因素身份验证(Require Multi-Factor Authentication Globally)**。 +3. 提交。 + +此选项**默认关闭**。 + +开启后,任何尚未注册 MFA 的用户在下次登录时都会被引导至 MFA 设置界面,并且**无法跳过此步骤**。他们完成注册、保存恢复代码后,就会进入原本要前往的页面。 + +### SSO 用户 + +MFA 由 DefectDojo 强制执行,而不是委托给您的身份提供商。在全局 MFA 强制要求开启的情况下,通过 SSO 登录的用户在其身份提供商将其重定向回 DefectDojo 后,同样会被引导设置 MFA,并在后续登录时被要求提供代码。 + +没有可以豁免 SSO 用户的设置。如果您的身份提供商已经强制执行其自身的 MFA,请慎重决定是否需要同时启用两者——开启全局 MFA 意味着 SSO 用户将需要经历两次提示。 + +## 恢复丢失 MFA 设备的用户 + +请按以下顺序操作: + +1. **使用恢复代码。** 如果用户仍持有恢复代码,可以在登录时输入其中一个来代替应用代码,然后重新从头设置 MFA。 +2. **如果用户在其他地方仍处于登录状态,** 可以前往 **MFA 设置**并点击**禁用 MFA**,无需代码即可操作,然后重新注册。 +3. **请管理员清除其 MFA。** 拥有服务器访问权限的管理员可以从账户中移除 MFA: + + ``` + python manage.py remove_mfa --username + ``` + + 该命令也接受使用 `--user-id` 或 `--email` 代替 `--username`(必须且只能指定其中一个;`--email` 不区分大小写)。在进行更改之前,系统会要求确认。之后,用户即可仅使用密码登录并重新注册。 + + 这是一条 shell 命令,因此需要访问 DefectDojo 容器或主机的权限。界面或 API 中没有等效的按钮或端点。在 **DefectDojo Cloud** 上,请联系 [DefectDojo 支持团队](mailto:support@defectdojo.com) 来执行此操作。 + +无需创建替代账户——清除 MFA 会保留用户现有的权限、历史记录和分配情况。 + +## MFA 与 API + +当用户启用了 MFA 后,向 `/api/v2/api-token-auth/`(该端点用于将用户名和密码兑换为 API 令牌)发出的请求还必须在凭据旁附带一个 `mfa_code` 字段中的 MFA 代码。系统接受当前的 TOTP 代码或未使用过的恢复代码;在此处传入恢复代码会**消耗**该代码。 + +缺少代码或代码错误时,会返回与密码错误相同的通用 *"Unable to log in with provided credentials"* 错误,因此如果用户启用 MFA 后令牌请求开始失败,这是首先要检查的地方。 + +**现有的 API 令牌仍会继续工作。** 启用或禁用 MFA 不会撤销或轮换已经颁发的令牌——MFA 检查只在令牌颁发时进行,而不是在每次使用该令牌发出请求时进行。已经持有令牌的长期运行的自动化流程,不会因用户注册 MFA 而受到影响。 diff --git a/docs/content/admin/user_management/PRO__resetting_user_credentials.it.md b/docs/content/admin/user_management/PRO__resetting_user_credentials.it.md new file mode 100644 index 0000000000..de34f94f50 --- /dev/null +++ b/docs/content/admin/user_management/PRO__resetting_user_credentials.it.md @@ -0,0 +1,34 @@ +--- +title: Reimpostazione in blocco delle credenziali utente +description: Ruota i token API e forza il reset della password per molti utenti contemporaneamente + dall'elenco Utenti +audience: pro +weight: 2 +--- + +L'elenco **Utenti** di DefectDojo Pro consente di ruotare i token API e forzare il reset della password per molti utenti contemporaneamente — utile per l'igiene periodica delle credenziali o per rispondere a un sospetto di esposizione di credenziali. + +Queste azioni in blocco sono disponibili solo per i **Superuser** e per gli utenti con il ruolo **Global Owner**. Se non si dispone di uno di questi ruoli, le caselle di selezione e i pulsanti per le azioni in blocco non vengono visualizzati. + +## Selezione degli utenti + +Nell'elenco **Utenti**, utilizzare le caselle di selezione per selezionare uno o più utenti. Viene visualizzata una barra delle azioni in blocco con i pulsanti di reset. Ogni azione richiede una conferma in una finestra di dialogo prima di essere eseguita. + +L'azione si applica agli utenti selezionati esplicitamente. **Non è possibile includere il proprio account** in un reset in blocco: se il proprio account è tra le righe selezionate, i pulsanti per le azioni in blocco vengono disabilitati e viene mostrato un avviso. + +## Reimposta token API + +**Reimposta token API** ruota il token API di ciascun utente selezionato: DefectDojo elimina il token esistente dell'utente e ne emette uno nuovo. **Il token attuale dell'utente smette di funzionare immediatamente**, quindi eventuali script o integrazioni che utilizzano il vecchio token devono essere aggiornati con quello nuovo. + +* I nuovi valori del token **non** vengono mostrati all'amministratore. Ogni utente interessato riceve una notifica **"API Token Reset"** che lo invita a recuperare il nuovo token dall'interfaccia utente (recapitata in base alle impostazioni di notifica di quell'utente). + +## Forza il reset della password + +**Forza il reset della password** imposta il flag *force-password-reset-on-next-login* su ciascun utente selezionato. Alla successiva richiesta effettuata da quell'utente, DefectDojo lo reindirizza alla pagina **Change Password** e non gli consente di proseguire finché non imposta una nuova password. Il flag viene rimosso automaticamente una volta fatto ciò. + +Tenere presente cosa questa azione **non** fa: + +* Non imposta né genera casualmente una password temporanea, e non restituisce alcuna credenziale all'amministratore. +* Non invia agli utenti interessati alcuna email o notifica. Poiché non viene inviato alcun avviso automatico, informare gli utenti interessati tramite un altro canale che verrà loro richiesto di cambiare la password al prossimo accesso. + +> **Utenti SSO:** a differenza del modulo di modifica per il singolo utente (che disabilita il flag di reset forzato per gli account autorizzati tramite SSO), l'azione in blocco applica il flag a **tutti** gli utenti selezionati, indipendentemente dal metodo di autenticazione utilizzato. Poiché gli utenti SSO accedono tramite il proprio Identity Provider anziché con una password DefectDojo, forzare un reset della password per loro generalmente non ha senso — evitare di includere nella selezione utenti che utilizzano esclusivamente SSO. diff --git a/docs/content/admin/user_management/PRO__resetting_user_credentials.pt-br.md b/docs/content/admin/user_management/PRO__resetting_user_credentials.pt-br.md new file mode 100644 index 0000000000..2338e90f32 --- /dev/null +++ b/docs/content/admin/user_management/PRO__resetting_user_credentials.pt-br.md @@ -0,0 +1,34 @@ +--- +title: Redefinindo credenciais de usuários em massa +description: Rotacione tokens de API e force a redefinição de senha para vários usuários + de uma vez a partir da lista de Usuários +audience: pro +weight: 2 +--- + +A lista de **Usuários** do DefectDojo Pro permite rotacionar tokens de API e forçar a redefinição de senha para vários usuários de uma vez — útil para higiene periódica de credenciais ou para responder a uma suspeita de exposição de credenciais. + +Essas ações em massa estão disponíveis apenas para **Superusuários** e usuários com o papel **Global Owner**. Se você não tiver uma dessas permissões, as caixas de seleção e os botões de ação em massa não aparecem. + +## Selecionando usuários + +Na lista de **Usuários**, use as caixas de seleção para selecionar um ou mais usuários. Uma barra de ações em massa aparece com os botões de redefinição. Cada ação pede confirmação em uma caixa de diálogo antes de ser executada. + +A ação se aplica aos usuários que você marcou explicitamente. Você **não pode incluir sua própria conta** em uma redefinição em massa: se sua conta estiver entre as linhas selecionadas, os botões de ação em massa ficam desabilitados e um aviso é exibido. + +## Reset API Tokens + +**Reset API Tokens** rotaciona o token de API de cada usuário selecionado: o DefectDojo exclui o token existente do usuário e emite um novo. **O token atual do usuário para de funcionar imediatamente**, portanto qualquer script ou integração que use o token antigo precisa ser atualizado com o novo. + +* Os novos valores de token **não** são exibidos para você como administrador. Cada usuário afetado recebe uma notificação de **"API Token Reset"** informando que deve obter o novo token na interface (entregue de acordo com as configurações de notificação desse usuário). + +## Force Password Reset + +**Force Password Reset** define o sinalizador *force-password-reset-on-next-login* em cada usuário selecionado. Na próxima vez que esse usuário fizer uma requisição, o DefectDojo o redireciona para a página **Change Password** e não permite que ele continue até definir uma nova senha. O sinalizador é removido automaticamente assim que isso acontece. + +Tenha em mente o que essa ação **não** faz: + +* Ela **não** define nem randomiza uma senha temporária, e **não** retorna nenhuma credencial para você. +* Ela **não** envia um e-mail ou notificação aos usuários afetados. Como não há aviso automático, informe os usuários afetados por outro canal de que serão solicitados a alterar a senha no próximo login. + +> **Usuários SSO:** Diferente do formulário de edição de usuário único (que desabilita o sinalizador de redefinição forçada para contas autorizadas via SSO), a ação em massa aplica o sinalizador a **todos** os usuários selecionados, independentemente de como eles se autenticam. Como os usuários SSO fazem login através do seu Provedor de Identidade em vez de uma senha do DefectDojo, forçar uma redefinição de senha para eles geralmente não faz sentido — evite incluir usuários somente-SSO na seleção. diff --git a/docs/content/admin/user_management/PRO__resetting_user_credentials.zh-hans.md b/docs/content/admin/user_management/PRO__resetting_user_credentials.zh-hans.md new file mode 100644 index 0000000000..ddb9d24dce --- /dev/null +++ b/docs/content/admin/user_management/PRO__resetting_user_credentials.zh-hans.md @@ -0,0 +1,33 @@ +--- +title: 批量重置用户凭据 +description: 从用户列表中一次性为多个用户轮换 API 令牌并强制重置密码 +audience: pro +weight: 2 +--- + +DefectDojo Pro 的**用户**列表允许您一次性为多个用户轮换 API 令牌并强制重置密码——这在定期进行凭据维护或应对疑似凭据泄露事件时非常有用。 + +这些批量操作仅对**超级用户**和拥有**全局所有者**角色的用户可用。如果您不具备这些身份之一,则不会显示选择复选框和批量操作按钮。 + +## 选择用户 + +在**用户**列表中,使用复选框选择一个或多个用户。此时会出现一个包含重置按钮的批量操作栏。每个操作在执行前都会弹出对话框要求您确认。 + +该操作仅适用于您明确勾选的用户。您**不能在批量重置中包含自己的账户**:如果您的账户位于所选行中,批量操作按钮将被禁用,并显示警告信息。 + +## 重置 API 令牌 + +**重置 API 令牌**会为每个所选用户轮换 API 令牌:DefectDojo 会删除该用户现有的令牌并签发一个新令牌。**该用户当前的令牌会立即失效**,因此任何使用旧令牌的脚本或集成都必须更新为新令牌。 + +* 新的令牌值**不会**显示给作为管理员的您。每个受影响的用户都会收到一条**“API 令牌已重置”**通知,告知他们从界面中获取新令牌(通知的送达方式取决于该用户的通知设置)。 + +## 强制重置密码 + +**强制重置密码**会为每个所选用户设置*下次登录时强制重置密码*标志。该用户下次发出请求时,DefectDojo 会将其重定向到**更改密码**页面,并在其设置新密码之前不允许继续操作。一旦用户完成设置,该标志会自动清除。 + +请注意此操作**不会**做以下事情: + +* 它**不会**设置或随机生成临时密码,也**不会**向您返回任何凭据。 +* 它**不会**向受影响的用户发送电子邮件或通知。由于没有自动通知,请通过其他渠道告知受影响的用户,他们将在下次登录时被提示更改密码。 + +> **SSO 用户:**与单用户编辑表单(该表单会为通过 SSO 授权的账户禁用强制重置标志)不同,批量操作会将该标志应用于**所有**所选用户,无论其使用何种身份验证方式。由于 SSO 用户是通过您的身份提供商登录,而非使用 DefectDojo 密码,因此对其强制重置密码通常没有意义——请避免在所选范围中包含仅使用 SSO 登录的用户。 diff --git a/docs/content/admin/user_management/_index.it.md b/docs/content/admin/user_management/_index.it.md new file mode 100644 index 0000000000..04c94ae885 --- /dev/null +++ b/docs/content/admin/user_management/_index.it.md @@ -0,0 +1,43 @@ +--- +title: Gestione utenti +description: Gestisci utenti, controllo degli accessi e autenticazione in DefectDojo +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 5 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- + +La gestione utenti di DefectDojo è diversa in ciascuna edizione. Scegli la sezione che corrisponde alla tua installazione. + +## DefectDojo Open-Source + +DefectDojo open-source utilizza il modello **Utenti autorizzati**: a un utente viene concesso l'accesso a un Prodotto o a un Tipo di prodotto aggiungendolo all'elenco Utenti autorizzati di quel record. I Superuser e lo staff possono vedere tutto. + +* [Utenti autorizzati](./os__authorized_users/) — come concedere l'accesso a Prodotti e Tipi di prodotto + +L'autenticazione su DefectDojo open-source si basa su nome utente/password locali, oltre al flusso di reset della password. + +## DefectDojo Pro + +DefectDojo Pro utilizza un sistema basato sui ruoli con Membri, Gruppi e Ruoli globali. Agli utenti può inoltre essere concesso l'accesso SSO tramite SAML o uno dei provider OAuth supportati. + +* [Autorizzazioni in DefectDojo](./about_perms_and_roles/) — panoramica di Ruoli, Appartenenze, Ruoli globali e Autorizzazioni di configurazione +* [Imposta le autorizzazioni di un utente](./set_user_permissions/) — assegnazione di Ruoli, Ruoli globali e Autorizzazioni di configurazione +* [Condividi le autorizzazioni: Gruppi di utenti](./create_user_group/) — assegnazione delle autorizzazioni a molti utenti contemporaneamente +* [Imposta le autorizzazioni in Pro](./pro_permissions_overhaul/) — interfaccia specifica di Pro per la gestione di Membri e Autorizzazioni +* [Reimpostazione in blocco delle credenziali utente](./pro__resetting_user_credentials/) — ruota i token API e forza il reset della password per molti utenti contemporaneamente +* [Tabelle delle autorizzazioni per azione](./user_permission_chart/) — riferimento completo di ogni autorizzazione per ogni Ruolo predefinito +* [Ruoli RBAC personalizzati](./pro__custom_rbac_roles/) — crea i tuoi ruoli scegliendo le singole autorizzazioni +* [Single Sign-On](/admin/sso/) — configurazione SAML e OAuth per Pro + +## Migrazione tra edizioni + +Se stai passando dagli Utenti autorizzati di open-source all'RBAC di Pro, oppure stai eseguendo l'aggiornamento da una versione open-source precedente alla 3.0 che utilizzava l'RBAC verso l'attuale modello Utenti autorizzati, consulta le [note di aggiornamento alla 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization). L'accesso esistente viene preservato automaticamente. diff --git a/docs/content/admin/user_management/_index.pt-br.md b/docs/content/admin/user_management/_index.pt-br.md new file mode 100644 index 0000000000..e32064ceaf --- /dev/null +++ b/docs/content/admin/user_management/_index.pt-br.md @@ -0,0 +1,43 @@ +--- +title: Gerenciamento de Usuários +description: Gerencie usuários, controle de acesso e autenticação no DefectDojo +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 5 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- + +A superfície de gerenciamento de usuários do DefectDojo é diferente em cada edição. Escolha a seção que corresponde à sua instalação. + +## DefectDojo Open-Source + +O DefectDojo open-source usa o modelo de **Usuários Autorizados**: um usuário recebe acesso a um Produto ou a um Tipo de Produto ao ser adicionado à lista de Usuários Autorizados desse registro. Superusuários e a equipe (staff) podem ver tudo. + +* [Usuários Autorizados](./os__authorized_users/) — como conceder acesso a Produtos e Tipos de Produto + +A autenticação no DefectDojo open-source é feita por usuário/senha local, além do fluxo de redefinição de senha. + +## DefectDojo Pro + +O DefectDojo Pro usa um sistema baseado em papéis (roles) com Membros, Grupos e Papéis Globais. Os usuários também podem receber acesso via SSO através de SAML ou de um dos provedores OAuth suportados. + +* [Permissões no DefectDojo](./about_perms_and_roles/) — visão geral de Papéis, Associações, Papéis Globais e Permissões de Configuração +* [Definir as Permissões de um Usuário](./set_user_permissions/) — atribuindo Papéis, Papéis Globais e Permissões de Configuração +* [Compartilhar permissões: Grupos de Usuários](./create_user_group/) — atribuindo permissões a vários usuários de uma vez +* [Definir Permissões no Pro](./pro_permissions_overhaul/) — interface específica do Pro para gerenciar Membros e Permissões +* [Redefinindo credenciais de usuários em massa](./pro__resetting_user_credentials/) — rotacione tokens de API e force a redefinição de senha para vários usuários de uma vez +* [Tabelas de permissões por ação](./user_permission_chart/) — referência completa de cada permissão para cada Papel integrado +* [Papéis RBAC Personalizados](./pro__custom_rbac_roles/) — crie seus próprios papéis escolhendo permissões individuais +* [Single Sign-On](/admin/sso/) — configuração de SAML e OAuth para o Pro + +## Migrando entre edições + +Se você está migrando dos Usuários Autorizados do open-source para o RBAC do Pro, ou atualizando de uma versão open-source anterior à 3.0 que usava RBAC para o modelo atual de Usuários Autorizados, consulte as [notas de atualização da 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization). O acesso existente é preservado automaticamente. diff --git a/docs/content/admin/user_management/_index.zh-hans.md b/docs/content/admin/user_management/_index.zh-hans.md new file mode 100644 index 0000000000..f1bb768f72 --- /dev/null +++ b/docs/content/admin/user_management/_index.zh-hans.md @@ -0,0 +1,43 @@ +--- +title: 用户管理 +description: 管理 DefectDojo 中的用户、访问控制和身份验证 +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 5 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- + +DefectDojo 的用户管理界面在各版本中有所不同。请选择与您的安装版本相匹配的部分。 + +## DefectDojo 开源版 + +开源版 DefectDojo 使用**已授权用户**模型:通过将用户添加到某条记录的已授权用户列表,即可授予该用户访问对应产品或产品类型的权限。超级用户和职员可以查看所有内容。 + +* [已授权用户](./os__authorized_users/)——如何授予对产品和产品类型的访问权限 + +开源版 DefectDojo 的身份验证方式为本地用户名/密码,加上密码重置流程。 + +## DefectDojo Pro + +DefectDojo Pro 使用基于角色的系统,包括成员、组和全局角色。用户还可以通过 SAML 或受支持的某个 OAuth 提供商获得 SSO 访问权限。 + +* [DefectDojo 中的权限](./about_perms_and_roles/)——角色、成员身份、全局角色和配置权限概述 +* [设置用户权限](./set_user_permissions/)——分配角色、全局角色和配置权限 +* [共享权限:用户组](./create_user_group/)——一次性为多个用户分配权限 +* [在 Pro 中设置权限](./pro_permissions_overhaul/)——用于管理成员和权限的 Pro 专属界面 +* [批量重置用户凭据](./pro__resetting_user_credentials/)——一次性为多个用户轮换 API 令牌并强制重置密码 +* [操作权限图表](./user_permission_chart/)——每个内置角色所拥有的每项权限的完整参考 +* [自定义 RBAC 角色](./pro__custom_rbac_roles/)——通过选择单项权限构建您自己的角色 +* [单点登录](/admin/sso/)——Pro 版的 SAML 和 OAuth 配置 + +## 版本间迁移 + +如果您正在从开源版的已授权用户模型迁移到 Pro 版的 RBAC,或者正在从使用 RBAC 的 3.0 之前的开源版本升级到当前的已授权用户模型,请参阅 [3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。现有的访问权限将自动保留。 diff --git a/docs/content/admin/user_management/about_perms_and_roles.it.md b/docs/content/admin/user_management/about_perms_and_roles.it.md new file mode 100644 index 0000000000..97d708911b --- /dev/null +++ b/docs/content/admin/user_management/about_perms_and_roles.it.md @@ -0,0 +1,120 @@ +--- +title: Autorizzazioni in DefectDojo +description: Riepilogo dettagliato di tutte le opzioni di autorizzazione di DefectDojo + Pro +weight: 2 +audience: pro +aliases: +- /it/en/customize_dojo/user_management/about_perms_and_roles +--- + +> **Funzionalità di DefectDojo Pro.** Il sistema RBAC basato su Membri / Gruppi / Ruoli globali descritto in questa pagina fa parte di DefectDojo Pro. DefectDojo open-source utilizza il modello [Utenti autorizzati](../os__authorized_users/) — consulta quella pagina per il controllo degli accessi in open-source, e le [note di aggiornamento alla 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se stai passando da un'edizione all'altra. + +Se hai un team di utenti che lavora in DefectDojo, è importante configurare correttamente il controllo degli accessi basato sui ruoli (Role\-Based Access Control, RBAC) in modo che gli utenti possano accedere solo a dati specifici. I dati di sicurezza sono altamente sensibili, e le opzioni di controllo degli accessi di DefectDojo permettono di definire in modo specifico l'accesso alle informazioni per ciascun membro del team. + +Questo articolo è una panoramica di come funzionano le autorizzazioni in DefectDojo. Se preferisci una descrizione dettagliata di **ogni azione** che può essere controllata dalle Autorizzazioni, consulta il nostro articolo **[Tabella delle autorizzazioni](../user_permission_chart/)**. + +## Tipi di autorizzazioni + +DefectDojo gestisce quattro diversi tipi di autorizzazioni: + +* Gli utenti possono essere assegnati come **Membri** di **Prodotti o Tipi di prodotto**. L'appartenenza a un Prodotto è accompagnata da un **Ruolo** che consente agli utenti di visualizzare e interagire con i Tipi di dati (Tipi di prodotto, Prodotti, Engagement, Test e Riscontri) in DefectDojo. Gli utenti possono avere più appartenenze a Prodotti o Tipi di prodotto, con diversi livelli di accesso. +​ +* Gli utenti possono anche avere assegnate **Autorizzazioni di configurazione**, che consentono loro di accedere alle pagine di configurazione di DefectDojo. Le Autorizzazioni di configurazione non sono correlate a Prodotti o Tipi di prodotto, e non sono associate ai Ruoli. +​ +* Agli utenti possono essere assegnati **Ruoli globali**, che forniscono loro un livello di accesso standardizzato a tutti i Prodotti e Tipi di prodotto. +​ +* Gli utenti possono essere configurati come **Superuser**: ruoli di livello amministratore che conferiscono loro il controllo e l'accesso a tutti i dati e la configurazione di DefectDojo. + +Ciascuno di questi tipi di Autorizzazione può anche essere assegnato a un **Gruppo** **di utenti**. Se hai un numero elevato di utenti in DefectDojo, ad esempio un team di test dedicato a un determinato Prodotto, i Gruppi ti consentono di configurare e mantenere le autorizzazioni rapidamente. + +## Appartenenza a Prodotto/Tipo di prodotto \& Ruoli + +Quando gli utenti vengono assegnati come membri di un Prodotto o Tipo di prodotto, ricevono anche un ruolo che controlla come interagiscono con i dati dei Riscontri associati. + +### Riepilogo dei ruoli + +DefectDojo Pro include cinque **ruoli predefiniti**: Reader, Writer, Maintainer, Owner e API Importer. Ognuno di essi può essere assegnato a livello globale o all'interno di un Prodotto / Tipo di prodotto. + +I ruoli predefiniti sono preset bloccati. Non possono essere modificati o eliminati, e le loro autorizzazioni sono le stesse su ogni istanza di DefectDojo Pro. Se nessuno di essi si adatta al modo in cui lavora il tuo team, puoi crearne uno su misura scegliendo le singole autorizzazioni oppure clonando un ruolo predefinito e adattandolo. Vedi [Ruoli RBAC personalizzati](../pro__custom_rbac_roles/). + +Per "dati sottostanti" si intendono tutti i Prodotti, Engagement, Test, Riscontri o Endpoint annidati sotto un Prodotto, o Tipo di prodotto. + +* Gli **utenti Reader** possono visualizzare i dati sottostanti di qualsiasi Prodotto o Tipo di prodotto a cui sono assegnati, e aggiungere commenti. Non possono modificare, aggiungere o alterare in altro modo i dati sottostanti, ma possono esportare Report e aggiungere Note ai dati. +​ +* Gli **utenti Writer** hanno tutte le capacità dei Reader, oltre alla possibilità di aggiungere o modificare Engagement, Test e Riscontri. Non possono aggiungere nuovi Prodotti, né eliminare alcun dato sottostante. +​ +* Gli **utenti Maintainer** hanno tutte le capacità dei Writer, oltre alla possibilità di modificare Prodotti o Tipi di prodotto. Possono aggiungere nuovi Membri con Ruoli al Prodotto o Tipo di prodotto, e possono anche eliminare Engagement, Test e Riscontri. +​ +* Gli **utenti Owner** hanno il maggior livello di controllo su un Prodotto o Tipo di prodotto. Possono designare altri Owner, e possono anche eliminare i Prodotti o Tipi di prodotto a cui sono assegnati. +​ +* Gli **utenti API Importer** hanno capacità limitate. Questo Ruolo consente un accesso API limitato senza esporre la maggior parte degli endpoint API, quindi è utile per l'automazione o per utenti destinati a essere "esterni" a DefectDojo. Possono visualizzare i dati sottostanti, aggiungere / modificare Engagement, e importare dati di scansione. + +Per informazioni dettagliate sui Ruoli predefiniti, consulta la nostra **[Tabella delle autorizzazioni per ruolo](../user_permission_chart/)**. Per l'elenco completo delle autorizzazioni che è possibile assegnare a un ruolo, e per scoprire come crearne uno personalizzato, consulta **[Ruoli RBAC personalizzati](../pro__custom_rbac_roles/)**. + +### Ruoli globali + +Gli utenti con **Ruoli globali** possono visualizzare e interagire con qualsiasi Tipo di dati (Tipi di prodotto, Prodotti, Engagement, Test e Riscontri) in DefectDojo, in base al Ruolo assegnato. + +### Appartenenze ai gruppi + +I Gruppi di utenti possono essere aggiunti come Membri di un Prodotto o Tipo di prodotto. Gli utenti che fanno parte del Gruppo erediteranno l'accesso a tutti i Prodotti o Tipi di prodotto associati, e erediteranno il Ruolo assegnato al Gruppo. + +#### Utenti con più ruoli + +* Se un Utente viene assegnato come membro di un Prodotto, non gli vengono concesse automaticamente le autorizzazioni associate al Tipo di prodotto. + +* Se un Utente si ritrova con più di un ruolo sullo stesso Prodotto o Tipo di prodotto (ad esempio uno assegnato direttamente e un altro ereditato da un Gruppo), riceve le autorizzazioni **combinate** di tutti i ruoli che detiene in quel contesto. + +* Il Ruolo di Prodotto di un Utente ha sempre la precedenza sul suo Ruolo di Tipo di prodotto "predefinito". +​ +* Il Ruolo di Prodotto / Tipo di prodotto di un Utente ha sempre la precedenza sul suo Ruolo globale all'interno del Prodotto o Tipo di prodotto sottostante. Ad esempio, se un Utente ha un Ruolo di Tipo di prodotto Reader, ma è anche assegnato come Owner su un Prodotto annidato sotto quel Tipo di prodotto, avrà autorizzazioni Owner aggiuntive solo per quel Prodotto. +​ +* I Ruoli non possono togliere autorizzazioni, possono solo aggiungerne di nuove. Ad esempio, se un Utente ha un Ruolo di Tipo di prodotto o un Ruolo globale Owner, assegnargli un ruolo Reader su un determinato Prodotto non gli toglierà le autorizzazioni Owner su quel Prodotto. +​ +* Lo stato di Superuser ha sempre la precedenza su qualsiasi Ruolo assegnato. + +## Superuser + +I Superuser (Admin) non hanno limitazioni nel sistema. Possono modificare tutte le impostazioni, gestire gli utenti e avere accesso in lettura / scrittura a tutti i dati. Possono anche modificare le regole di accesso per tutti gli utenti in DefectDojo. I Superuser ricevono inoltre le notifiche per tutti i problemi e gli avvisi di sistema. + +Per impostazione predefinita, il primo account creato su una nuova istanza di DefectDojo avrà le autorizzazioni Superuser. Quell'utente potrà modificare le autorizzazioni per tutti gli utenti DefectDojo successivi. Solo un Superuser esistente può aggiungere un altro superuser, o assegnare un Ruolo globale a un utente. + + +## Autorizzazioni di configurazione + +Le Autorizzazioni di configurazione, sebbene simili, non sono correlate a Prodotti o Ruoli. Devono essere assegnate separatamente dai Ruoli. **Gli utenti normali non dispongono di alcuna Autorizzazione di configurazione per impostazione predefinita, e l'assegnazione di queste autorizzazioni di configurazione deve essere effettuata con attenzione.** + +Le Autorizzazioni di configurazione possono essere assegnate agli utenti in diversi modi: + +1. Le Autorizzazioni di configurazione possono essere assegnate direttamente agli utenti. Le autorizzazioni specifiche possono essere configurate direttamente nella pagina di un Utente. + +2. Le Autorizzazioni di configurazione possono essere assegnate ai Gruppi di utenti. Come per i Ruoli, è possibile aggiungere Autorizzazioni di configurazione specifiche ai Gruppi, il che conferirà queste autorizzazioni a tutti i membri del Gruppo. + +I Superuser dispongono di tutte le Autorizzazioni di configurazione, quindi non hanno una sezione Autorizzazioni di configurazione nella loro pagina Utente. + +### Autorizzazioni di configurazione del gruppo + +Se gli utenti fanno parte di un Gruppo, dispongono anche di Autorizzazioni di configurazione del gruppo che controllano il loro livello di accesso alla configurazione di un Gruppo. Le Autorizzazioni del gruppo non corrispondono all'appartenenza del Gruppo a Prodotti o Tipi di prodotto. + +Se gli utenti creano un nuovo Gruppo, ricevono per impostazione predefinita il ruolo Owner del nuovo Gruppo. + +Per ulteriori informazioni sulle Autorizzazioni di configurazione, consulta la nostra **[Tabella delle autorizzazioni di configurazione](../user_permission_chart/#configuration-permission-chart)**. + +## Gestire le autorizzazioni predefinite + +Quando in DefectDojo viene creato un nuovo utente — manualmente, tramite SAML / SSO, o tramite un qualsiasi provider di social-auth — questo **non ha alcuna autorizzazione per impostazione predefinita**. Al primo accesso vedrà zero Tipi di prodotto, zero Prodotti e zero Engagement. Non può visualizzare né interagire con alcun dato finché un Superuser non gli concede l'accesso (direttamente, tramite un Ruolo globale, tramite un'appartenenza a Prodotto / Tipo di prodotto, o aggiungendolo a un Gruppo). + +Se desideri che ogni nuovo utente creato riceva automaticamente un livello di accesso di base — ad esempio, "ogni nuovo utente SSO deve essere Reader in un determinato gruppo" — puoi configurare un **Default group** nella pagina System Settings. + +1. Apri **⚙️ Configuration → System Settings** (solo Superuser). +2. Imposta **Default group** sul [Gruppo di utenti](../create_user_group/) a cui devono unirsi i nuovi utenti creati. +3. Imposta **Default group role** sul ruolo che devono avere in quel gruppo (ad es. **Reader**). +4. Facoltativamente, imposta **Default group email pattern** su un'espressione regolare (ad es. `.*@yourcompany\.com$`) in modo che il gruppo predefinito venga applicato solo agli utenti la cui email corrisponde. +5. Save. + +Sia **Default group** che **Default group role** devono essere impostati — se uno dei due è vuoto, il gruppo predefinito non viene applicato. + +Questa impostazione si applica a ogni percorso di creazione utente: creazione manuale, SAML, OAuth e altri provider di social-auth. Non viene applicata retroattivamente — gli utenti esistenti manterranno le loro appartenenze ai gruppi attuali anche se modifichi questa impostazione in seguito. + +Per indicazioni specifiche su SSO, consulta [Configurazione SAML](/admin/sso/pro__saml/#default-access-for-sso-provisioned-users) o la sezione del tuo provider in [Configurazione SSO](../configure_sso/). diff --git a/docs/content/admin/user_management/about_perms_and_roles.pt-br.md b/docs/content/admin/user_management/about_perms_and_roles.pt-br.md new file mode 100644 index 0000000000..e10f0cfa7d --- /dev/null +++ b/docs/content/admin/user_management/about_perms_and_roles.pt-br.md @@ -0,0 +1,119 @@ +--- +title: Permissões no DefectDojo +description: Resumo detalhado de todas as opções de permissão do DefectDojo Pro +weight: 2 +audience: pro +aliases: +- /pt-br/en/customize_dojo/user_management/about_perms_and_roles +--- + +> **Recurso do DefectDojo Pro.** O sistema de RBAC de Membros / Grupos / Papéis Globais descrito nesta página faz parte do DefectDojo Pro. O DefectDojo open-source usa o modelo de [Usuários Autorizados](../os__authorized_users/) — consulte essa página para o controle de acesso do open-source, e as [notas de atualização da 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se você estiver migrando entre edições. + +Se você tem uma equipe de usuários trabalhando no DefectDojo, é importante configurar adequadamente o Controle de Acesso Baseado em Papéis (RBAC) para que os usuários só possam acessar dados específicos. Dados de segurança são altamente sensíveis, e as opções de controle de acesso do DefectDojo permitem que você seja específico sobre o acesso de cada membro da equipe às informações. + +Este artigo é uma visão geral de como as permissões funcionam no DefectDojo. Se você preferir ver um detalhamento de **cada ação** que pode ser controlada pelas Permissões, consulte nosso artigo **[Tabela de Permissões](../user_permission_chart/)**. + +## Tipos de Permissões + +O DefectDojo gerencia quatro tipos diferentes de permissões: + +* Os usuários podem ser designados como **Membros** de **Produtos ou Tipos de Produto**. Uma Associação a Produto vem com um **Papel** que permite aos seus usuários visualizar e interagir com Tipos de Dados (Tipos de Produto, Produtos, Engajamentos, Testes e Achados) no DefectDojo. Os usuários podem ter múltiplas associações a Produtos ou Tipos de Produto, com diferentes níveis de acesso. +​ +* Os usuários também podem ter **Permissões de Configuração** atribuídas, que permitem acessar páginas de configuração no DefectDojo. As Permissões de Configuração não estão relacionadas a Produtos ou Tipos de Produto, e não estão associadas a Papéis. +​ +* Os usuários podem receber **Papéis Globais**, que dão a eles um nível padronizado de acesso a todos os Produtos e Tipos de Produto. +​ +* Os usuários podem ser configurados como **Superusuários**: papéis de nível administrativo que dão a eles controle e acesso a todos os dados e configurações do DefectDojo. + +Cada um desses tipos de Permissão também pode ser atribuído a um **Grupo** de **Usuários**. Se você tiver um grande número de usuários no DefectDojo, como uma equipe de testes dedicada a um Produto específico, os Grupos permitem configurar e manter as permissões rapidamente. + +## Associação a Produto/Tipo de Produto e Papéis + +Quando os usuários são designados como membros de um Produto ou Tipo de Produto, eles também recebem um papel que controla como interagem com os dados de Achados associados. + +### Resumo dos Papéis + +O DefectDojo Pro vem com cinco **papéis integrados**: Reader, Writer, Maintainer, Owner e API Importer. Qualquer um deles pode ser atribuído globalmente ou dentro de um Produto / Tipo de Produto. + +Os papéis integrados são predefinições fixas. Eles não podem ser editados ou excluídos, e suas permissões são as mesmas em todas as instâncias do DefectDojo Pro. Se nenhum deles se encaixar na forma como sua equipe trabalha, você pode criar um papel que se encaixe, escolhendo permissões individuais ou clonando um papel integrado e ajustando-o. Veja [Papéis RBAC Personalizados](../pro__custom_rbac_roles/). + +"Dados subjacentes" refere-se a todos os Produtos, Engajamentos, Testes, Achados ou Endpoints aninhados sob um Produto, ou Tipo de Produto. + +* **Usuários Reader** podem visualizar os dados subjacentes de qualquer Produto ou Tipo de Produto ao qual estejam atribuídos, e adicionar comentários. Eles não podem editar, adicionar ou modificar de outra forma nenhum dado subjacente, mas podem exportar Relatórios e adicionar Notas aos dados. +​ +* **Usuários Writer** têm todas as habilidades de Reader, além da capacidade de Adicionar ou Editar Engajamentos, Testes e Achados. Eles não podem adicionar novos Produtos, e não podem Excluir nenhum dado subjacente. +​ +* **Usuários Maintainer** têm todas as habilidades de Writer, além da capacidade de editar Produtos ou Tipos de Produto. Eles podem adicionar novos Membros com Papéis ao Produto ou Tipo de Produto, e também podem Excluir Engajamentos, Testes e Achados. +​ +* **Usuários Owner** têm o maior nível de controle sobre um Produto ou Tipo de Produto. Eles podem designar outros Owners, e também podem Excluir os Produtos ou Tipos de Produto aos quais estão atribuídos. +​ +* **Usuários API Importer** têm habilidades limitadas. Este Papel permite acesso limitado à API sem expor a maioria dos endpoints da API, sendo útil para automação ou para usuários que devem ser 'externos' ao DefectDojo. Eles podem visualizar dados subjacentes, Adicionar / Editar Engajamentos, e Importar Dados de Varredura. + +Para informações detalhadas sobre os Papéis integrados, consulte nossa **[Tabela de Permissões por Papel](../user_permission_chart/)**. Para a lista completa de permissões que um papel pode receber, e como criar o seu próprio, veja **[Papéis RBAC Personalizados](../pro__custom_rbac_roles/)**. + +### Papéis Globais + +Usuários com **Papéis Globais** podem visualizar e interagir com qualquer Tipo de Dados (Tipos de Produto, Produtos, Engajamentos, Testes e Achados) no DefectDojo, dependendo do Papel atribuído a eles. + +### Associações de Grupo + +Grupos de Usuários podem ser adicionados como Membros de um Produto ou Tipo de Produto. Os usuários que fazem parte do Grupo herdarão acesso a todos os Produtos ou Tipos de Produto associados, e herdarão o Papel atribuído ao Grupo. + +#### Usuários com múltiplos papéis + +* Se um Usuário é designado como membro de um Produto, ele não recebe automaticamente as permissões associadas do Tipo de Produto. + +* Se um Usuário acabar com mais de um papel no mesmo Produto ou Tipo de Produto (por exemplo, um atribuído diretamente e outro herdado de um Grupo), ele recebe as permissões **combinadas** de todos os papéis que possui ali. + +* O Papel de Produto de um Usuário sempre substitui seu Papel de Tipo de Produto 'padrão'. +​ +* O Papel de Produto / Tipo de Produto de um Usuário sempre substitui seu Papel Global dentro do Produto ou Tipo de Produto subjacente. Por exemplo, se um Usuário tem um Papel de Tipo de Produto de Reader, mas também está atribuído como Owner em um Produto aninhado sob esse Tipo de Produto, ele terá permissões adicionais de Owner somente para esse Produto. +​ +* Os Papéis não podem retirar permissões, eles só podem adicionar novas. Por exemplo, se um Usuário tem um Papel de Tipo de Produto ou Papel Global de Owner, atribuir a ele um papel de Reader em um Produto específico não removerá suas permissões de Owner nesse Produto. +​ +* O status de Superusuário sempre substitui quaisquer Papéis atribuídos. + +## Superusuários + +Os Superusuários (Admins) não têm limitações no sistema. Eles podem alterar todas as configurações, gerenciar usuários e têm acesso de leitura/gravação a todos os dados. Eles também podem alterar as regras de acesso para todos os usuários do DefectDojo. Os Superusuários também recebem notificações de todos os problemas e alertas do sistema. + +Por padrão, a primeira conta criada em uma nova instância do DefectDojo terá permissões de Superusuário. Esse usuário poderá editar as permissões de todos os usuários do DefectDojo criados posteriormente. Somente um Superusuário existente pode adicionar outro superusuário, ou adicionar um Papel Global a um usuário. + + +## Permissões de Configuração + +As Permissões de Configuração, embora semelhantes, não estão relacionadas a Produtos ou Papéis. Elas devem ser atribuídas separadamente dos Papéis. **Usuários comuns não têm nenhuma Permissão de Configuração por padrão, e a atribuição dessas permissões de configuração deve ser feita com cuidado.** + +Os usuários podem ter Permissões de Configuração atribuídas de diferentes formas: + +1. Os usuários podem receber Permissões de Configuração diretamente. Permissões específicas podem ser configuradas diretamente na página de um Usuário. + +2. Grupos de Usuários podem receber Permissões de Configuração. Assim como com os Papéis, Permissões de Configuração específicas podem ser adicionadas aos Grupos, o que dará a todos os membros do Grupo essas permissões. + +Os Superusuários têm todas as Permissões de Configuração, portanto não têm uma seção de Permissões de Configuração em sua página de Usuário. + +### Permissões de Configuração de Grupo + +Se os usuários fazem parte de um Grupo, eles também têm Permissões de Configuração de Grupo, que controlam seu nível de acesso à configuração de um Grupo. As Permissões de Grupo não correspondem à associação do Grupo a Produtos ou Tipos de Produto. + +Se os usuários criarem um novo Grupo, receberão o papel de Owner do novo Grupo por padrão. + +Para mais informações sobre Permissões de Configuração, consulte nossa **[Tabela de Permissões de Configuração](../user_permission_chart/#configuration-permission-chart)**. + +## Gerenciar permissões padrão + +Quando um usuário totalmente novo é criado no DefectDojo — seja manualmente, via SAML / SSO, ou via qualquer provedor de social-auth — ele **não tem nenhuma permissão por padrão**. Ele verá zero Tipos de Produto, zero Produtos e zero Engajamentos no primeiro login. Ele não pode visualizar ou interagir com nenhum dado até que um Superusuário conceda acesso (diretamente, via um Papel Global, via uma associação a Produto / Tipo de Produto, ou adicionando-o a um Grupo). + +Se você quiser que todo usuário recém-provisionado receba automaticamente um nível básico de acesso — por exemplo, "todo novo usuário SSO deve ser Reader em um determinado grupo" — você pode configurar um **Grupo padrão** na página de Configurações do Sistema. + +1. Abra **⚙️ Configuration → System Settings** (somente Superusuário). +2. Defina **Default group** como o [Grupo de Usuários](../create_user_group/) ao qual os usuários recém-criados devem ser adicionados. +3. Defina **Default group role** como o papel que eles devem ter nesse grupo (por exemplo, **Reader**). +4. Opcionalmente, defina **Default group email pattern** como uma expressão regular (por exemplo, `.*@yourcompany\.com$`) para que o grupo padrão seja aplicado apenas a usuários cujo e-mail corresponda. +5. Salve. + +Tanto **Default group** quanto **Default group role** devem ser definidos — se algum estiver vazio, o grupo padrão não é aplicado. + +Essa configuração se aplica a todos os fluxos de criação de usuário: criação manual, SAML, OAuth e outros provedores de social-auth. Ela não é aplicada retroativamente — os usuários existentes manterão suas associações de grupo atuais mesmo que você altere essa configuração posteriormente. + +Para orientações específicas sobre SSO, consulte [Configuração SAML](/admin/sso/pro__saml/#default-access-for-sso-provisioned-users) ou a seção do seu provedor em [Configuração de SSO](../configure_sso/). diff --git a/docs/content/admin/user_management/about_perms_and_roles.zh-hans.md b/docs/content/admin/user_management/about_perms_and_roles.zh-hans.md new file mode 100644 index 0000000000..9d38880638 --- /dev/null +++ b/docs/content/admin/user_management/about_perms_and_roles.zh-hans.md @@ -0,0 +1,119 @@ +--- +title: DefectDojo 中的权限 +description: 详细汇总 DefectDojo Pro 的所有权限选项 +weight: 2 +audience: pro +aliases: +- /zh-hans/en/customize_dojo/user_management/about_perms_and_roles +--- + +> **DefectDojo Pro 功能。**本页所述的成员/组/全局角色 RBAC 系统是 DefectDojo Pro 的一部分。开源版 DefectDojo 使用[已授权用户](../os__authorized_users/)模型——有关开源版的访问控制,请参阅该页面;如果您正在版本之间迁移,请参阅 [3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。 + +如果您的团队有多名用户在 DefectDojo 中协作,那么适当地设置基于角色的访问控制(RBAC)非常重要,这样用户才能仅访问特定的数据。安全数据高度敏感,DefectDojo 的访问控制选项让您可以精确控制每位团队成员对信息的访问权限。 + +本文概述了 DefectDojo 中权限的工作方式。如果您想查看权限可控制的**每项操作**的详细分类,请参阅我们的**[权限图表](../user_permission_chart/)**文章。 + +## 权限类型 + +DefectDojo 管理四种不同类型的权限: + +* 用户可以被指定为**产品或产品类型**的**成员**。产品成员身份附带一个**角色**,使您的用户能够查看并操作 DefectDojo 中的数据类型(产品类型、产品、测试活动、测试和发现项)。用户可以拥有多个产品或产品类型的成员身份,并具有不同级别的访问权限。 +​ +* 用户还可以被指定**配置权限**,使其能够访问 DefectDojo 中的配置页面。配置权限与产品或产品类型无关,也不与角色关联。 +​ +* 用户可以被指定**全局角色**,使其对所有产品和产品类型拥有统一级别的访问权限。 +​ +* 用户可以被设置为**超级用户**:这是一种管理员级别的角色,使其对所有 DefectDojo 数据和配置拥有控制权和访问权。 + +以上每种权限类型也都可以指定给**用户组**。如果您在 DefectDojo 中有大量用户,例如某个产品的专职测试团队,组功能可以让您快速设置和维护权限。 + +## 产品/产品类型成员身份与角色 + +当用户被指定为产品或产品类型的成员时,他们还会获得一个角色,该角色控制其与相关发现项数据的交互方式。 + +### 角色概述 + +DefectDojo Pro 提供五种**内置角色**:读者、编写者、维护者、所有者和 API 导入者。这些角色都可以在全局范围内指定,也可以在特定产品/产品类型内指定。 + +内置角色是锁定的预设角色,无法编辑或删除,并且在每个 DefectDojo Pro 实例上的权限都相同。如果这些角色都不符合您团队的工作方式,您可以通过选择单项权限,或复制某个内置角色并进行调整,来构建适合的角色。请参阅[自定义 RBAC 角色](../pro__custom_rbac_roles/)。 + +“底层数据”是指嵌套在某个产品或产品类型下的所有产品、测试活动、测试、发现项或端点。 + +* **读者用户**可以查看其所分配到的任何产品或产品类型的底层数据,并添加评论。他们不能编辑、添加或以其他方式修改任何底层数据,但可以导出报告并为数据添加备注。 +​ +* **编写者用户**拥有读者的全部能力,此外还可以添加或编辑测试活动、测试和发现项。他们不能添加新产品,也不能删除任何底层数据。 +​ +* **维护者用户**拥有编写者的全部能力,此外还可以编辑产品或产品类型。他们可以为产品或产品类型添加带有角色的新成员,也可以删除测试活动、测试和发现项。 +​ +* **所有者用户**对产品或产品类型拥有最大程度的控制权。他们可以指定其他所有者,也可以删除其被分配到的产品或产品类型。 +​ +* **API 导入者用户**的能力有限。此角色允许有限的 API 访问,而不会暴露大部分 API 端点,因此适用于自动化场景,或原本就应“外部于” DefectDojo 的用户。他们可以查看底层数据、添加/编辑测试活动,以及导入扫描数据。 + +有关内置角色的详细信息,请参阅我们的**[角色权限图表](../user_permission_chart/)**。有关可赋予角色的完整权限列表,以及如何构建自定义角色,请参阅**[自定义 RBAC 角色](../pro__custom_rbac_roles/)**。 + +### 全局角色 + +拥有**全局角色**的用户可以根据其被指定的角色,查看并操作 DefectDojo 中的任何数据类型(产品类型、产品、测试活动、测试和发现项)。 + +### 组成员身份 + +用户组可以被添加为产品或产品类型的成员。属于该组的用户将继承对所有相关产品或产品类型的访问权限,并继承指定给该组的角色。 + +#### 拥有多个角色的用户 + +* 如果某用户被指定为某产品的成员,默认情况下不会被授予该产品所属产品类型的任何相关权限。 + +* 如果某用户在同一产品或产品类型上最终拥有多个角色(例如一个是直接指定的,另一个是从组继承而来的),他们将获得其在该处所持有的所有角色的**合并**权限。 + +* 用户的产品角色始终优先于其“默认”产品类型角色。 +​ +* 用户的产品/产品类型角色始终优先于其在该底层产品或产品类型内的全局角色。例如,如果某用户拥有某产品类型的读者角色,但同时被指定为该产品类型下某个产品的所有者,则其仅会针对该产品获得额外的所有者权限。 +​ +* 角色不能剥夺权限,只能叠加权限。例如,如果某用户拥有产品类型角色或全局角色为所有者,那么为其在某个特定产品上指定读者角色,并不会剥夺其在该产品上的所有者权限。 +​ +* 超级用户身份始终优先于任何已指定的角色。 + +## 超级用户 + +超级用户(管理员)在系统中不受任何限制。他们可以更改所有设置、管理用户,并对所有数据拥有读/写访问权限。他们还可以更改 DefectDojo 中所有用户的访问规则。超级用户还会收到所有系统问题和警报的通知。 + +默认情况下,在新的 DefectDojo 实例上创建的第一个账户将拥有超级用户权限。该用户将能够编辑此后所有 DefectDojo 用户的权限。只有现有的超级用户才能添加另一个超级用户,或为某用户添加全局角色。 + + +## 配置权限 + +配置权限虽然与角色类似,但与产品或角色并无关联,必须与角色分开单独指定。**普通用户默认没有任何配置权限,指定这些配置权限时应格外谨慎。** + +用户可以通过不同方式获得配置权限的指定: + +1. 用户可以被直接指定配置权限。具体权限可以直接在用户页面上配置。 + +2. 用户组可以被指定配置权限。与角色类似,可以为组添加特定的配置权限,这将使该组的所有成员都获得这些权限。 + +超级用户拥有所有配置权限,因此其用户页面上不会显示配置权限部分。 + +### 组配置权限 + +如果用户属于某个组,他们还会拥有组配置权限,用于控制其对该组配置的访问级别。组权限与该组的产品或产品类型成员身份并无对应关系。 + +如果用户创建了一个新组,默认情况下将被赋予该新组的所有者角色。 + +有关配置权限的更多信息,请参阅我们的**[配置权限图表](../user_permission_chart/#configuration-permission-chart)**。 + +## 管理默认权限 + +当 DefectDojo 中创建一个全新用户时——无论是手动创建、通过 SAML/SSO 创建,还是通过任何社交身份验证提供商创建——该用户**默认没有任何权限**。他们首次登录时将看不到任何产品类型、产品或测试活动。在超级用户为其授予访问权限之前(通过直接授权、全局角色、产品/产品类型成员身份,或将其添加到某个组),他们将无法查看或操作任何数据。 + +如果您希望每个新创建的用户都能自动获得基线级别的访问权限——例如“每个新的 SSO 用户都应成为某特定组的读者”——您可以在系统设置页面上配置**默认组**。 + +1. 打开**⚙️ 配置 → 系统设置**(仅限超级用户)。 +2. 将**默认组**设置为新创建用户应加入的[用户组](../create_user_group/)。 +3. 将**默认组角色**设置为他们在该组中应持有的角色(例如**读者**)。 +4. 您也可以选择将**默认组电子邮件模式**设置为一个正则表达式(例如 `.*@yourcompany\.com$`),使默认组仅应用于电子邮件地址匹配该模式的用户。 +5. 保存。 + +**默认组**和**默认组角色**都必须设置——如果其中任何一项为空,则不会应用默认组。 + +此设置适用于每一种用户创建方式:手动创建、SAML、OAuth 以及其他社交身份验证提供商。该设置不会追溯应用——即使您之后更改此设置,现有用户仍将保留其当前的组成员身份。 + +有关 SSO 相关的具体指导,请参阅 [SAML 配置](/admin/sso/pro__saml/#default-access-for-sso-provisioned-users),或[SSO 配置](../configure_sso/)下您所用提供商对应的部分。 diff --git a/docs/content/admin/user_management/create_user_group.it.md b/docs/content/admin/user_management/create_user_group.it.md new file mode 100644 index 0000000000..76e9fd6f44 --- /dev/null +++ b/docs/content/admin/user_management/create_user_group.it.md @@ -0,0 +1,144 @@ +--- +title: 'Condividi le autorizzazioni: Gruppi di utenti' +description: Condividi e gestisci le autorizzazioni per molti utenti in DefectDojo + Pro +weight: 3 +audience: pro +aliases: +- /it/en/customize_dojo/user_management/create_user_group +--- + +> **Funzionalità di DefectDojo Pro.** I Gruppi di utenti e il sistema RBAC sottostante fanno parte di DefectDojo Pro. DefectDojo open-source utilizza il modello [Utenti autorizzati](../os__authorized_users/) — consulta quella pagina per il controllo degli accessi in open-source, e le [note di aggiornamento alla 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se stai passando da un'edizione all'altra. + +Se hai un numero significativo di utenti DefectDojo, potresti voler creare uno o più **Gruppi**, per impostare le stesse regole di controllo degli accessi basato sui ruoli (RBAC) per molti utenti contemporaneamente. Solo i Superuser possono creare Gruppi di utenti. + +I Gruppi possono funzionare in più modi: + +* Impostare uno, o più Ruoli a livello di Prodotto o Tipo di prodotto per tutti i Membri del Gruppo, consentendo un controllo specifico su quali Prodotti o Tipi di prodotto possono essere accessibili e modificabili dal Gruppo. +* Impostare un Ruolo globale per tutti i Membri del Gruppo, dando loro visibilità e accesso a tutti i Prodotti o Tipi di prodotto. +* Impostare Autorizzazioni di configurazione per un Gruppo, consentendo loro di modificare funzionalità specifiche di DefectDojo. + +Per ulteriori informazioni sui Ruoli, consulta il nostro articolo **Introduzione ai Ruoli**. + +## La pagina Tutti i gruppi + +Dalla barra laterale, vai su 👤**Users \> Groups** per visualizzare un elenco di tutti i gruppi di utenti attivi e inattivi. + +![image](images/Create_a_User_Group_for_shared_permissions.png) +Da qui, puoi creare, eliminare o visualizzare le tue singole pagine dei Gruppi. + +Per gli utenti DefectDojo Pro, la pagina Tutti i gruppi dell'interfaccia Pro dispone di alcune opzioni aggiuntive. +* Puoi filtrare questa tabella per Nome del gruppo, Descrizione, Indirizzo e-mail, Ruolo globale, oltre che per il numero totale di Utenti, Tipi di prodotto e Prodotti associati al Gruppo. +* Puoi anche modificare le Autorizzazioni di un Gruppo o altre impostazioni facendo clic sul pulsante "⋮" accanto al Gruppo che desideri modificare. + +![image](images/all_groups_pro.png) + +## Visualizzazione di un gruppo + +La visualizzazione di un gruppo mostra tutte le informazioni del Gruppo, come ID, nome, descrizione, ruolo globale, ecc. Vengono inoltre visualizzati i Membri del gruppo, i Tipi di prodotto e i Prodotti associati al gruppo. Inoltre, le autorizzazioni di configurazione legate a un Gruppo possono essere aggiornate direttamente dalla pagina "View Group". + +Per gli utenti DefectDojo Pro, la vista Gruppo dell'interfaccia Pro consente di assegnare le modifiche alle Autorizzazioni di configurazione in modo leggermente diverso. + +![image](images/group_view_pro_ui.png) + +* Tutte le autorizzazioni di configurazione vengono visualizzate in un menu a discesa raggruppato in sottocategorie. Se la selezione delle autorizzazioni di configurazione è diversa dal valore attuale, viene visualizzato un pulsante "Update Configuration Permissions". + +![image](images/groups_pro_configuration_permissions.png) + +* Una volta selezionate alcune autorizzazioni aggiuntive, all'utente verrà chiesto di confermare di voler aggiornare le autorizzazioni per il gruppo selezionato prima che l'aggiornamento venga effettuato. + +## Creare / Modificare un Gruppo di utenti + +1. Vai alla pagina 👤**Users \> Groups** nella barra laterale. Vedrai un elenco di tutti i Gruppi di utenti esistenti, con il relativo Nome, Descrizione, Numero di utenti, Ruolo globale (se applicabile) ed Email. +​ + +![image](images/Create_a_User_Group_for_shared_permissions_2.png) + +2. Fai clic sul **🛠️ button** accanto all'intestazione All Groups, e seleziona **\+ New Group.** +​ + +![image](images/Create_a_User_Group_for_shared_permissions_3.png) + + +3. Questo ti porterà a una pagina in cui puoi creare un nuovo Gruppo. Imposta il Nome per questo Gruppo, e aggiungi una Descrizione se lo desideri. + +Puoi anche selezionare un Ruolo globale che desideri applicare a questo Gruppo, se lo desideri. Aggiungere un Ruolo globale al Gruppo darà a tutti i Membri del gruppo accesso a tutti i dati DefectDojo, insieme a un livello limitato di accesso in modifica a seconda del Ruolo globale scelto. Consulta il nostro articolo **Introduzione ai Ruoli** per maggiori informazioni. + +L'account che crea inizialmente un Gruppo avrà un Ruolo Owner per il Gruppo per impostazione predefinita. + +### Impostare un indirizzo email per ricevere i report + +Il Weekly Digest è un report su tutti i Prodotti / Tipi di prodotto assegnati al Gruppo. Per far inviare un Digest settimanale, inserisci l'indirizzo email di destinazione che desideri utilizzare nel modulo Create / Edit Group. I membri del Gruppo continueranno comunque a ricevere le notifiche come al solito. + +### Visualizzazione della pagina di un Gruppo + +Una volta creato un Gruppo, puoi accedervi selezionandolo nel menu elencato sotto **Users \> Groups.** + +La pagina del Gruppo può essere personalizzata con una **Descrizione**. Presenta un elenco di tutti i **Membri del gruppo,** oltre ai **Prodotti, Tipi di prodotto**, e al **Ruolo** associato a ciascuno di essi**.** + +Qui puoi anche vedere le **Autorizzazioni di configurazione** del Gruppo elencate. + +## Gestire gli utenti di un Gruppo + +L'appartenenza al Gruppo viene gestita dalla singola pagina del Gruppo, che puoi selezionare dall'elenco nella pagina **Users \> Groups**. Fai clic sul Nome del gruppo evidenziato per accedere alla pagina del Gruppo che desideri modificare. + +Per visualizzare o modificare l'appartenenza a un Gruppo, un Utente deve avere le Autorizzazioni di configurazione appropriate abilitate, oltre all'appartenenza al Gruppo (o lo stato di Superuser). + +### **Aggiungere un utente a un Gruppo** + +I Gruppi di utenti possono avere tutti gli Utenti assegnati che desideri. Tutti gli Utenti in un Gruppo riceveranno il Ruolo associato su ogni Prodotto o Tipo di prodotto elencato, ma gli Utenti possono anche avere Ruoli individuali che hanno la precedenza sul ruolo del Gruppo. + +1. Dalla pagina del Gruppo, seleziona **\+ Add Users** dal pulsante **☰** all'estremità dell'intestazione **Members**. +​ + +![image](images/Create_a_User_Group_for_shared_permissions_4.png) + +2. Questo ti porterà alla schermata **Add Some Group Members**. Apri il menu a discesa Users, e poi seleziona ciascun utente che desideri aggiungere al Gruppo. +​ + +![image](images/Create_a_User_Group_for_shared_permissions_5.png) + +3. Seleziona il Ruolo del gruppo che desideri assegnare a questi Utenti. Questo determina la loro capacità di configurare il Gruppo. + +Nota che aggiungere un membro a un Gruppo non gli consentirà l'accesso alla propria pagina del Gruppo per impostazione predefinita. Questa è un'Autorizzazione di configurazione separata che deve essere prima abilitata. + +### **Modificare o eliminare un Membro da un Gruppo di utenti** + +1. Dalla pagina del Gruppo, seleziona ⋮ accanto al Nome dell'Utente che desideri modificare o eliminare dal Gruppo. + +**📝 Edit** ti porterà alla schermata Edit Member, dove puoi modificare il Ruolo di questo utente (da Reader, Maintainer o Owner a una scelta diversa). + +**🗑️ Delete** rimuove completamente l'appartenenza dell'Utente. Non rimuoverà alcun contributo o modifica che l'Utente ha apportato al Prodotto o Tipo di prodotto. + +![image](images/Create_a_User_Group_for_shared_permissions_6.png) + +## Gestire le Autorizzazioni di un Gruppo + +Le Autorizzazioni del Gruppo vengono gestite dalla singola pagina del Gruppo, che puoi selezionare dall'elenco nella pagina **Users \> Groups**. Fai clic sul Nome del gruppo evidenziato per accedere alla pagina del Gruppo che desideri modificare. + +Nota che solo i Superuser possono modificare le autorizzazioni di un Gruppo (Prodotto / Tipo di prodotto, o Configurazione). +​ +### **Aggiungere Ruoli di Prodotto o Ruoli di Tipo di prodotto per un Gruppo** + +Puoi registrare tutti i Ruoli di Prodotto o Ruoli di Tipo di prodotto che desideri in ciascun Gruppo. + +1. Dalla pagina del Gruppo, seleziona **\+ Add Product Types**, oppure \+ **Add Product** dall'intestazione pertinente (Product Type Groups o Product Groups). +​ + +![image](images/Create_a_User_Group_for_shared_permissions_7.png) + +2. Questo ti porterà a una pagina **Register New Products / Product Types**, dove puoi selezionare un Prodotto o Tipo di prodotto da aggiungere dal menu a discesa. + +![image](images/Create_a_User_Group_for_shared_permissions_8.png) + +3. Seleziona il Ruolo che vuoi che tutti i membri del Gruppo abbiano riguardo a questo particolare Prodotto o Tipo di prodotto. + +I Gruppi non possono essere assegnati a Prodotti o Tipi di prodotto senza un Ruolo. Se non sei sicuro di quale Ruolo vuoi che un Gruppo abbia, Reader è una buona opzione 'predefinita'. Questo manterrà sicuro lo stato del tuo Prodotto finché non prendi la decisione finale sul Ruolo del Gruppo. + +### **Assegnare Autorizzazioni di configurazione a un Gruppo** + +Se vuoi che i Membri del tuo Gruppo accedano alle funzioni di Configurazione e controllino determinati aspetti di DefectDojo, puoi assegnare queste responsabilità dalla pagina del Gruppo. + +Assegna i ruoli View, Add, Edit o Delete dal menu nell'angolo in basso a destra. Selezionare un'Autorizzazione di configurazione darà immediatamente al Gruppo l'accesso a questa particolare funzione. + +![image](images/Create_a_User_Group_for_shared_permissions_9.png) diff --git a/docs/content/admin/user_management/create_user_group.pt-br.md b/docs/content/admin/user_management/create_user_group.pt-br.md new file mode 100644 index 0000000000..f5f5366929 --- /dev/null +++ b/docs/content/admin/user_management/create_user_group.pt-br.md @@ -0,0 +1,139 @@ +--- +title: 'Compartilhar permissões: Grupos de Usuários' +description: Compartilhe e mantenha permissões para vários usuários no DefectDojo + Pro +weight: 3 +audience: pro +aliases: +- /pt-br/en/customize_dojo/user_management/create_user_group +--- + +> **Recurso do DefectDojo Pro.** Os Grupos de Usuários e o sistema de RBAC subjacente são parte do DefectDojo Pro. O DefectDojo open-source usa o modelo de [Usuários Autorizados](../os__authorized_users/) — consulte essa página para o controle de acesso do open-source, e as [notas de atualização da 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se você estiver migrando entre edições. + +Se você tem um número significativo de usuários no DefectDojo, pode ser interessante criar um ou mais **Grupos**, para definir as mesmas regras de Controle de Acesso Baseado em Papéis (RBAC) para vários usuários simultaneamente. Somente Superusuários podem criar Grupos de Usuários. + +Os Grupos podem funcionar de várias formas: + +* Definir um, ou vários Papéis diferentes em nível de Produto ou Tipo de Produto para todos os Membros do Grupo, permitindo controle específico sobre quais Produtos ou Tipos de Produto podem ser acessados e editados pelo Grupo. +* Definir um Papel Global para todos os Membros do Grupo, dando a eles visibilidade e acesso a todos os Produtos ou Tipos de Produto. +* Definir Permissões de Configuração para um Grupo, permitindo que alterem funcionalidades específicas do DefectDojo. + +Para mais informações sobre Papéis, consulte nosso artigo **Introdução aos Papéis**. + +## A página Todos os Grupos + +Na barra lateral, navegue até 👤**Usuários \> Grupos** para ver uma lista de todos os grupos de usuários ativos e inativos. + +![image](images/Create_a_User_Group_for_shared_permissions.png) +A partir daqui, você pode criar, excluir ou visualizar suas páginas de Grupo individuais. + +Para usuários do DefectDojo Pro, a página Todos os Grupos da interface Pro tem algumas opções adicionais. +* Você pode filtrar essa tabela por Nome do Grupo, Descrição, Endereço de E-mail, Papel Global, além do número total de Usuários, Tipos de Produto e Produtos associados ao Grupo. +* Você também pode ajustar as Permissões de um Grupo ou outras configurações clicando no botão "⋮" ao lado do Grupo que deseja editar. + +![image](images/all_groups_pro.png) + +## Visualizando um Grupo + +Visualizar um grupo exibe todas as informações do Grupo, como ID, nome, descrição, papel global etc. Os Membros do Grupo, Tipos de Produto e Produtos associados ao grupo também são exibidos. Além disso, as permissões de configuração vinculadas a um Grupo podem ser atualizadas diretamente na página "View Group". + +Para usuários do DefectDojo Pro, a Visualização de Grupo da interface Pro permite atribuir ajustes de Permissão de Configuração de uma forma um pouco diferente. + +![image](images/group_view_pro_ui.png) + +* Todas as permissões de configuração são exibidas em um menu suspenso agrupado em subcategorias. Se a seleção de permissões de configuração for diferente do valor atual, um botão "Update Configuration Permissions" é exibido. + +![image](images/groups_pro_configuration_permissions.png) + +* Depois que algumas permissões adicionais forem selecionadas, o usuário será solicitado a confirmar que deseja atualizar as permissões do grupo selecionado antes que a atualização seja feita. + +## Criar / Editar um Grupo de Usuários + +1. Navegue até a página 👤**Usuários \> Grupos** na barra lateral. Você verá uma lista de todos os Grupos de Usuários existentes, incluindo Nome, Descrição, Número de Usuários, Papel Global (se aplicável) e E-mail. +​ +![image](images/Create_a_User_Group_for_shared_permissions_2.png) + +2. Clique no **botão 🛠️** ao lado do título Todos os Grupos, e selecione **\+ Novo Grupo.** +​ +![image](images/Create_a_User_Group_for_shared_permissions_3.png) + + +3. Isso o levará a uma página onde você pode criar um novo Grupo. Defina o Nome deste Grupo, e adicione uma Descrição, se desejar. + +Você também pode selecionar um Papel Global que deseja aplicar a este Grupo, se desejar. Adicionar um Papel Global ao Grupo dará a todos os Membros do Grupo acesso a todos os dados do DefectDojo, junto com um nível limitado de acesso de edição, dependendo do Papel Global escolhido. Consulte nosso artigo **Introdução aos Papéis** para mais informações. + +A conta que cria um Grupo inicialmente terá o Papel de Owner do Grupo por padrão. + +### Definir um endereço de e-mail para receber relatórios + +O Resumo Semanal (Weekly Digest) é um relatório sobre todos os Produtos / Tipos de Produto atribuídos ao Grupo. Para que um Resumo Semanal seja enviado, insira o endereço de e-mail de destino que deseja usar no formulário Criar / Editar Grupo. Os membros do Grupo continuarão recebendo notificações normalmente. + +### Visualizando uma página de Grupo + +Depois de criar um Grupo, você pode acessá-lo selecionando-o no menu listado em **Usuários \> Grupos.** + +A página do Grupo pode ser personalizada com uma **Descrição**.Ela apresenta uma lista de todos os **Membros do Grupo,** bem como os **Produtos, Tipos de Produto**, atribuídos, e o **Papel** associado a cada um deles**.** + +Você também pode ver as **Permissões de Configuração** do Grupo listadas aqui. + +## Gerenciar os Usuários de um Grupo + +A Associação ao Grupo é gerenciada a partir da página individual do Grupo, que você pode selecionar na lista da página **Usuários \> Grupos**. Clique no Nome do Grupo destacado para acessar a página do Grupo que deseja editar. + +Para visualizar ou editar a Associação de um Grupo, um Usuário deve ter as permissões de Configuração apropriadas habilitadas, além de ser Membro do Grupo (ou ter status de Superusuário). + +### **Adicionar um Usuário a um Grupo** + +Os Grupos de Usuários podem ter quantos Usuários você desejar. Todos os Usuários em um Grupo receberão o Papel associado em cada Produto ou Tipo de Produto listado, mas os Usuários também podem ter Papéis Individuais que substituem o papel do Grupo. + +1. Na página do Grupo, selecione **\+ Add Users** no botão **☰** na borda do título **Members**. +​ +![image](images/Create_a_User_Group_for_shared_permissions_4.png) + +2. Isso o levará à tela **Add Some Group Members**. Abra o menu suspenso de Usuários e marque cada usuário que deseja adicionar ao Grupo. +​ +![image](images/Create_a_User_Group_for_shared_permissions_5.png) + +3. Selecione o Papel de Grupo que deseja atribuir a esses Usuários. Isso determina a capacidade deles de configurar o Grupo. + +Observe que adicionar um membro a um Grupo não dará a ele, por padrão, acesso à sua própria página de Grupo. Essa é uma Permissão de Configuração separada que deve ser habilitada primeiro. + +### **Editar ou Excluir um Membro de um Grupo de Usuários** + +1. Na página do Grupo, selecione o ⋮ ao lado do Nome do Usuário que deseja Editar ou Excluir do Grupo. + +**📝 Edit** o levará à tela de Edição de Membro, onde você pode alterar o Papel desse usuário (de Reader, Maintainer ou Owner para outra opção). + +**🗑️ Delete** remove completamente a Associação de um Usuário. Isso não removerá nenhuma contribuição ou alteração que o Usuário tenha feito no Produto ou Tipo de Produto. + +![image](images/Create_a_User_Group_for_shared_permissions_6.png) + +## Gerenciar as Permissões de um Grupo + +As Permissões de Grupo são gerenciadas a partir da página individual do Grupo, que você pode selecionar na lista da página **Usuários \> Grupos**. Clique no Nome do Grupo destacado para acessar a página do Grupo que deseja editar. + +Observe que somente Superusuários podem editar as permissões de um Grupo (Produto / Tipo de Produto, ou Configuração). +​ +### **Adicionar Papéis de Produto ou Papéis de Tipo de Produto para um Grupo** + +Você pode registrar quantos Papéis de Produto ou Papéis de Tipo de Produto desejar em cada Grupo. + +1. Na página do Grupo, selecione **\+ Add Product Types**, ou \+ **Add Product** no título correspondente (Grupos de Tipo de Produto ou Grupos de Produto). +​ +![image](images/Create_a_User_Group_for_shared_permissions_7.png) + +2. Isso o levará a uma página **Register New Products / Product Types**, onde você pode selecionar um Produto ou Tipo de Produto para adicionar no menu suspenso. + +![image](images/Create_a_User_Group_for_shared_permissions_8.png) + +3. Selecione o Papel que deseja que todos os membros do Grupo tenham em relação a esse Produto ou Tipo de Produto específico. + +Os Grupos não podem ser atribuídos a Produtos ou Tipos de Produto sem um Papel. Se você não tiver certeza de qual Papel deseja que um Grupo tenha, Reader é uma boa opção 'padrão'. Isso manterá o estado do seu Produto seguro até que você tome sua decisão final sobre o Papel do Grupo. + +### **Atribuir Permissões de Configuração a um Grupo** + +Se você quiser que os Membros do seu Grupo acessem funções de Configuração e controlem certos aspectos do DefectDojo, você pode atribuir essas responsabilidades a partir da página do Grupo. + +Atribua os papéis de Visualizar, Adicionar, Editar ou Excluir no menu no canto inferior direito. Marcar uma Permissão de Configuração dará imediatamente ao Grupo acesso a essa função específica. + +![image](images/Create_a_User_Group_for_shared_permissions_9.png) diff --git a/docs/content/admin/user_management/create_user_group.zh-hans.md b/docs/content/admin/user_management/create_user_group.zh-hans.md new file mode 100644 index 0000000000..e843f66e63 --- /dev/null +++ b/docs/content/admin/user_management/create_user_group.zh-hans.md @@ -0,0 +1,138 @@ +--- +title: 共享权限:用户组 +description: 在 DefectDojo Pro 中为多个用户共享和维护权限 +weight: 3 +audience: pro +aliases: +- /zh-hans/en/customize_dojo/user_management/create_user_group +--- + +> **DefectDojo Pro 功能。**用户组及其底层的 RBAC 系统是 DefectDojo Pro 的一部分。开源版 DefectDojo 使用[已授权用户](../os__authorized_users/)模型——有关开源版的访问控制,请参阅该页面;如果您正在版本之间迁移,请参阅 [3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。 + +如果您的 DefectDojo 用户数量较多,您可能希望创建一个或多个**组**,以便同时为多个用户设置相同的基于角色的访问控制(RBAC)规则。只有超级用户才能创建用户组。 + +组的用途多种多样: + +* 为所有组成员设置一个或多个不同的产品级或产品类型级角色,从而精确控制该组可以访问和编辑哪些产品或产品类型。 +* 为所有组成员设置一个全局角色,使他们能够查看并访问所有产品或产品类型。 +* 为组设置配置权限,使其能够更改 DefectDojo 中的特定功能。 + +有关角色的更多信息,请参阅我们的**角色简介**文章。 + +## “所有组”页面 + +在侧边栏中,导航至 👤**用户 > 组**,查看所有活动和非活动用户组的列表。 + +![image](images/Create_a_User_Group_for_shared_permissions.png) +在此处,您可以创建、删除或查看各个组的页面。 + +对于 DefectDojo Pro 用户,Pro 界面的“所有组”页面提供了一些附加选项。 +* 您可以按组名称、描述、电子邮件地址、全局角色,以及该组关联的用户、产品类型和产品的总数来筛选此表格。 +* 您也可以通过点击您想编辑的组旁边的“⋮”按钮,来调整该组的权限或其他设置。 + +![image](images/all_groups_pro.png) + +## 查看组 + +查看组会显示该组的全部信息,例如 ID、名称、描述、全局角色等。与该组关联的组成员、产品类型和产品也会一并显示。此外,与组绑定的配置权限也可以直接在“查看组”页面上更新。 + +对于 DefectDojo Pro 用户,Pro 界面的“组视图”允许您以稍有不同的方式来调整配置权限的指定。 + +![image](images/group_view_pro_ui.png) + +* 所有配置权限都显示在一个下拉菜单中,并按子类别分组。如果所选的配置权限与其当前值不同,系统会显示一个“更新配置权限”按钮。 + +![image](images/groups_pro_configuration_permissions.png) + +* 选择了一些额外权限后,系统会要求用户确认是否要更新所选组的权限,然后才会执行更新。 + +## 创建/编辑用户组 + +1. 在侧边栏中导航至 👤**用户 > 组**页面。您将看到所有现有用户组的列表,包括其名称、描述、用户数量、全局角色(如适用)和电子邮件地址。 +​ +![image](images/Create_a_User_Group_for_shared_permissions_2.png) + +2. 点击“所有组”标题旁边的**🛠️ 按钮**,然后选择**+ 新建组**。 +​ +![image](images/Create_a_User_Group_for_shared_permissions_3.png) + + +3. 这将带您进入一个可以创建新组的页面。为该组设置名称,并根据需要添加描述。 + +如果需要,您还可以为该组选择一个全局角色。为组添加全局角色将使所有组成员能够访问所有 DefectDojo 数据,并根据您所选择的全局角色获得一定程度的编辑权限。更多信息请参阅我们的**角色简介**文章。 + +最初创建组的账户默认将拥有该组的所有者角色。 + +### 设置接收报告的电子邮件地址 + +每周摘要是关于该组所分配的所有产品/产品类型的报告。若要发送每周摘要,请在创建/编辑组表单中输入您希望使用的目标电子邮件地址。 组成员仍将照常收到通知。 + +### 查看组页面 + +创建组后,您可以在**用户 > 组**下的菜单列表中选择该组以访问它。 + +组页面可以通过**描述**进行自定义。它列出了所有**组成员**,以及所分配的**产品、产品类型**,和与这些各项分别关联的**角色**。 + +您还可以在此处查看该组的**配置权限**列表。 + +## 管理组的用户 + +组成员身份可以在各个组的页面上进行管理,您可以从**用户 > 组**页面的列表中选择该组。点击高亮显示的组名称,即可进入您想要编辑的组页面。 + +要查看或编辑组的成员身份,用户必须已启用相应的配置权限,并且是该组的成员(或具备超级用户身份)。 + +### **将用户添加到组** + +用户组可以指定任意数量的用户。组中的所有用户都会获得所列每个产品或产品类型上的关联角色,但用户也可能拥有个人角色,这些角色会优先于组角色。 + +1. 在组页面上,点击**成员**标题边缘的**☰** 按钮,然后选择**+ 添加用户**。 +​ +![image](images/Create_a_User_Group_for_shared_permissions_4.png) + +2. 这将带您进入**添加组成员**界面。打开用户下拉菜单,然后勾选您想添加到该组的每个用户。 +​ +![image](images/Create_a_User_Group_for_shared_permissions_5.png) + +3. 选择您想指定给这些用户的组角色。这将决定他们配置该组的能力。 + +请注意,将成员添加到组默认不会使其能够访问自己所在的组页面。这是一项单独的配置权限,必须先启用。 + +### **编辑或删除用户组中的成员** + +1. 在组页面上,点击您想编辑或从组中删除的用户名称旁边的 ⋮。 + +**📝 编辑**将带您进入编辑成员界面,您可以在此更改该用户的角色(从读者、维护者或所有者更改为其他选项)。 + +**🗑️ 删除**将彻底移除用户的成员身份。这不会移除该用户对产品或产品类型所做的任何贡献或更改。 + +![image](images/Create_a_User_Group_for_shared_permissions_6.png) + +## 管理组的权限 + +组权限可以在各个组的页面上进行管理,您可以从**用户 > 组**页面的列表中选择该组。点击高亮显示的组名称,即可进入您想要编辑的组页面。 + +请注意,只有超级用户才能编辑组的权限(产品/产品类型权限,或配置权限)。 +​ +### **为组添加产品角色或产品类型角色** + +您可以在每个组中注册任意数量的产品角色或产品类型角色。 + +1. 在组页面上,从相关标题(产品类型组或产品组)中选择**+ 添加产品类型**,或 **+ 添加产品**。 +​ +![image](images/Create_a_User_Group_for_shared_permissions_7.png) + +2. 这将带您进入**注册新产品/产品类型**页面,您可以从下拉菜单中选择要添加的产品或产品类型。 + +![image](images/Create_a_User_Group_for_shared_permissions_8.png) + +3. 选择您希望所有组成员对该特定产品或产品类型所拥有的角色。 + +在没有角色的情况下,组无法被指定给产品或产品类型。如果您不确定希望某个组拥有哪个角色,读者是一个不错的“默认”选项。这样可以在您就组角色做出最终决定之前,保持产品状态的安全。 + +### **为组指定配置权限** + +如果您希望组中的成员能够访问配置功能,并控制 DefectDojo 的某些方面,您可以在组页面上指定这些职责。 + +在右下角的菜单中指定查看、添加、编辑或删除角色。勾选某项配置权限将立即使该组获得对该特定功能的访问权限。 + +![image](images/Create_a_User_Group_for_shared_permissions_9.png) diff --git a/docs/content/admin/user_management/pro_permissions_overhaul.it.md b/docs/content/admin/user_management/pro_permissions_overhaul.it.md new file mode 100644 index 0000000000..46cffb3394 --- /dev/null +++ b/docs/content/admin/user_management/pro_permissions_overhaul.it.md @@ -0,0 +1,54 @@ +--- +title: Impostare le autorizzazioni in Pro +description: Revisione, funzionalità Pro +weight: 3 +audience: pro +aliases: +- /it/en/customize_dojo/user_management/pro_permissions_overhaul +--- + +## Introduzione ai tipi di autorizzazione + +I singoli utenti dispongono di quattro diversi tipi di autorizzazione che possono essere loro assegnati: + +* Gli utenti possono essere assegnati come **Membri di Prodotti o Tipi di prodotto**. Questo consente loro di visualizzare e interagire con i Tipi di dati (Tipi di prodotto, Prodotti, Engagement, Test e Riscontri) in DefectDojo, in base al ruolo che viene loro assegnato sullo specifico Prodotto. Gli utenti possono avere più appartenenze a Prodotti o Tipi di prodotto, con diversi livelli di accesso. +​ +* Gli utenti possono anche avere assegnate **Autorizzazioni di configurazione**, che consentono loro di accedere alle pagine di configurazione di DefectDojo. Le Autorizzazioni di configurazione non sono correlate a Prodotti o Tipi di prodotto. +​ +* Agli utenti possono essere assegnati **Ruoli globali**, che forniscono loro un livello di accesso standardizzato a tutti i Prodotti e Tipi di prodotto. +​ +* Gli utenti possono essere configurati come **Superuser**: ruoli di livello amministratore che conferiscono loro il controllo e l'accesso a tutti i dati e la configurazione di DefectDojo. + +Puoi anche creare Gruppi se desideri assegnare l'Appartenenza a Prodotti, Autorizzazioni di configurazione o Ruoli globali a un gruppo di utenti contemporaneamente. Se hai un numero elevato di utenti in DefectDojo, ad esempio un team di test dedicato a un determinato Prodotto, i Gruppi possono essere una funzionalità più utile. + +## Superuser \& Ruoli globali + +Parte della configurazione del controllo degli accessi basato sui ruoli (RBAC) potrebbe richiedere la creazione di Superuser aggiuntivi, o di utenti con Ruoli globali. + +* I Superuser (Admin) non hanno limitazioni nel sistema. Possono modificare tutte le impostazioni, gestire gli utenti e avere accesso in lettura / scrittura a tutti i dati. Possono anche modificare le regole di accesso per tutti gli utenti in DefectDojo. I Superuser ricevono inoltre le notifiche per tutti i problemi e gli avvisi di sistema. +* Gli utenti con Ruoli globali possono visualizzare e interagire con qualsiasi Tipo di dati (Tipi di prodotto, Prodotti, Engagement, Test e Riscontri) in DefectDojo, in base al Ruolo loro assegnato. Per maggiori informazioni su ciascun Ruolo e sui privilegi associati, consulta il nostro articolo Introduzione ai Ruoli. +* Gli utenti possono anche avere Autorizzazioni di configurazione specifiche assegnate, che consentono loro di accedere a determinate pagine di configurazione di DefectDojo. Gli utenti non hanno alcuna Autorizzazione di configurazione per impostazione predefinita. + +Per impostazione predefinita, il primo account creato su una nuova istanza di DefectDojo avrà le autorizzazioni Superuser. Quell'utente potrà modificare le autorizzazioni per tutti gli utenti DefectDojo successivi. Solo un Superuser esistente può aggiungere un altro superuser, o assegnare un Ruolo globale a un utente. + +Le autorizzazioni in DefectDojo Pro sono state semplificate, per rendere più facile assegnare l'accesso agli oggetti. Questa funzionalità è accessibile tramite l'[interfaccia Pro](/get_started/about/ui_pro_vs_os/). + +### Aprire la finestra delle autorizzazioni + +![image](images/pro_permissions.png) + +Quando visualizzi un Tipo di prodotto o un Prodotto, puoi aprire la finestra delle Autorizzazioni per impostare rapidamente le autorizzazioni. Questo menu si trova in una Tabella facendo clic sui puntini orizzontali **"⋮"**. Se stai visualizzando la pagina di un singolo **Prodotto** o **Tipo di prodotto**, questo menu si trova sotto l'icona a forma di ingranaggio blu '⚙️'. + +## Impostare le autorizzazioni tramite la finestra delle autorizzazioni + +![image](images/pro_permissions_2.png) + +1. Nella parte superiore di questa finestra, puoi scegliere di gestire le autorizzazioni per un singolo utente o per un [gruppo di utenti](../create_user_group). +2. Qui puoi selezionare un utente o un gruppo da aggiungere al Prodotto, e selezionare il [Ruolo](../about_perms_and_roles) che vuoi che quell'utente abbia. +3. Nella tabella inferiore, puoi vedere un elenco di tutti gli utenti o gruppi che hanno accesso a questo oggetto. Puoi anche assegnare rapidamente un nuovo ruolo a uno di questi utenti o gruppi dal menu a discesa. + +## Impostare le autorizzazioni di configurazione tramite la vista Utente + +Le autorizzazioni di configurazione di un utente possono ora essere impostate con un approccio più intuitivo. Dalla vista Users, tutte le autorizzazioni di configurazione vengono visualizzate in un menu a discesa, quindi raggruppate per tipo di autorizzazione. Se la selezione delle autorizzazioni di configurazione è diversa dal valore attuale, viene visualizzato un pulsante "Update Configuration Permissions". Quando viene cliccato, all'utente verrà chiesto di confermare di voler aggiornare le autorizzazioni per il gruppo selezionato prima che l'aggiornamento venga effettuato. + +![image](images/pro_user_view.png) diff --git a/docs/content/admin/user_management/pro_permissions_overhaul.pt-br.md b/docs/content/admin/user_management/pro_permissions_overhaul.pt-br.md new file mode 100644 index 0000000000..164a805604 --- /dev/null +++ b/docs/content/admin/user_management/pro_permissions_overhaul.pt-br.md @@ -0,0 +1,54 @@ +--- +title: Definir Permissões no Pro +description: Reformulação, recurso do Pro +weight: 3 +audience: pro +aliases: +- /pt-br/en/customize_dojo/user_management/pro_permissions_overhaul +--- + +## Introdução aos Tipos de Permissão + +Usuários individuais têm quatro tipos diferentes de permissão que podem ser atribuídos a eles: + +* Os usuários podem ser designados como **Membros de Produtos ou Tipos de Produto**. Isso permite que eles visualizem e interajam com Tipos de Dados (Tipos de Produto, Produtos, Engajamentos, Testes e Achados) no DefectDojo, dependendo do papel atribuído a eles no Produto específico. Os usuários podem ter múltiplas associações a Produtos ou Tipos de Produto, com diferentes níveis de acesso. +​ +* Os usuários também podem ter **Permissões de Configuração** atribuídas, que permitem acessar páginas de configuração no DefectDojo. As Permissões de Configuração não estão relacionadas a Produtos ou Tipos de Produto. +​ +* Os usuários podem receber **Papéis Globais**, que dão a eles um nível padronizado de acesso a todos os Produtos e Tipos de Produto. +​ +* Os usuários podem ser configurados como **Superusuários**: papéis de nível administrativo que dão a eles controle e acesso a todos os dados e configurações do DefectDojo. + +Você também pode criar Grupos se quiser atribuir Associação a Produto, Permissões de Configuração ou Papéis Globais a um grupo de usuários ao mesmo tempo. Se você tiver um grande número de usuários no DefectDojo, como uma equipe de testes dedicada a um Produto específico, os Grupos podem ser um recurso mais útil. + +## Superusuários e Papéis Globais + +Parte da sua configuração de Controle de Acesso Baseado em Papéis (RBAC) pode exigir a criação de Superusuários adicionais, ou de usuários com Papéis Globais. + +* Os Superusuários (Admins) não têm limitações no sistema. Eles podem alterar todas as configurações, gerenciar usuários e têm acesso de leitura/gravação a todos os dados. Eles também podem alterar as regras de acesso para todos os usuários do DefectDojo. Os Superusuários também recebem notificações de todos os problemas e alertas do sistema. +* Usuários com Papéis Globais podem visualizar e interagir com qualquer Tipo de Dados (Tipos de Produto, Produtos, Engajamentos, Testes e Achados) no DefectDojo, dependendo do Papel atribuído a eles. Para mais informações sobre cada Papel e os privilégios associados, consulte nosso artigo Introdução aos Papéis. +* Os usuários também podem ter Permissões de Configuração específicas atribuídas, permitindo que acessem determinadas páginas de configuração do DefectDojo. Por padrão, os usuários não têm nenhuma Permissão de Configuração. + +Por padrão, a primeira conta criada em uma nova instância do DefectDojo terá permissões de Superusuário. Esse usuário poderá editar as permissões de todos os usuários do DefectDojo criados posteriormente. Somente um Superusuário existente pode adicionar outro superusuário, ou adicionar um Papel Global a um usuário. + +As permissões no DefectDojo Pro foram simplificadas, para facilitar a atribuição de acesso a objetos. Esse recurso pode ser acessado através da [interface Pro](/get_started/about/ui_pro_vs_os/). + +### Abrindo a janela de Permissões + +![image](images/pro_permissions.png) + +Ao visualizar um Tipo de Produto ou Produto, você pode abrir a janela de Permissões para definir permissões rapidamente. Esse menu pode ser encontrado em uma Tabela clicando nos pontos horizontais **"⋮"**. Se estiver em uma página individual de **Produto** ou **Tipo de Produto**, esse menu pode ser encontrado sob a engrenagem azul '⚙️'. + +## Definindo Permissões através da janela de permissões + +![image](images/pro_permissions_2.png) + +1. Na parte superior dessa janela, você pode optar por gerenciar permissões para um usuário individual ou para um [grupo de usuários](../create_user_group). +2. Aqui, você pode selecionar um usuário ou grupo para adicionar ao Produto, e selecionar o [Papel](../about_perms_and_roles) que deseja que esse usuário tenha. +3. Na tabela inferior, você pode ver uma lista de todos os usuários ou grupos que têm acesso a esse objeto. Você também pode atribuir rapidamente um novo papel a um desses usuários ou grupos a partir do menu suspenso. + +## Definindo Permissões de Configuração através da visualização do Usuário + +As permissões de configuração de um usuário agora podem ser definidas de uma forma mais amigável. Na Visualização de Usuários, todas as permissões de configuração são exibidas em um menu suspenso, agrupadas por tipo de permissão. Se a seleção de permissões de configuração for diferente do valor atual, um botão "Update Configuration Permissions" é exibido. Ao clicar nele, o usuário será solicitado a confirmar que deseja atualizar as permissões do grupo selecionado antes que a atualização seja feita. + +![image](images/pro_user_view.png) diff --git a/docs/content/admin/user_management/pro_permissions_overhaul.zh-hans.md b/docs/content/admin/user_management/pro_permissions_overhaul.zh-hans.md new file mode 100644 index 0000000000..57c3412c0d --- /dev/null +++ b/docs/content/admin/user_management/pro_permissions_overhaul.zh-hans.md @@ -0,0 +1,54 @@ +--- +title: 在 Pro 中设置权限 +description: 权限功能改版,Pro 功能 +weight: 3 +audience: pro +aliases: +- /zh-hans/en/customize_dojo/user_management/pro_permissions_overhaul +--- + +## 权限类型简介 + +每个用户可以被指定四种不同类型的权限: + +* 用户可以被指定为**产品或产品类型的成员**。这使其能够根据在特定产品上被指定的角色,查看并操作 DefectDojo 中的数据类型(产品类型、产品、测试活动、测试和发现项)。用户可以拥有多个产品或产品类型的成员身份,并具有不同级别的访问权限。 +​ +* 用户还可以被指定**配置权限**,使其能够访问 DefectDojo 中的配置页面。配置权限与产品或产品类型无关。 +​ +* 用户可以被指定**全局角色**,使其对所有产品和产品类型拥有统一级别的访问权限。 +​ +* 用户可以被设置为**超级用户**:这是一种管理员级别的角色,使其对所有 DefectDojo 数据和配置拥有控制权和访问权。 + +如果您希望同时为一组用户指定产品成员身份、配置权限或全局角色,也可以创建组。如果您在 DefectDojo 中有大量用户,例如某个产品的专职测试团队,组功能可能会更有帮助。 + +## 超级用户与全局角色 + +您的基于角色的访问控制(RBAC)配置中,可能有一部分需要您创建额外的超级用户,或拥有全局角色的用户。 + +* 超级用户(管理员)在系统中不受任何限制。他们可以更改所有设置、管理用户,并对所有数据拥有读/写访问权限。他们还可以更改 DefectDojo 中所有用户的访问规则。超级用户还会收到所有系统问题和警报的通知。 +* 拥有全局角色的用户可以根据其被指定的角色,查看并操作 DefectDojo 中的任何数据类型(产品类型、产品、测试活动、测试和发现项)。有关每个角色及其相关权限的更多信息,请参阅我们的角色简介文章。 +* 用户还可以被指定特定的配置权限,使其能够访问 DefectDojo 的某些配置页面。用户默认没有任何配置权限。 + +默认情况下,在新的 DefectDojo 实例上创建的第一个账户将拥有超级用户权限。该用户将能够编辑此后所有 DefectDojo 用户的权限。只有现有的超级用户才能添加另一个超级用户,或为某用户添加全局角色。 + +DefectDojo Pro 中的权限已得到简化,使指定对象访问权限变得更加容易。此功能可以通过 [Pro 界面](/get_started/about/ui_pro_vs_os/)访问。 + +### 打开权限窗口 + +![image](images/pro_permissions.png) + +在查看产品类型或产品时,您可以打开权限窗口来快速设置权限。在表格中,可以通过点击横向圆点**“⋮”**找到此菜单。如果是在查看某个具体的**产品**或**产品类型**页面,则该菜单可以在蓝色齿轮“⚙️”下找到。 + +## 通过权限窗口设置权限 + +![image](images/pro_permissions_2.png) + +1. 在此窗口顶部,您可以选择为单个用户或某个[用户组](../create_user_group)管理权限。 +2. 在此处,您可以选择要添加到该产品的用户或组,并选择您希望该用户拥有的[角色](../about_perms_and_roles)。 +3. 在下方的表格中,您可以看到有权访问该对象的所有用户或组的列表。您也可以通过下拉菜单,快速为其中某个用户或组指定新角色。 + +## 通过用户视图设置配置权限 + +现在,用户的配置权限可以通过更加友好的方式进行设置。在用户视图中,所有配置权限都显示在一个下拉菜单中,并按权限类型分组。如果所选的配置权限与其当前值不同,系统会显示一个“更新配置权限”按钮。点击该按钮后,系统会要求用户确认是否要更新所选组的权限,然后才会执行更新。 + +![image](images/pro_user_view.png) diff --git a/docs/content/admin/user_management/set_user_permissions.it.md b/docs/content/admin/user_management/set_user_permissions.it.md new file mode 100644 index 0000000000..7b678908cc --- /dev/null +++ b/docs/content/admin/user_management/set_user_permissions.it.md @@ -0,0 +1,155 @@ +--- +title: Impostare le autorizzazioni di un utente +description: Come assegnare ruoli e autorizzazioni a un utente, oltre allo stato di + superuser +weight: 2 +audience: pro +aliases: +- /it/en/customize_dojo/user_management/set_user_permissions +--- + +> **Funzionalità di DefectDojo Pro.** Il sistema RBAC Membri / Gruppi / Ruoli globali descritto in questa pagina fa parte di DefectDojo Pro. La versione open source di DefectDojo utilizza il modello [Utenti autorizzati](../os__authorized_users/) — consulta quella pagina per il controllo degli accessi nella versione open source, e le [note di aggiornamento alla 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se stai passando da un'edizione all'altra. + +## Introduzione ai tipi di autorizzazione + +I singoli utenti dispongono di quattro diversi tipi di autorizzazione che possono essere loro assegnati: + +* Gli utenti possono essere assegnati come **Membri di Prodotti o Tipi di prodotto**. Questo consente loro di visualizzare e interagire con i tipi di dati (Tipi di prodotto, Prodotti, Engagement, Test e Riscontri) in DefectDojo in base al ruolo che viene loro assegnato sullo specifico Prodotto. Gli utenti possono avere più appartenenze a Prodotti o Tipi di prodotto, con diversi livelli di accesso. +​ +* Gli utenti possono anche avere **Autorizzazioni di configurazione** assegnate, che consentono loro di accedere alle pagine di configurazione di DefectDojo. Le Autorizzazioni di configurazione non sono legate a Prodotti o Tipi di prodotto. +​ +* Agli utenti possono essere assegnati **Ruoli globali**, che conferiscono loro un livello di accesso standardizzato a tutti i Prodotti e Tipi di prodotto. +​ +* Gli utenti possono essere impostati come **Superuser**: ruoli di livello amministratore che conferiscono loro il controllo e l'accesso a tutti i dati e la configurazione di DefectDojo. + +È inoltre possibile creare Gruppi se si desidera assegnare contemporaneamente l'appartenenza a un Prodotto, le Autorizzazioni di configurazione o i Ruoli globali a un gruppo di utenti. Se in DefectDojo è presente un numero elevato di utenti, ad esempio un team di test dedicato a un determinato Prodotto, i Gruppi possono essere una funzionalità più utile. + +## Superuser e Ruoli globali + +Parte della configurazione del controllo degli accessi basato sui ruoli (RBAC) potrebbe richiedere la creazione di Superuser aggiuntivi, o di utenti con Ruoli globali. + +* I Superuser (Admin) non hanno limitazioni nel sistema. Possono modificare tutte le impostazioni, gestire gli utenti e avere accesso in lettura/scrittura a tutti i dati. Possono anche modificare le regole di accesso per tutti gli utenti di DefectDojo. I Superuser riceveranno inoltre notifiche per tutti i problemi e gli avvisi di sistema. +* Gli utenti con Ruoli globali possono visualizzare e interagire con qualsiasi tipo di dati (Tipi di prodotto, Prodotti, Engagement, Test e Riscontri) in DefectDojo in base al Ruolo loro assegnato. Per maggiori informazioni su ciascun Ruolo e sui relativi privilegi, consulta il nostro articolo di Introduzione ai Ruoli. +* Agli utenti possono anche essere assegnate specifiche Autorizzazioni di configurazione, che consentono loro di accedere a determinate pagine di configurazione di DefectDojo. Per impostazione predefinita, gli utenti non dispongono di alcuna Autorizzazione di configurazione. + +Per impostazione predefinita, il primo account creato su una nuova istanza di DefectDojo avrà i permessi di Superuser. Questo utente potrà modificare le autorizzazioni di tutti gli utenti di DefectDojo successivi. Solo un Superuser esistente può aggiungere un altro superuser, o assegnare un Ruolo globale a un utente. + +### Assegnare lo stato di Superuser o Ruolo globale a un utente esistente + +1. Vai alla pagina 👤 Users \> Users nella barra laterale. Vedrai un elenco di tutti gli account registrati su DefectDojo, insieme allo stato Attivo di ciascun account, ai Ruoli globali e ad altri dati utente rilevanti. +​ +![image](images/Set_a_User's_Permissions.png) +​ +2. Fai clic sul nome dell'account a cui vuoi concedere i privilegi di Superuser. Questo ti porterà alla sua pagina Utente. +​ +3. Dalla sezione Informazioni predefinite della pagina Utente, apri il menu ☰ e seleziona Modifica. +​ +![image](images/Set_a_User's_Permissions_2.png) + +4. Dalla pagina Modifica utente: +​ +Per lo stato di Superuser, seleziona la casella ☑️ Stato Superuser, presente nelle Informazioni predefinite dell'utente. +​ +Per assegnare un Ruolo globale, selezionane uno dal menu a discesa Ruolo globale in fondo alla pagina. +​ +![image](images/Set_a_User's_Permissions_3.png) +​ +5. Fai clic su Invia per confermare le modifiche. + +## Appartenenza a Prodotto e Tipo di prodotto + +Per impostazione predefinita, qualsiasi nuovo account creato su DefectDojo non avrà l'autorizzazione a visualizzare alcun dato a livello di Prodotto. Sarà necessario assegnare loro l'appartenenza a ciascun Prodotto che desiderano visualizzare e con cui vogliono interagire. + +* L'appartenenza a Prodotto e Tipo di prodotto può essere configurata solo da **Superuser, Maintainer o Owner**. +* I **Maintainer e Owner** possono configurare l'appartenenza solo sui Prodotti/Tipi di prodotto a cui sono già assegnati. +* I **Maintainer e Owner globali** possono configurare l'appartenenza su qualsiasi Prodotto o Tipo di prodotto, così come i **Superuser**. + +Gli utenti possono avere contemporaneamente due tipi di appartenenza a livello di **Prodotto**: + +* Il Ruolo conferito dalla loro appartenenza al Tipo di prodotto sottostante, se applicabile +* Il loro Ruolo specifico per il Prodotto, se esistente. + +Se un utente è già stato aggiunto come membro di un Tipo di prodotto e non necessita di un ulteriore livello di autorizzazioni su uno specifico Prodotto, non è necessario aggiungerlo come Membro del Prodotto. + +### Aggiungere un nuovo Membro + +1. Vai al Prodotto o Tipo di prodotto a cui vuoi assegnare un utente. Puoi selezionare il Prodotto dall'elenco in **Products \> All Products**. + +![image](images/Set_a_User's_Permissions_4.png) + +2. Individua l'intestazione **Members**, fai clic sul menu **☰** e seleziona **\+ Add Users**. +3. Questo ti porterà a una pagina in cui puoi **registrare nuovi Membri**. Seleziona un Utente dal menu a discesa Users. +4. Seleziona il Ruolo che vuoi assegnare a quell'Utente su questo Prodotto o Tipo di prodotto: **API Importer, Reader, Writer, Maintainer** o **Owner.** +​ +![image](images/Set_a_User's_Permissions_5.png) + +Gli utenti non possono essere assegnati come Membri su un Prodotto o Tipo di prodotto senza avere anche un Ruolo. Se non sei sicuro di quale Ruolo assegnare a un nuovo utente, **Reader** è una buona opzione 'predefinita'. Questo manterrà sicuro lo stato del tuo Prodotto finché non prenderai la decisione finale sul suo Ruolo. + +### Modificare o eliminare un Membro + +Ai Membri può essere modificato il Ruolo all'interno di un Prodotto o Tipo di prodotto. + +Nella pagina **Product** o **Product Type**, vai all'intestazione **Members** e fai clic sul pulsante **⋮** accanto all'Utente che vuoi Modificare o Eliminare. + +![image](images/Set_a_User's_Permissions_6.png) + +📝 **Edit** ti porterà alla schermata **Edit Member**, dove puoi cambiare il **Ruolo** di questo utente (da **API Importer, Reader, Writer, Maintainer** o **Owner** a una scelta diversa). + +🗑️ **Delete** rimuove completamente l'appartenenza di un Utente. Non rimuoverà alcun contributo o modifica apportata dall'Utente al Prodotto o Tipo di prodotto. + +* Se non riesci a Modificare o Eliminare l'appartenenza di un utente (il pulsante **⋮** non è visibile), è perché tale appartenenza gli è conferita a livello di **Product Type**. +* Un utente può avere due livelli di appartenenza all'interno di un Prodotto: uno assegnato a livello di **Product Type** e un altro assegnato a livello di **Product**. + +#### Aggiungere un ruolo Prodotto aggiuntivo a un utente con un ruolo Tipo di prodotto correlato + +Se un Utente ha un Ruolo a livello di Tipo di prodotto, gli verrà assegnata anche l'appartenenza con questo Ruolo a ogni Prodotto sottostante all'interno della categoria. Tuttavia, se vuoi che questo Utente abbia un Ruolo speciale su uno specifico Prodotto all'interno di quel Tipo di prodotto, puoi assegnargli un Ruolo aggiuntivo a livello di Prodotto. + +1. Dalla pagina del Prodotto, vai all'intestazione **Members**, fai clic sul menu **☰** e seleziona **\+ Add Users** (come se stessi aggiungendo un nuovo Utente al Prodotto). +2. Seleziona il nome dell'Utente dal menu a discesa e seleziona il Ruolo Prodotto che vuoi assegnare a quell'Utente. + +Un Ruolo Prodotto avrà la precedenza sul Ruolo standard del Tipo di prodotto o sul Ruolo globale di un utente. Ad esempio, se un Utente ha un Ruolo Tipo di prodotto di **Reader**, ma è anche assegnato come **Owner** su un Prodotto annidato in quel Tipo di prodotto, avrà ulteriori permessi da **Owner** aggiunti solo per quel Prodotto. + +Tuttavia, questo non funziona al contrario. Se un Utente ha un Ruolo Tipo di prodotto o un Ruolo globale di **Owner**, assegnargli un ruolo **Reader** su un particolare Prodotto non gli toglierà i permessi da **Owner**. **I Ruoli non possono togliere le autorizzazioni concesse a un Utente da altri Ruoli, possono solo aggiungerne di ulteriori.** + +## Autorizzazioni di configurazione + +Molte finestre di configurazione ed endpoint API possono essere abilitati per utenti o gruppi di utenti, indipendentemente dal loro stato di superuser. Queste Autorizzazioni di configurazione consentono agli utenti normali di accedere e contribuire a parti di DefectDojo al di fuori della loro normale assegnazione di Prodotto o Ruolo Prodotto. + +Le Autorizzazioni di configurazione non sono legate a uno specifico Prodotto o Tipo di prodotto: gli utenti possono avere Autorizzazioni di configurazione assegnate senza bisogno di altri stati o dell'appartenenza a Prodotto/Tipo di prodotto. +​ +### Elenco delle Autorizzazioni di configurazione + +* **Credential Manager:** Accesso alla pagina ⚙️Configuration \> Credential Manager +* **Development Environments:** Gestione dell'elenco Engagements \> Environments +* **Finding Templates:** Accesso alla pagina Findings \> Finding Templates +* **Groups**: Accesso alla pagina 👤Users \> Groups +* **Jira Instances:** Accesso alla pagina ⚙️Configuration \> JIRA +* **Language Types**: Accesso all'endpoint API [Language Types](/automation/api/languages/) +* **Login Banner**: Modifica della pagina ⚙️Configuration \> Login Banner +* **Announcements**: Accesso a ⚙️Configuration \> Announcements +* **Note Types:** Accesso alla pagina ⚙️Configuration \> Note Types +* **Product Types:** n/d +* **Questionnaires**: Accesso alla pagina Questionnaires \> All Questionnaires +* **Questions**: Accesso alla pagina Questionnaires \> Questions +* **Regulations**: Accesso alla pagina ⚙️Configuration \> Regulations +* **SLA Configuration:** Accesso alla pagina ⚙️Configuration \> SLA Configuration +* **Test Types:** Aggiunta o modifica di un Test Type (in Engagements \> Test Types) +* **Tool Configuration:** Accesso alla pagina **⚙️Configuration \> Tool Types** +* **Tool Types:** Accesso alla pagina ⚙️Configuration \> Tool Types +* **Users:** Accesso alla pagina 👤Users \> Users + +### Aggiungere Autorizzazioni di configurazione a un utente + +**Solo i Superuser possono aggiungere Autorizzazioni di configurazione a un utente**. + +1. Vai alla pagina 👤 Users \> Users nella barra laterale. Vedrai un elenco di tutti gli account registrati su DefectDojo, insieme allo stato Attivo di ciascun account, ai Ruoli globali e ad altri dati utente rilevanti. +​ +![image](images/Set_a_User's_Permissions_7.png) + +2. Fai clic sul nome dell'account che desideri modificare. +​ +3. Vai all'elenco delle Autorizzazioni di configurazione. Si trova sul lato destro della pagina Utente. +​ +4. Seleziona le Autorizzazioni di configurazione utente che desideri aggiungere. +​ +Per una descrizione dettagliata delle Autorizzazioni di configurazione utente, consulta il nostro [Elenco delle autorizzazioni](../user_permission_chart/). diff --git a/docs/content/admin/user_management/set_user_permissions.pt-br.md b/docs/content/admin/user_management/set_user_permissions.pt-br.md new file mode 100644 index 0000000000..b0b935600f --- /dev/null +++ b/docs/content/admin/user_management/set_user_permissions.pt-br.md @@ -0,0 +1,154 @@ +--- +title: Definir as permissões de um Usuário +description: Como conceder Funções e Permissões a um usuário, além do status de superuser +weight: 2 +audience: pro +aliases: +- /pt-br/en/customize_dojo/user_management/set_user_permissions +--- + +> **Recurso do DefectDojo Pro.** O sistema de RBAC de Membros / Grupos / Funções Globais descrito nesta página faz parte do DefectDojo Pro. O DefectDojo de código aberto usa o modelo [Usuários Autorizados](../os__authorized_users/) — consulte essa página para o controle de acesso no código aberto, e as [notas de atualização da versão 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) caso você esteja migrando entre edições. + +## Introdução aos Tipos de Permissão + +Usuários individuais podem receber quatro tipos diferentes de permissão: + +* Os usuários podem ser atribuídos como **Membros de Produtos ou Tipos de Produto**. Isso permite que eles visualizem e interajam com Tipos de Dados (Tipos de Produto, Produtos, Engajamentos, Testes e Achados) no DefectDojo, de acordo com o papel atribuído a eles no Produto específico. Os usuários podem ter várias associações de Produto ou Tipo de Produto, com diferentes níveis de acesso. +​ +* Os usuários também podem ter **Permissões de Configuração** atribuídas, que permitem acessar páginas de configuração no DefectDojo. As Permissões de Configuração não estão relacionadas a Produtos ou Tipos de Produto. +​ +* Os usuários podem receber **Funções Globais**, que concedem um nível padronizado de acesso a todos os Produtos e Tipos de Produto. +​ +* Os usuários podem ser configurados como **Superusers**: papéis em nível de administrador que concedem controle e acesso a todos os dados e configurações do DefectDojo. + +Você também pode criar Grupos caso deseje atribuir Associação de Produto, Permissões de Configuração ou Funções Globais a um grupo de usuários ao mesmo tempo. Se você tiver um grande número de usuários no DefectDojo, como uma equipe de testes dedicada a um Produto específico, os Grupos podem ser um recurso mais útil. + +## Superusers \& Funções Globais + +Parte da configuração do seu Controle de Acesso Baseado em Função (RBAC) pode exigir que você crie Superusers adicionais, ou usuários com Funções Globais. + +* Os Superusers (Admins) não têm limitações no sistema. Eles podem alterar todas as configurações, gerenciar usuários e têm acesso de leitura/gravação a todos os dados. Também podem alterar as regras de acesso de todos os usuários no DefectDojo. Os Superusers também recebem notificações de todos os problemas e alertas do sistema. +* Os usuários com Funções Globais podem visualizar e interagir com qualquer Tipo de Dado (Tipos de Produto, Produtos, Engajamentos, Testes e Achados) no DefectDojo, de acordo com a Função atribuída a eles. Para mais informações sobre cada Função e os privilégios associados, consulte nosso artigo Introdução às Funções. +* Os usuários também podem ter Permissões de Configuração específicas atribuídas, permitindo o acesso a determinadas páginas de configuração do DefectDojo. Por padrão, os usuários não têm nenhuma Permissão de Configuração. + +Por padrão, a primeira conta criada em uma nova instância do DefectDojo terá permissões de Superuser. Esse usuário poderá editar as permissões de todos os usuários do DefectDojo criados posteriormente. Somente um Superuser existente pode adicionar outro superuser, ou atribuir uma Função Global a um usuário. + +### Adicionar status de Superuser ou Função Global a um usuário existente + +1. Navegue até a página 👤 Usuários \> Usuários na barra lateral. Você verá uma lista de todas as contas registradas no DefectDojo, junto com o status Ativo de cada conta, as Funções Globais e outros dados relevantes do Usuário. +​ +![image](images/Set_a_User's_Permissions.png) +​ +2. Clique no nome da conta à qual deseja conceder privilégios de Superuser. Isso o levará à Página do Usuário. +​ +3. Na seção Informações Padrão da Página do Usuário, abra o menu ☰ e selecione Editar. +​ +![image](images/Set_a_User's_Permissions_2.png) + +4. Na página Editar Usuário: +​ +Para o Status de Superuser, marque a caixa ☑️ Status de Superuser, localizada nas Informações Padrão do usuário. +​ +Para atribuir uma Função Global, selecione uma no menu suspenso Função Global, na parte inferior da página. +​ +![image](images/Set_a_User's_Permissions_3.png) +​ +5. Clique em Enviar para aceitar essas alterações. + +## Associação de Produto \& Tipo de Produto + +Por padrão, qualquer nova conta criada no DefectDojo não terá permissão para visualizar nenhum dado em nível de Produto. Será necessário atribuir a ela associação a cada Produto que deve visualizar e com o qual deve interagir. + +* A associação de Produto \& Tipo de Produto só pode ser configurada por **Superusers, Maintainers ou Owners**. +* **Maintainers \& Owners** só podem configurar associação em Produtos / Tipos de Produto aos quais já estão atribuídos. +* **Global Maintainers \& Owners** podem configurar associação em qualquer Produto ou Tipo de Produto, assim como os **Superusers**. + +Os usuários podem ter dois tipos de associação simultaneamente no nível de **Produto**: + +* A Função conferida pela sua associação subjacente de Tipo de Produto, se aplicável +* Sua Função específica de Produto, se existir. + +Se um usuário já foi adicionado como membro de Tipo de Produto e não precisa de um nível adicional de permissões em um Produto específico, não há necessidade de adicioná-lo como Membro do Produto. + +### Adicionando um novo Membro + +1. Navegue até o Produto ou Tipo de Produto ao qual deseja atribuir um usuário. Você pode selecionar o Produto na lista em **Produtos \> Todos os Produtos**. + +![image](images/Set_a_User's_Permissions_4.png) + +2. Localize o cabeçalho **Membros**, clique no menu **☰** e selecione **\+ Adicionar Usuários**. +3. Isso o levará a uma página onde você pode **Registrar novos Membros**. Selecione um Usuário no menu suspenso Usuários. +4. Selecione a Função que deseja que esse Usuário tenha nesse Produto ou Tipo de Produto: **API Importer, Reader, Writer, Maintainer** ou **Owner.** +​ +![image](images/Set_a_User's_Permissions_5.png) + +Os usuários não podem ser atribuídos como Membros de um Produto ou Tipo de Produto sem também ter uma Função. Se você não tiver certeza de qual Função deseja atribuir a um novo usuário, **Reader** é uma boa opção "padrão". Isso manterá o estado do seu Produto seguro até que você tome sua decisão final sobre a Função dele. + +### Editar ou Excluir um Membro + +Os Membros podem ter sua Função alterada dentro de um Produto ou Tipo de Produto. + +Na página do **Produto** ou **Tipo de Produto**, navegue até o cabeçalho **Membros** e clique no botão **⋮** ao lado do Usuário que deseja Editar ou Excluir. + +![image](images/Set_a_User's_Permissions_6.png) + +📝 **Editar** o levará à tela **Editar Membro**, onde você pode alterar a **Função** desse usuário (de **API Importer, Reader, Writer, Maintainer** ou **Owner** para uma opção diferente). + +🗑️ **Excluir** remove completamente a Associação de um Usuário. Isso não removerá quaisquer contribuições ou alterações que o Usuário tenha feito no Produto ou Tipo de Produto. + +* Se você não conseguir Editar ou Excluir a Associação de um usuário (o **⋮** não está visível), é porque essa Associação foi conferida em nível de **Tipo de Produto**. +* Um usuário pode ter dois níveis de associação dentro de um Produto \- um atribuído no nível de **Tipo de Produto** e outro no nível de **Produto**. + +#### Adicionar uma Função de Produto adicional a um usuário com uma Função de Tipo de Produto relacionada + +Se um Usuário tiver uma Função em nível de Tipo de Produto, ele também receberá Associação com essa Função em todos os Produtos subjacentes dentro da categoria. No entanto, se você quiser que esse Usuário tenha uma Função especial em um Produto específico dentro desse Tipo de Produto, você pode atribuir a ele uma Função adicional em nível de Produto. + +1. Na página do Produto, navegue até o cabeçalho **Membros**, clique no menu **☰** e selecione **\+ Adicionar Usuários** (como se estivesse adicionando um novo Usuário ao Produto). +2. Selecione o nome do Usuário no menu suspenso e selecione a Função de Produto que deseja atribuir a esse Usuário. + +Uma Função de Produto substitui a Função padrão de Tipo de Produto ou a Função Global de um usuário. Por exemplo, se um Usuário tiver uma Função de Tipo de Produto **Reader**, mas também estiver atribuído como **Owner** em um Produto vinculado a esse Tipo de Produto, ele terá permissões adicionais de **Owner** somente para esse Produto. + +No entanto, isso não funciona ao contrário. Se um Usuário tiver uma Função de Tipo de Produto ou Função Global **Owner**, atribuir a ele uma função **Reader** em um Produto específico não removerá suas permissões de **Owner**. **As Funções não podem remover permissões concedidas a um Usuário por outras Funções, elas só podem adicionar permissões extras.** + +## Permissões de Configuração + +Muitas caixas de diálogo de configuração e endpoints de API podem ser habilitados para usuários ou grupos de usuários, independentemente do status de superuser deles. Essas Permissões de Configuração permitem que usuários comuns acessem e contribuam para partes do DefectDojo fora de sua atribuição padrão de Produto ou Função de Produto. + +As Permissões de Configuração não estão relacionadas a um Produto ou Tipo de Produto específico \- os usuários podem ter Permissões de Configuração atribuídas sem a necessidade de outros status ou de Associação a Produto / Tipo de Produto. +​ +### Lista de Permissões de Configuração + +* **Gerenciador de Credenciais:** Acesso à página ⚙️Configuração \> Gerenciador de Credenciais +* **Ambientes de Desenvolvimento:** Gerenciar a lista Engajamentos \> Ambientes +* **Modelos de Achado:** Acesso à página Achados \> Modelos de Achado +* **Grupos**: Acessar a página 👤Usuários \> Grupos +* **Instâncias do Jira:** Acessar a página ⚙️Configuração \> JIRA +* **Tipos de Idioma**: Acessar o endpoint de API [Tipos de Idioma](/automation/api/languages/) +* **Banner de Login**: Editar a página ⚙️Configuração \> Banner de Login +* **Anúncios**: Acessar ⚙️Configuração \> Anúncios +* **Tipos de Nota:** Acesso à página ⚙️Configuração \> Tipos de Nota +* **Tipos de Produto:** n/a +* **Questionários**: Acesso à página Questionários \> Todos os Questionários +* **Perguntas**: Acesso à página Questionários \> Perguntas +* **Regulamentações**: Acesso à página ⚙️Configuração \> Regulamentações +* **Configuração de SLA:** Acesso à página ⚙️Configuração \> Configuração de SLA +* **Tipos de Teste:** Adicionar ou editar um Tipo de Teste (em Engajamentos \> Tipos de Teste) +* **Configuração de Ferramenta:** Acesso à página **⚙️Configuração \> Tipos de Ferramenta** +* **Tipos de Ferramenta:** Acesso à página ⚙️Configuração \> Tipos de Ferramenta +* **Usuários:** Acesso à página 👤Usuários \> Usuários + +### Adicionar Permissões de Configuração a um Usuário + +**Somente Superusers podem adicionar Permissões de Configuração a um Usuário**. + +1. Navegue até a página 👤 Usuários \> Usuários na barra lateral. Você verá uma lista de todas as contas registradas no DefectDojo, junto com o status Ativo de cada conta, as Funções Globais e outros dados relevantes do Usuário. +​ +![image](images/Set_a_User's_Permissions_7.png) + +2. Clique no nome da conta que deseja editar. +​ +3. Navegue até a Lista de Permissões de Configuração. Ela está localizada no lado direito da Página do Usuário. +​ +4. Selecione as Permissões de Configuração de Usuário que deseja adicionar. +​ +Para uma descrição detalhada das Permissões de Configuração de Usuário, consulte nosso [Quadro de Permissões](../user_permission_chart/). diff --git a/docs/content/admin/user_management/set_user_permissions.zh-hans.md b/docs/content/admin/user_management/set_user_permissions.zh-hans.md new file mode 100644 index 0000000000..979c673121 --- /dev/null +++ b/docs/content/admin/user_management/set_user_permissions.zh-hans.md @@ -0,0 +1,154 @@ +--- +title: 设置用户的权限 +description: 如何为用户授予角色和权限,以及超级用户身份 +weight: 2 +audience: pro +aliases: +- /zh-hans/en/customize_dojo/user_management/set_user_permissions +--- + +> **DefectDojo Pro 功能。** 本页介绍的成员/组/全局角色 RBAC 系统是 DefectDojo Pro 的一部分。开源版 DefectDojo 使用[已授权用户](../os__authorized_users/)模型——有关开源版访问控制,请参阅该页面;如果您正在版本之间迁移,请参阅[3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。 + +## 权限类型简介 + +各个用户可以被分配以下四种不同类型的权限： + +* 用户可以被分配为**产品或产品类型的成员**。这使他们能够根据在特定产品上被分配的角色,查看并操作 DefectDojo 中的数据类型(产品类型、产品、测试活动、测试和发现项)。用户可以同时拥有多个产品或产品类型的成员身份,并具有不同级别的访问权限。 +​ +* 用户还可以被分配**配置权限**,从而能够访问 DefectDojo 中的配置页面。配置权限与产品或产品类型无关。 +​ +* 用户可以被分配**全局角色**,从而对所有产品和产品类型拥有统一级别的访问权限。 +​ +* 用户可以被设置为**超级用户**：这是一种管理员级别的角色,可让其控制并访问所有 DefectDojo 数据和配置。 + +如果您想同时为一组用户分配产品成员身份、配置权限或全局角色,也可以创建组。如果您的 DefectDojo 中用户数量较多(例如某个产品的专职测试团队),使用组功能可能会更方便。 + +## 超级用户与全局角色 + +您的基于角色的访问控制(RBAC)配置中,可能有一部分需要您创建额外的超级用户,或拥有全局角色的用户。 + +* 超级用户(管理员)在系统中不受任何限制。他们可以更改所有设置、管理用户,并对所有数据拥有读/写权限。他们还可以更改 DefectDojo 中所有用户的访问规则。超级用户还会收到所有系统问题和警报的通知。 +* 拥有全局角色的用户可以根据其被分配的角色,查看并操作 DefectDojo 中的任意数据类型(产品类型、产品、测试活动、测试和发现项)。有关每种角色及其相关权限的更多信息,请参阅我们的角色简介文章。 +* 用户还可以被分配特定的配置权限,从而能够访问某些 DefectDojo 配置页面。用户默认没有任何配置权限。 + +默认情况下,新 DefectDojo 实例上创建的第一个账户将拥有超级用户权限。该用户将能够编辑此后所有 DefectDojo 用户的权限。只有现有的超级用户才能添加另一个超级用户,或为用户添加全局角色。 + +### 为现有用户添加超级用户或全局角色状态 + +1. 在侧边栏导航到 👤 用户 > 用户页面。您将看到 DefectDojo 上所有已注册账户的列表,以及每个账户的活动状态、全局角色和其他相关用户数据。 +​ +![image](images/Set_a_User's_Permissions.png) +​ +2. 点击您希望授予超级用户权限的账户名称。这将带您进入该用户的用户页面。 +​ +3. 在其用户页面的默认信息部分,打开 ☰ 菜单并选择编辑。 +​ +![image](images/Set_a_User's_Permissions_2.png) + +4. 在编辑用户页面： +​ +若要设置超级用户状态,请勾选位于用户默认信息中的 ☑️ 超级用户状态复选框。 +​ +若要分配全局角色,请从页面底部的全局角色下拉菜单中选择一个。 +​ +![image](images/Set_a_User's_Permissions_3.png) +​ +5. 点击提交以接受这些更改。 + +## 产品与产品类型成员身份 + +默认情况下,在 DefectDojo 上创建的任何新账户都无权查看任何产品级别的数据。需要为其分配他们想要查看和操作的每个产品的成员身份。 + +* 产品与产品类型的成员身份只能由**超级用户、维护者或所有者**配置。 +* **维护者与所有者**只能在他们已被分配的产品/产品类型上配置成员身份。 +* **全局维护者与所有者**可以在任何产品或产品类型上配置成员身份,**超级用户**同样可以。 + +用户在**产品**级别可以同时拥有两种成员身份： + +* 由其所属产品类型成员身份所赋予的角色(如适用) +* 其特定于该产品的角色(如果存在)。 + +如果某用户已被添加为产品类型成员,并且不需要在特定产品上拥有额外级别的权限,则无需再将其添加为产品成员。 + +### 添加新成员 + +1. 导航到您想为其分配用户的产品或产品类型。您可以从**产品 > 所有产品**下的列表中选择该产品。 + +![image](images/Set_a_User's_Permissions_4.png) + +2. 找到**成员**标题,点击 **☰** 菜单,然后选择**+ 添加用户**。 +3. 这将带您进入一个可以**注册新成员**的页面。从下拉的用户菜单中选择一个用户。 +4. 选择您希望该用户在此产品或产品类型上拥有的角色：**API 导入者、读取者、编写者、维护者**或**所有者**。 +​ +![image](images/Set_a_User's_Permissions_5.png) + +用户不能在没有角色的情况下被分配为产品或产品类型的成员。如果您不确定要为新用户分配哪个角色,**读取者**是一个不错的“默认”选项。这样可以在您对其角色做出最终决定之前,保持产品状态的安全。 + +### 编辑或删除成员 + +成员的角色可以在产品或产品类型内进行更改。 + +在**产品**或**产品类型**页面中,导航到**成员**标题,点击您想要编辑或删除的用户旁边的 **⋮** 按钮。 + +![image](images/Set_a_User's_Permissions_6.png) + +📝 **编辑**将带您进入**编辑成员**界面,您可以在此更改该用户的**角色**(从 **API 导入者、读取者、编写者、维护者**或**所有者**更改为其他选项)。 + +🗑️ **删除**将完全移除某用户的成员身份。这不会移除该用户对该产品或产品类型所做的任何贡献或更改。 + +* 如果您无法编辑或删除某用户的成员身份(**⋮** 不可见),这是因为该成员身份是在**产品类型**级别授予的。 +* 一个用户在某个产品中可以拥有两个级别的成员身份——一个在**产品类型**级别分配,另一个在**产品**级别分配。 + +#### 为拥有相关产品类型角色的用户添加额外的产品角色 + +如果某用户拥有产品类型级别的角色,他们也会被分配该角色作为该类别下每个产品的成员身份。但是,如果您希望该用户在该产品类型下的某个特定产品上拥有特殊角色,可以在产品级别为其额外授予一个角色。 + +1. 在产品页面中,导航到**成员**标题,点击 **☰** 菜单,然后选择**+ 添加用户**(就像您要为该产品添加新用户一样)。 +2. 从下拉菜单中选择该用户的姓名,并选择您希望为该用户分配的产品角色。 + +产品角色会取代用户的标准产品类型角色或全局角色。例如,如果某用户的产品类型角色为**读取者**,但同时在该产品类型下的某个产品上被指定为**所有者**,那么他们将仅在该产品上获得额外的**所有者**权限。 + +但反过来则不成立。如果某用户的产品类型角色或全局角色为**所有者**,在某个特定产品上为其分配**读取者**角色并不会剥夺其**所有者**权限。**角色不能剥夺用户由其他角色获得的权限,只能增加额外的权限。** + +## 配置权限 + +许多配置对话框和 API 端点可以针对用户或用户组启用,而不论其是否为超级用户。这些配置权限允许普通用户访问并参与 DefectDojo 中超出其标准产品或产品角色分配范围之外的部分。 + +配置权限与特定的产品或产品类型无关——用户无需具备其他状态或产品/产品类型成员身份,即可被分配配置权限。 +​ +### 配置权限列表 + +* **凭据管理器：** 访问 ⚙️配置 > 凭据管理器页面 +* **开发环境：** 管理测试活动 > 环境列表 +* **发现项模板：** 访问发现项 > 发现项模板页面 +* **组**：访问 👤用户 > 组页面 +* **Jira 实例：** 访问 ⚙️配置 > JIRA 页面 +* **语言类型**：访问[语言类型](/automation/api/languages/) API 端点 +* **登录横幅**：编辑 ⚙️配置 > 登录横幅页面 +* **公告**：访问 ⚙️配置 > 公告 +* **备注类型：** 访问 ⚙️配置 > 备注类型页面 +* **产品类型：** 不适用 +* **问卷**：访问问卷 > 所有问卷页面 +* **问题**：访问问卷 > 问题页面 +* **法规**：访问 ⚙️配置 > 法规页面 +* **SLA 配置：** 访问 ⚙️配置 > SLA 配置页面 +* **测试类型：** 添加或编辑测试类型(在测试活动 > 测试类型下) +* **工具配置：** 访问**⚙️配置 > 工具类型**页面 +* **工具类型：** 访问 ⚙️配置 > 工具类型页面 +* **用户：** 访问 👤用户 > 用户页面 + +### 为用户添加配置权限 + +**只有超级用户才能为用户添加配置权限**。 + +1. 在侧边栏导航到 👤 用户 > 用户页面。您将看到 DefectDojo 上所有已注册账户的列表,以及每个账户的活动状态、全局角色和其他相关用户数据。 +​ +![image](images/Set_a_User's_Permissions_7.png) + +2. 点击您想要编辑的账户名称。 +​ +3. 导航到配置权限列表。该列表位于用户页面的右侧。 +​ +4. 选择您想要添加的用户配置权限。 +​ +有关用户配置权限的详细说明,请参阅我们的[权限图表](../user_permission_chart/)。 diff --git a/docs/content/admin/user_management/user_permission_chart.it.md b/docs/content/admin/user_management/user_permission_chart.it.md new file mode 100644 index 0000000000..4f8403dc54 --- /dev/null +++ b/docs/content/admin/user_management/user_permission_chart.it.md @@ -0,0 +1,99 @@ +--- +title: Tabelle delle autorizzazioni per azione +description: Tutte le autorizzazioni utente di DefectDojo Pro in dettaglio +weight: 4 +audience: pro +aliases: +- /it/en/customize_dojo/user_management/user_permission_chart +--- + +> **Funzionalità di DefectDojo Pro.** Il sistema RBAC Membri / Gruppi / Ruoli globali descritto in questa pagina fa parte di DefectDojo Pro. La versione open source di DefectDojo utilizza il modello [Utenti autorizzati](../os__authorized_users/) — consulta quella pagina per il controllo degli accessi nella versione open source, e le [note di aggiornamento alla 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) se stai passando da un'edizione all'altra. + +## Tabella delle autorizzazioni per ruolo + +Questa tabella elenca tutte le autorizzazioni relative a un Prodotto o Tipo di prodotto, oltre a quali autorizzazioni sono disponibili per ciascun ruolo. + +I cinque ruoli seguenti sono i **ruoli integrati** di DefectDojo Pro. Sono preset bloccati: le loro autorizzazioni sono identiche su ogni istanza e non possono essere modificate. Se hai creato i tuoi ruoli personalizzati, questa tabella descrive i ruoli integrati da cui sono stati clonati, non i ruoli stessi. Per il catalogo completo delle autorizzazioni che è possibile assegnare a un ruolo, consulta [Ruoli RBAC personalizzati](../pro__custom_rbac_roles/#choosing-permissions). + +| **Section** | **Permission** | Reader | Writer | Maintainer | Owner | API Importer | +| --- | --- | --- | --- | --- | --- | --- | +| **Accesso a Prodotto/Tipo di prodotto** | Visualizzare il Prodotto o Tipo di prodotto assegnato ¹ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | Visualizzare Prodotti, Engagement, Test, Riscontri ed Endpoint annidati | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | Aggiungere nuovi Prodotti (all'interno del Tipo di prodotto assegnato) ² | | | ☑️ | ☑️ | | +| | Eliminare i Prodotti o Tipi di prodotto assegnati | | | | ☑️ | | +| **Appartenenza a Prodotto/Tipo di prodotto** | Aggiungere Utenti come Membri (escluso il Ruolo Owner) | | | ☑️ | ☑️ | | +| | Modificare i Ruoli dei membri (escluso il Ruolo Owner) | | | ☑️ | ☑️ | | +| | Modificare i Ruoli dei membri (incluso il Ruolo Owner) | | | | ☑️ | | +| | Rimuoversi dall'appartenenza a Prodotto/Tipo di prodotto | ☑️ | ☑️ | ☑️ | ☑️ | | +| | Assegnare un Ruolo Owner a un altro Utente | | | | ☑️ | | +| | Modificare un'appartenenza a Prodotto/Tipo di prodotto associata all'interno di un Gruppo³ | | | | ☑️ | | +| | Eliminare un'appartenenza a Prodotto/Tipo di prodotto associata all'interno di un Gruppo³ | | | | | | +| **Engagement** (all'interno di un Prodotto) | Aggiungere, modificare Engagement | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Visualizzare le Accettazioni del rischio ⁴ | | ☑️ | ☑️ | ☑️ | | +| | Aggiungere, modificare Accettazioni del rischio | | ☑️ | ☑️ | ☑️ | | +| | Eliminare Engagement | | | ☑️ | ☑️ | | +| **Test** (all'interno di un Prodotto) | Aggiungere Test | | ☑️ | ☑️ | ☑️ | | +| | Modificare Test | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Eliminare Test | | | ☑️ | ☑️ | | +| **Riscontri** (all'interno di un Prodotto) | Aggiungere Riscontri | | ☑️ | ☑️ | ☑️ | | +| | Modificare Riscontri | | ☑️ | ☑️ | ☑️ | | +| | Importare, reimportare risultati della scansione | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Eliminare Riscontri | | | ☑️ | ☑️ | | +| | Aggiungere, modificare, eliminare Gruppi di riscontri | | ☑️ | ☑️ | ☑️ | | +| **Altri dati** (all'interno di un Prodotto) | Aggiungere, modificare Endpoint | | ☑️ | ☑️ | ☑️ | | +| | Eliminare Endpoint | | | ☑️ | ☑️ | | +| | Modificare Benchmark | | ☑️ | ☑️ | ☑️ | | +| | Eliminare Benchmark | | | ☑️ | ☑️ | | +| | Visualizzare la cronologia delle Note | ☑️ | ☑️ | ☑️ | ☑️ | | +| | Aggiungere, modificare, eliminare le proprie Note | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | Modificare le Note di altri utenti | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Eliminare le Note di altri utenti | | | ☑️ | ☑️ | | + +1. Un utente a cui sono assegnate autorizzazioni solo a livello di Prodotto non può visualizzare il Tipo di prodotto in cui è contenuto. +2. Quando un nuovo Prodotto viene aggiunto sotto un Tipo di prodotto, tutti gli Utenti a livello di Tipo di prodotto verranno aggiunti come Membri del nuovo Prodotto con il loro Ruolo a livello di Tipo di prodotto. +3. L'utente che desidera apportare modifiche a un Gruppo deve anche avere le **Autorizzazioni di configurazione** **Edit Group**, e un **Ruolo di configurazione del Gruppo** di **Maintainer o Owner** nel Gruppo che desidera modificare. +4. La visibilità delle Accettazioni del rischio è regolata da un'autorizzazione minima distinta rispetto alla visibilità dei Riscontri: un Reader sul Prodotto può visualizzare i Riscontri sottostanti ma **non può** visualizzare le Accettazioni del rischio a cui questi Riscontri appartengono. Per dettagli sulle autorizzazioni delle Accettazioni del rischio, sul comportamento della data di scadenza e sui flussi di ripristino, consulta [Accettazioni del rischio (Pro)](/triage_findings/findings_workflows/pro__risk_acceptance/#risk-acceptance-permissions-and-visibility). + +## Tabella delle autorizzazioni di configurazione + +Ogni Autorizzazione di configurazione si riferisce a una particolare funzione del software e ha un insieme associato di azioni che un utente può eseguire relative a questa funzione. + +La maggior parte delle Autorizzazioni di configurazione consente agli utenti di accedere a determinate pagine dell'interfaccia. + +| **Configuration Permission** | **View ☑️** | **Add ☑️** | **Edit ☑️** | **Delete ☑️** | +| --- | --- | --- | --- | --- | +| Credential Manager | Accesso alla pagina **⚙️Configuration \> Credential Manager** | Aggiunta di nuove voci al Credential Manager | Modifica delle voci del Credential Manager | Eliminazione delle voci del Credential Manager | +| Development Environments | n/d | Aggiunta di nuovi Development Environments all'elenco 🗓️**Engagements \> Environments** | Modifica dei Development Environments nell'elenco 🗓️**Engagements \> Environments** | Eliminazione dei Development Environments dall'elenco **🗓️Engagements \> Environments** | +| Finding Templates¹ | Accesso alla pagina **Findings \> Finding Templates** | Aggiunta di un Finding Template | Modifica di un Finding Template | Eliminazione di un Finding Template | +| Groups | Accesso alla pagina **👤Users \> Groups** | Aggiunta di un nuovo Gruppo di utenti | Solo Superuser | Solo Superuser | +| Jira Instances | Accesso alla pagina **⚙️Configuration \> JIRA** | Aggiunta di una nuova configurazione JIRA | Modifica di una configurazione JIRA esistente | Eliminazione di una configurazione JIRA | +| Language Types | | | | | +| Login Banner | n/d | n/d | Modifica del login banner, disponibile in **⚙️Configuration \> Login Banner** | n/d | +| Announcements | n/d | n/d | Configurazione degli Announcements, disponibile in **⚙️Configuration \> Announcements** | n/d | +| Note Types | Accesso alla pagina ⚙️Configuration \> Note Types | Aggiunta di un Note Type | Modifica di un Note Type | Eliminazione di un Note Type | +| Prioritization Engines | Accesso alla pagina di configurazione del Prioritization Engine | Aggiunta di un nuovo Prioritization Engine | Modifica di un Prioritization Engine esistente | Eliminazione di un Prioritization Engine | +| Product Types | n/d | Aggiunta di un nuovo Product Type (in Products \> Product Type) | n/d | n/d | +| Questionnaires | Accesso alla pagina **Questionnaires \> All Questionnaires** | Aggiunta di un nuovo Questionnaire | Modifica di un Questionnaire esistente | Eliminazione di un Questionnaire | +| Questions | Accesso alla pagina **Questionnaires \> Questions** | Aggiunta di una nuova Question | Modifica di una Question esistente | n/d | +| Regulations | n/d | Aggiunta di una Regulation alla pagina **⚙️Configuration \> Regulations** | Modifica di una Regulation esistente | Eliminazione di una Regulation | +| Scheduling Service Schedule | Accesso alla pagina **Scheduling** | Solo Superuser | Modifica di uno Schedule esistente (cambio trigger, abilitazione/disabilitazione) | Eliminazione di uno Schedule | +| SLA Configuration | Accesso alla pagina **⚙️Configuration \> SLA Configuration** | Aggiunta di una nuova SLA Configuration | Modifica di una SLA Configuration esistente | Eliminazione di una SLA Configuration | +| Test Types | n/d | Aggiunta di un nuovo Test Type (in **Engagements \> Test Types**) | Modifica di un Test Type esistente | n/d | +| Tool Configuration | Accesso alla pagina **⚙️Configuration \> Tool Configuration** | Aggiunta di una nuova Tool Configuration | Modifica di una Tool Configuration esistente | Eliminazione di una Tool Configuration | +| Tool Types | Accesso alla pagina **⚙️Configuration \> Tool Types** | Aggiunta di un nuovo Tool Type | Modifica di un Tool Type esistente | Eliminazione di un Tool Type | +| Users | Accesso alla pagina **👤Users \> Users** | Aggiunta di un nuovo Utente a DefectDojo | Modifica di un Utente esistente | Eliminazione di un Utente | + +1. L'accesso alla pagina Finding Templates richiede anche il Ruolo globale **Writer, Maintainer** o **Owner** per questo utente. + +## Autorizzazioni di configurazione del Gruppo + +| Configuration Permission | **Reader** | **Maintainer** | **Owner** | +| --- | --- | --- | --- | +| Visualizzare il Gruppo | ☑️ | ☑️ | ☑️ | +| Rimuoversi dal Gruppo | ☑️ | ☑️ | ☑️ | +| Modificare il ruolo di un Membro in un Gruppo | | ☑️ | ☑️ | +| Modificare o eliminare un'appartenenza a Prodotto o Tipo di prodotto da un Gruppo¹ | | ☑️ | ☑️ | +| Cambiare il ruolo di un Membro del Gruppo a Owner | | | ☑️ | +| Eliminare il Gruppo | | | ☑️ | + +1. Questo richiede inoltre che l'Utente abbia almeno un Ruolo Maintainer sul Prodotto o Tipo di prodotto che desidera modificare. diff --git a/docs/content/admin/user_management/user_permission_chart.pt-br.md b/docs/content/admin/user_management/user_permission_chart.pt-br.md new file mode 100644 index 0000000000..0ca95d5952 --- /dev/null +++ b/docs/content/admin/user_management/user_permission_chart.pt-br.md @@ -0,0 +1,99 @@ +--- +title: Quadros de permissões de ações +description: Todas as permissões de usuário do DefectDojo Pro em detalhes +weight: 4 +audience: pro +aliases: +- /pt-br/en/customize_dojo/user_management/user_permission_chart +--- + +> **Recurso do DefectDojo Pro.** O sistema de RBAC de Membros / Grupos / Funções Globais descrito nesta página faz parte do DefectDojo Pro. O DefectDojo de código aberto usa o modelo [Usuários Autorizados](../os__authorized_users/) — consulte essa página para o controle de acesso no código aberto, e as [notas de atualização da versão 3.0](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization) caso você esteja migrando entre edições. + +## Quadro de Permissões por Função + +Este quadro tem como objetivo listar todas as permissões relacionadas a um Produto ou Tipo de Produto, bem como quais permissões estão disponíveis para cada função. + +As cinco funções abaixo são as **funções integradas** do DefectDojo Pro. Elas são predefinições bloqueadas: suas permissões são as mesmas em todas as instâncias e não podem ser alteradas. Se você criou suas próprias funções, este quadro descreve as funções integradas a partir das quais elas foram clonadas, e não as funções personalizadas em si. Para o catálogo completo de permissões que podem ser atribuídas a uma função, consulte [Funções RBAC Personalizadas](../pro__custom_rbac_roles/#choosing-permissions). + +| **Seção** | **Permissão** | Reader | Writer | Maintainer | Owner | API Importer | +| --- | --- | --- | --- | --- | --- | --- | +| **Acesso a Produto / Tipo de Produto** | Visualizar o Produto ou Tipo de Produto atribuído ¹ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | Visualizar Produtos, Engajamentos, Testes, Achados e Endpoints aninhados | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | Adicionar novos Produtos (dentro do Tipo de Produto atribuído) ² | | | ☑️ | ☑️ | | +| | Excluir Produtos ou Tipos de Produto atribuídos | | | | ☑️ | | +| **Associação a Produto / Tipo de Produto** | Adicionar Usuários como Membros (exceto a Função Owner) | | | ☑️ | ☑️ | | +| | Editar Funções de membros (exceto a Função Owner) | | | ☑️ | ☑️ | | +| | Editar Funções de membros (incluindo a Função Owner) | | | | ☑️ | | +| | Remover a si mesmo da associação a Produto / Tipo de Produto | ☑️ | ☑️ | ☑️ | ☑️ | | +| | Atribuir a Função Owner a outro Usuário | | | | ☑️ | | +| | Editar uma Associação a Produto/Tipo de Produto vinculada a um Grupo³ | | | | ☑️ | | +| | Excluir uma Associação a Produto/Tipo de Produto vinculada a um Grupo³ | | | | | | +| **Engajamentos** (Dentro de um Produto) | Adicionar, Editar Engajamentos | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Visualizar Aceitações de risco ⁴ | | ☑️ | ☑️ | ☑️ | | +| | Adicionar, Editar Aceitações de risco | | ☑️ | ☑️ | ☑️ | | +| | Excluir Engajamentos | | | ☑️ | ☑️ | | +| **Testes** (Dentro de um Produto) | Adicionar Testes | | ☑️ | ☑️ | ☑️ | | +| | Editar Testes | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Excluir Testes | | | ☑️ | ☑️ | | +| **Achados** (Dentro de um Produto) | Adicionar Achados | | ☑️ | ☑️ | ☑️ | | +| | Editar Achados | | ☑️ | ☑️ | ☑️ | | +| | Importar, Reimportar Resultados de Scan | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Excluir Achados | | | ☑️ | ☑️ | | +| | Adicionar, Editar, Excluir Grupos de Achados | | ☑️ | ☑️ | ☑️ | | +| **Outros Dados** (Dentro de um Produto) | Adicionar, Editar Endpoints | | ☑️ | ☑️ | ☑️ | | +| | Excluir Endpoints | | | ☑️ | ☑️ | | +| | Editar Benchmarks | | ☑️ | ☑️ | ☑️ | | +| | Excluir Benchmarks | | | ☑️ | ☑️ | | +| | Visualizar Histórico de Notas | ☑️ | ☑️ | ☑️ | ☑️ | | +| | Adicionar, Editar, Excluir Notas próprias | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | Editar Notas de terceiros | | ☑️ | ☑️ | ☑️ | ☑️ | +| | Excluir Notas de terceiros | | | ☑️ | ☑️ | | + +1. Um usuário que recebe permissões apenas em nível de Produto não pode visualizar o Tipo de Produto no qual esse Produto está contido. +2. Quando um novo Produto é adicionado sob um Tipo de Produto, todos os Usuários em nível de Tipo de Produto serão adicionados como Membros do novo Produto com sua Função em nível de Tipo de Produto. +3. O usuário que deseja fazer alterações em um Grupo também precisa ter a **Permissão de Configuração** **Editar Grupo**, e uma **Função de Configuração de Grupo** de **Maintainer ou Owner** no Grupo que deseja editar. +4. A visibilidade de Aceitação de risco é controlada por uma permissão mínima distinta da visibilidade de Achados — um Reader no Produto pode visualizar os Achados subjacentes, mas **não pode** visualizar as Aceitações de risco às quais esses Achados pertencem. Para detalhes sobre permissões de Aceitação de risco, comportamento da data de expiração e fluxos de reinstauração, consulte [Aceitações de risco (Pro)](/triage_findings/findings_workflows/pro__risk_acceptance/#risk-acceptance-permissions-and-visibility). + +## Quadro de Permissões de Configuração + +Cada Permissão de Configuração se refere a uma função específica do software e tem um conjunto associado de ações que um usuário pode realizar relacionadas a essa função. + +A maioria das Permissões de Configuração dá aos usuários acesso a determinadas páginas na interface. + +| **Configuration Permission** | **View ☑️** | **Add ☑️** | **Edit ☑️** | **Delete ☑️** | +| --- | --- | --- | --- | --- | +| Gerenciador de Credenciais | Acessar a página **⚙️Configuração \> Gerenciador de Credenciais** | Adicionar novas entradas no Gerenciador de Credenciais | Editar entradas do Gerenciador de Credenciais | Excluir entradas do Gerenciador de Credenciais | +| Ambientes de Desenvolvimento | n/a | Adicionar novos Ambientes de Desenvolvimento à lista 🗓️**Engajamentos \> Ambientes** | Editar Ambientes de Desenvolvimento na lista 🗓️**Engajamentos \> Ambientes** | Excluir Ambientes de Desenvolvimento da lista **🗓️Engajamentos \> Ambientes** | +| Modelos de Achado¹ | Acessar a página **Achados \> Modelos de Achado** | Adicionar um Modelo de Achado | Editar um Modelo de Achado | Excluir um Modelo de Achado | +| Grupos | Acessar a página **👤Usuários \> Grupos** | Adicionar um novo Grupo de Usuários | Somente Superuser | Somente Superuser | +| Instâncias do Jira | Acessar a página **⚙️Configuração \> JIRA page** | Adicionar uma nova Configuração do JIRA | Editar uma Configuração do JIRA existente | Excluir uma Configuração do JIRA | +| Tipos de Idioma | | | | | +| Banner de Login | n/a | n/a | Editar o banner de login, localizado em **⚙️Configuração \> Banner de Login** | n/a | +| Anúncios | n/a | n/a | Configurar Anúncios, localizados em **⚙️Configuração \> Anúncios** | n/a | +| Tipos de Nota | Acesso à página ⚙️Configuração \> Tipos de Nota | Adicionar um Tipo de Nota | Editar um Tipo de Nota | Excluir um Tipo de Nota | +| Mecanismos de Priorização | Acessar a página de configuração do Mecanismo de Priorização | Adicionar um novo Mecanismo de Priorização | Editar um Mecanismo de Priorização existente | Excluir um Mecanismo de Priorização | +| Tipos de Produto | n/a | Adicionar um novo Tipo de Produto (em Produtos \> Tipo de Produto) | n/a | n/a | +| Questionários | Acessar a página **Questionários \> Todos os Questionários** | Adicionar um novo Questionário | Editar um Questionário existente | Excluir um Questionário | +| Perguntas | Acessar a página **Questionários \> Perguntas** | Adicionar uma nova Pergunta | Editar uma Pergunta existente | n/a | +| Regulamentações | n/a | Adicionar uma Regulamentação à página **⚙️Configuração \> Regulamentações** | Editar uma Regulamentação existente | Excluir uma Regulamentação | +| Agendamento do Serviço de Agendamento | Acessar a página **Agendamento** | Somente Superuser | Editar um Agendamento existente (alterar gatilho, ativar/desativar) | Excluir um Agendamento | +| Configuração de SLA | Acessar a página **⚙️Configuração \> Configuração de SLA** | Adicionar uma nova Configuração de SLA | Editar uma Configuração de SLA existente | Excluir uma Configuração de SLA | +| Tipos de Teste | n/a | Adicionar um novo Tipo de Teste (em **Engajamentos \> Tipos de Teste**) | Editar um Tipo de Teste existente | n/a | +| Configuração de Ferramenta | Acessar a página **⚙️Configuração \> Configuração de Ferramenta** | Adicionar uma nova Configuração de Ferramenta | Editar uma Configuração de Ferramenta existente | Excluir uma Configuração de Ferramenta | +| Tipos de Ferramenta | Acessar a página **⚙️Configuração \> Tipos de Ferramenta** | Adicionar um novo Tipo de Ferramenta | Editar um Tipo de Ferramenta existente | Excluir um Tipo de Ferramenta | +| Usuários | Acessar a página **👤Usuários \> Usuários** | Adicionar um novo Usuário ao DefectDojo | Editar um Usuário existente | Excluir um Usuário | + +1. O acesso à página de Modelos de Achado também requer a Função Global **Writer, Maintainer** ou **Owner** para esse usuário. + +## Permissões de Configuração de Grupo + +| Configuration Permission | **Reader** | **Maintainer** | **Owner** | +| --- | --- | --- | --- | +| Visualizar Grupo | ☑️ | ☑️ | ☑️ | +| Remover a si mesmo do Grupo | ☑️ | ☑️ | ☑️ | +| Editar a função de um Membro em um Grupo | | ☑️ | ☑️ | +| Editar ou Excluir uma Associação a Produto ou Tipo de Produto de um Grupo¹ | | ☑️ | ☑️ | +| Alterar a função de um Membro do Grupo para Owner | | | ☑️ | +| Excluir Grupo | | | ☑️ | + +1. Isso também exige que o Usuário tenha pelo menos a Função Maintainer no Produto ou Tipo de Produto que deseja editar. diff --git a/docs/content/admin/user_management/user_permission_chart.zh-hans.md b/docs/content/admin/user_management/user_permission_chart.zh-hans.md new file mode 100644 index 0000000000..97d6453ad5 --- /dev/null +++ b/docs/content/admin/user_management/user_permission_chart.zh-hans.md @@ -0,0 +1,99 @@ +--- +title: 操作权限图表 +description: 详细列出所有 DefectDojo Pro 用户权限 +weight: 4 +audience: pro +aliases: +- /zh-hans/en/customize_dojo/user_management/user_permission_chart +--- + +> **DefectDojo Pro 功能。** 本页介绍的成员/组/全局角色 RBAC 系统是 DefectDojo Pro 的一部分。开源版 DefectDojo 使用[已授权用户](../os__authorized_users/)模型——有关开源版访问控制,请参阅该页面;如果您正在版本之间迁移,请参阅[3.0 升级说明](/releases/os_upgrading/3.0/#authorized-users-panel-replaces-membersgroups-under-legacy-authorization)。 + +## 角色权限图表 + +此图表旨在列出与产品或产品类型相关的所有权限,以及每个角色可用的权限。 + +以下五种角色是 DefectDojo Pro 的**内置角色**。它们是锁定的预设角色：其权限在每个实例上都相同,且无法更改。如果您已创建了自定义角色,本图表描述的是这些自定义角色所克隆自的内置角色,而非自定义角色本身。有关角色可被赋予的完整权限目录,请参阅[自定义 RBAC 角色](../pro__custom_rbac_roles/#choosing-permissions)。 + +| **类别** | **权限** | 读取者 | 编写者 | 维护者 | 所有者 | API 导入者 | +| --- | --- | --- | --- | --- | --- | --- | +| **产品/产品类型访问** | 查看已分配的产品或产品类型 ¹ | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | 查看嵌套的产品、测试活动、测试、发现项、端点 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | 添加新产品(在已分配的产品类型内) ² | | | ☑️ | ☑️ | | +| | 删除已分配的产品或产品类型 | | | | ☑️ | | +| **产品/产品类型成员身份** | 将用户添加为成员(所有者角色除外) | | | ☑️ | ☑️ | | +| | 编辑成员角色(所有者角色除外) | | | ☑️ | ☑️ | | +| | 编辑成员角色(包括所有者角色) | | | | ☑️ | | +| | 将自己移出产品/产品类型成员身份 | ☑️ | ☑️ | ☑️ | ☑️ | | +| | 为其他用户添加所有者角色 | | | | ☑️ | | +| | 编辑组内关联的产品/产品类型成员身份³ | | | | ☑️ | | +| | 删除组内关联的产品/产品类型成员身份³ | | | | | | +| **测试活动**(产品内) | 添加、编辑测试活动 | | ☑️ | ☑️ | ☑️ | ☑️ | +| | 查看风险接受 ⁴ | | ☑️ | ☑️ | ☑️ | | +| | 添加、编辑风险接受 | | ☑️ | ☑️ | ☑️ | | +| | 删除测试活动 | | | ☑️ | ☑️ | | +| **测试**(产品内) | 添加测试 | | ☑️ | ☑️ | ☑️ | | +| | 编辑测试 | | ☑️ | ☑️ | ☑️ | ☑️ | +| | 删除测试 | | | ☑️ | ☑️ | | +| **发现项**(产品内) | 添加发现项 | | ☑️ | ☑️ | ☑️ | | +| | 编辑发现项 | | ☑️ | ☑️ | ☑️ | | +| | 导入、重新导入扫描结果 | | ☑️ | ☑️ | ☑️ | ☑️ | +| | 删除发现项 | | | ☑️ | ☑️ | | +| | 添加、编辑、删除发现项组 | | ☑️ | ☑️ | ☑️ | | +| **其他数据**(产品内) | 添加、编辑端点 | | ☑️ | ☑️ | ☑️ | | +| | 删除端点 | | | ☑️ | ☑️ | | +| | 编辑基准 | | ☑️ | ☑️ | ☑️ | | +| | 删除基准 | | | ☑️ | ☑️ | | +| | 查看备注历史 | ☑️ | ☑️ | ☑️ | ☑️ | | +| | 添加、编辑、删除自己的备注 | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ | +| | 编辑他人的备注 | | ☑️ | ☑️ | ☑️ | ☑️ | +| | 删除他人的备注 | | | ☑️ | ☑️ | | + +1. 仅在产品级别被分配权限的用户,无法查看该产品所属的产品类型。 +2. 当在某个产品类型下添加新产品时,所有产品类型级别的用户都会以其产品类型级别的角色被添加为该新产品的成员。 +3. 希望对组进行更改的用户,还必须拥有**编辑组配置权限**,并在其希望编辑的组中拥有**维护者或所有者**的**组配置角色**。 +4. 风险接受的可见性由一个与发现项可见性不同的独立最低权限所控制——产品上的读取者可以查看相关的发现项,但**无法**查看这些发现项所属的风险接受。有关风险接受权限、到期日期行为以及恢复工作流程的详细信息,请参阅[风险接受(Pro)](/triage_findings/findings_workflows/pro__risk_acceptance/#risk-acceptance-permissions-and-visibility)。 + +## 配置权限图表 + +每项配置权限都对应软件中的某项特定功能,并附带一组与该功能相关的、用户可执行的操作。 + +大多数配置权限赋予用户访问界面中特定页面的权限。 + +| **配置权限** | **查看 ☑️** | **添加 ☑️** | **编辑 ☑️** | **删除 ☑️** | +| --- | --- | --- | --- | --- | +| 凭据管理器 | 访问**⚙️配置 > 凭据管理器**页面 | 向凭据管理器添加新条目 | 编辑凭据管理器条目 | 删除凭据管理器条目 | +| 开发环境 | 不适用 | 向 🗓️**测试活动 > 环境**列表添加新的开发环境 | 编辑 🗓️**测试活动 > 环境**列表中的开发环境 | 从**🗓️测试活动 > 环境**列表中删除开发环境 | +| 发现项模板¹ | 访问**发现项 > 发现项模板**页面 | 添加发现项模板 | 编辑发现项模板 | 删除发现项模板 | +| 组 | 访问**👤用户 > 组**页面 | 添加新的用户组 | 仅限超级用户 | 仅限超级用户 | +| Jira 实例 | 访问**⚙️配置 > JIRA 页面** | 添加新的 JIRA 配置 | 编辑现有的 JIRA 配置 | 删除 JIRA 配置 | +| 语言类型 | | | | | +| 登录横幅 | 不适用 | 不适用 | 编辑登录横幅,位于**⚙️配置 > 登录横幅**下 | 不适用 | +| 公告 | 不适用 | 不适用 | 配置公告,位于**⚙️配置 > 公告**下 | 不适用 | +| 备注类型 | 访问⚙️配置 > 备注类型页面 | 添加备注类型 | 编辑备注类型 | 删除备注类型 | +| 优先级排序引擎 | 访问优先级排序引擎配置页面 | 添加新的优先级排序引擎 | 编辑现有的优先级排序引擎 | 删除优先级排序引擎 | +| 产品类型 | 不适用 | 添加新的产品类型(在产品 > 产品类型下) | 不适用 | 不适用 | +| 问卷 | 访问**问卷 > 所有问卷**页面 | 添加新问卷 | 编辑现有问卷 | 删除问卷 | +| 问题 | 访问**问卷 > 问题**页面 | 添加新问题 | 编辑现有问题 | 不适用 | +| 法规 | 不适用 | 在**⚙️配置 > 法规**页面添加法规 | 编辑现有法规 | 删除法规 | +| 调度服务计划 | 访问**调度**页面 | 仅限超级用户 | 编辑现有计划(更改触发条件、启用/禁用) | 删除计划 | +| SLA 配置 | 访问**⚙️配置 > SLA 配置**页面 | 添加新的 SLA 配置 | 编辑现有的 SLA 配置 | 删除 SLA 配置 | +| 测试类型 | 不适用 | 添加新的测试类型(在**测试活动 > 测试类型**下) | 编辑现有测试类型 | 不适用 | +| 工具配置 | 访问**⚙️配置 > 工具配置**页面 | 添加新的工具配置 | 编辑现有的工具配置 | 删除工具配置 | +| 工具类型 | 访问**⚙️配置 > 工具类型**页面 | 添加新的工具类型 | 编辑现有的工具类型 | 删除工具类型 | +| 用户 | 访问**👤用户 > 用户**页面 | 向 DefectDojo 添加新用户 | 编辑现有用户 | 删除用户 | + +1. 访问发现项模板页面还要求该用户拥有**编写者、维护者**或**所有者**全局角色。 + +## 组配置权限 + +| 配置权限 | **读取者** | **维护者** | **所有者** | +| --- | --- | --- | --- | +| 查看组 | ☑️ | ☑️ | ☑️ | +| 将自己移出组 | ☑️ | ☑️ | ☑️ | +| 编辑组内某成员的角色 | | ☑️ | ☑️ | +| 编辑或删除组中的产品或产品类型成员身份¹ | | ☑️ | ☑️ | +| 将组成员的角色更改为所有者 | | | ☑️ | +| 删除组 | | | ☑️ | + +1. 这还要求该用户在其希望编辑的产品或产品类型上至少拥有维护者角色。 diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.it.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.it.md new file mode 100644 index 0000000000..488be1b265 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.it.md @@ -0,0 +1,39 @@ +--- +title: Grado di salute dell'Asset +description: Come DefectDojo calcola il Grado di salute dell'Asset +weight: 7 +audience: opensource +aliases: +- /it/asset_modelling/os_hierarchy/product_health_grade/ +- /it/en/asset_modelling/os_hierarchy/product_health_grade/ +--- + +DefectDojo può calcolare un grado per i tuoi Asset in base alla quantità di Riscontri in essi contenuti. I gradi sono classificati da A \- F. + +Nota che solo i Riscontri Attivo \& Verificato contribuiscono al Grado dell'Asset \- i Riscontri non verificati non avranno alcun impatto. + +*Il grado di salute di ogni Asset (A \- F) appare accanto al suo nome nell'Elenco degli Asset.* + +![Gradi di salute dell'Asset mostrati accanto a ciascun Asset nell'Elenco degli Asset](images/asset-health-grade.png) + +## Calcolo del Grado dell'Asset + +Ogni Grado dell'Asset parte da 100 (in assenza di Riscontri). + +Il calcolo del grado inizia osservando il livello di **Gravità** più alto di un Riscontro in un Asset, e riducendo la salute dell'Asset a un livello base. + +| **Livello di Gravità più alto di un Riscontro** | **Grado massimo** | +| --- | --- | +| **Critica** | **40** | +| **Alta** | **60** | +| **Media** | **80** | +| **Bassa** | **95** | + +Vengono poi sottratti ulteriori punti dal Grado per ogni Riscontro aggiuntivo: + +| **Livello di Gravità di un Riscontro aggiuntivo** | **Riduzione del Grado** | +| --- | --- | +| **Critica** | **5** | +| **Alta** | **3** | +| **Media** | **2** | +| **Bassa** | **1** | diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.pt-br.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.pt-br.md new file mode 100644 index 0000000000..23cda91338 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.pt-br.md @@ -0,0 +1,39 @@ +--- +title: Nota de Integridade do Ativo +description: Como o DefectDojo calcula a Nota de Integridade do Ativo +weight: 7 +audience: opensource +aliases: +- /pt-br/asset_modelling/os_hierarchy/product_health_grade/ +- /pt-br/en/asset_modelling/os_hierarchy/product_health_grade/ +--- + +O DefectDojo pode calcular uma nota para seus Ativos com base na quantidade de Achados contidos neles. As notas são classificadas de A a F. + +Observe que apenas Achados Ativos e Verificados contribuem para a Nota do Ativo - achados não verificados não terão impacto. + +*A nota de integridade de cada Ativo (A a F) aparece ao lado do seu nome na Lista de Ativos.* + +![Notas de Integridade do Ativo exibidas ao lado de cada Ativo na Lista de Ativos](images/asset-health-grade.png) + +## Cálculo da Nota do Ativo + +Toda Nota de Ativo começa em 100 (sem Achados). + +O cálculo da nota começa observando o maior nível de **Severidade** de um Achado no Ativo, reduzindo a Integridade do Ativo a um nível base. + +| **Maior Nível de Severidade de um Achado** | **Nota Máxima** | +| --- | --- | +| **Crítica** | **40** | +| **Alto** | **60** | +| **Médio** | **80** | +| **Baixo** | **95** | + +Pontos adicionais são então deduzidos da Nota para cada Achado adicional: + +| **Nível de Severidade de um Achado adicional** | **Redução na Nota** | +| --- | --- | +| **Crítica** | **5** | +| **Alto** | **3** | +| **Médio** | **2** | +| **Baixo** | **1** | diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.zh-hans.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.zh-hans.md new file mode 100644 index 0000000000..60d789d107 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.zh-hans.md @@ -0,0 +1,39 @@ +--- +title: 资产健康等级 +description: DefectDojo 如何计算资产健康等级 +weight: 7 +audience: opensource +aliases: +- /zh-hans/asset_modelling/os_hierarchy/product_health_grade/ +- /zh-hans/en/asset_modelling/os_hierarchy/product_health_grade/ +--- + +DefectDojo 可以根据资产中所包含的发现项数量，为您的资产计算等级。等级从 A 到 F 排列。 + +请注意，只有活动且已验证的发现项才会影响资产等级——未验证的发现项不会产生影响。 + +*每个资产的健康等级（A 至 F）会显示在资产列表中其名称旁边。* + +![资产列表中每个资产旁显示的资产健康等级](images/asset-health-grade.png) + +## 资产等级计算 + +每个资产等级的起始值为 100（在没有发现项的情况下）。 + +等级计算首先查看资产中发现项的最高**严重程度**级别，并将资产健康度降低到一个基础水平。 + +| **发现项的最高严重程度级别** | **最高等级** | +| --- | --- | +| **严重** | **40** | +| **高** | **60** | +| **中** | **80** | +| **低** | **95** | + +之后，每增加一个发现项，都会从等级中扣除相应的分数： + +| **额外发现项的严重程度级别** | **等级扣减值** | +| --- | --- | +| **严重** | **5** | +| **高** | **3** | +| **中** | **2** | +| **低** | **1** | diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.it.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.it.md new file mode 100644 index 0000000000..e28c32985b --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.it.md @@ -0,0 +1,216 @@ +--- +title: 'Gerarchia degli Asset: Panoramica' +description: Informazioni su Organizzazioni, Asset, Engagement, Test e Riscontri +weight: 1 +audience: opensource +aliases: +- /it/en/working_with_findings/organizing_engagements_tests/product_hierarchy +- /it/asset_modelling/os_hierarchy/product_hierarchy/ +- /it/en/asset_modelling/os_hierarchy/product_hierarchy/ +--- + +DefectDojo utilizza cinque classi di dati principali per organizzare il tuo lavoro: **Organizzazioni, Asset**, **Engagement**, **Test** e **Riscontri**. + +DefectDojo è progettato per essere flessibile e adattarsi al tuo team, anziché costringere il team ad adattarsi allo strumento. Sarai in grado di progettare uno spazio di lavoro solido e adattabile una volta compreso come queste classi di dati possono essere utilizzate per organizzare il tuo lavoro. + +### Diagramma della gerarchia degli Asset +![image](images/Asset_Hierarchy_Full.png) + + +## **Organizzazioni** + +La prima categoria di dati che dovrai configurare in DefectDojo è un'Organizzazione. Le Organizzazioni sono pensate per categorizzare gli Asset in un modo specifico. Questo potrebbe essere: + +* per dominio aziendale +* per team di sviluppo +* per team di sicurezza + +![image](images/Asset_Hierarchy_Overview.png) +*Gli Asset sono raggruppati e annidati sotto la propria Organizzazione.* + +Alle Organizzazioni è possibile applicare regole di controllo degli accessi basato sui ruoli (Role\-Based Access Control), che limitano la capacità dei membri del team di visualizzare e interagire con i loro dati (inclusi eventuali Asset sottostanti con dati di Engagement, Test e Riscontro). Per maggiori informazioni sui ruoli utente, consulta il nostro articolo **Introduzione ai Ruoli**. + +#### Cosa può rappresentare un'Organizzazione? + +* Se un particolare progetto software ha molte distribuzioni o versioni distinte, potrebbe valere la pena creare una singola Organizzazione che copra l'ambito dell'intero progetto, con ogni versione esistente come Asset individuale. +​ +* Potresti anche considerare di utilizzare le Organizzazioni per rappresentare le fasi del tuo processo di sviluppo software: un'Organizzazione per 'In Development', un'Organizzazione per 'In Production', ecc. +​ +* In definitiva, sta a te decidere come organizzare i tuoi Asset e cosa vuoi che le tue Organizzazioni rappresentino. La tua gerarchia DefectDojo potrebbe dover cambiare per adattarsi alle esigenze dei tuoi team di sicurezza. + +## **Asset** + +Un **Asset** in DefectDojo è pensato per rappresentare qualsiasi progetto, programma o applicazione che stai attualmente testando. L'Asset ospita tutto il lavoro di sicurezza e la cronologia dei test relativi all'obiettivo sottostante. + +![image](images/Asset_Hierarchy_Overview_2.png) + +* un **Nome** univoco +* una **Descrizione** +* un'**Organizzazione** +* una **Configurazione SLA** assegnata + +Gli Asset possono avere un ambito ampio o specifico, a tua scelta. Per impostazione predefinita, gli Asset sono oggetti completamente separati nella gerarchia, ma possono essere raggruppati per **Organizzazione**. + +Gli Asset sono 'isolati' e non interagiscono con altri Asset. Le funzionalità intelligenti di DefectDojo, come la **Deduplicazione**, si applicano solo nel contesto di un singolo Asset. + +Come le **Organizzazioni**, anche gli **Asset** possono avere regole di controllo degli accessi basato sui ruoli, che limitano la capacità dei membri del team di visualizzarli e interagire con essi (così come con eventuali dati di Engagement, Test e Riscontro sottostanti). Per maggiori informazioni sui ruoli utente, consulta il nostro articolo **Introduzione ai Ruoli**. + +#### Cosa può rappresentare un Asset? + +Il concetto di 'Asset' di DefectDojo non corrisponde necessariamente 1:1 a ciò che la tua organizzazione definirebbe un 'Prodotto'. Lo sviluppo software è complesso e le esigenze di sicurezza possono variare notevolmente anche nell'ambito di un singolo software. + +I seguenti scenari sono buoni motivi per considerare la creazione di un Asset DefectDojo separato: + +* "**ExampleAsset**" ha una versione Windows, una versione Mac e una versione Cloud +* "**ExampleAsset 1\.0**" utilizza componenti software completamente diversi da "**ExampleAsset 2\.0**", ed entrambe le versioni sono attivamente supportate dalla tua azienda. +* Il team assegnato a lavorare su "**ExampleAsset version A**" è diverso dal team Asset assegnato a lavorare su "**ExampleAsset version B**", e necessita quindi di autorizzazioni di sicurezza diverse. + +Queste variazioni all'interno di un singolo Asset possono anche essere gestite a livello di Engagement. Nota che gli Engagement non dispongono di controllo degli accessi come invece Asset e Organizzazioni. + +## **Engagement** + +Una volta configurato un Asset, puoi iniziare a creare e pianificare Engagement. Gli Engagement sono pensati per rappresentare i momenti in cui viene svolto il testing, e contengono uno o più **Test**. + +Gli Engagement hanno sempre: + +* un **Nome** univoco +* **Date di inizio e fine** previste +* uno **Status** (Not Started, In Progress, Cancelled, Completed...) +* un **Testing Lead** assegnato +* un **Asset** associato + +Esistono due tipi di Engagement: **Interactive** e **CI/CD**. + +* Un **Interactive Engagement** viene generalmente eseguito da un ingegnere. Gli Interactive Engagement si concentrano sul testing dell'applicazione mentre è in esecuzione, utilizzando un test automatizzato, un tester umano o qualsiasi attività che “interagisce” con le funzionalità dell'applicazione. Consulta la [definizione di IAST di OWASP](https://owasp.org/www-project-devsecops-guideline/latest/02c-Interactive-Application-Security-Testing#:~:text=Interactive%20Application%20Security%20Testing,interacting%E2%80%9D%20with%20the%20application%20functionality.). +* Un **CI/CD Engagement** è pensato per l'integrazione automatizzata con una pipeline CI/CD. I CI/CD Engagement sono pensati per importare dati come azione automatizzata, attivata da una fase del processo di rilascio. + +Gli Engagement possono essere monitorati utilizzando la visualizzazione **Calendar** di DefectDojo. + +#### Cosa può rappresentare un Engagement? + +Gli Engagement sono pensati per rappresentare gruppi di sforzi di test correlati. Il modo in cui desideri raggruppare i tuoi sforzi di test dipende dal tuo approccio. + +Se hai uno sforzo di test pianificato, un Engagement ti offre un luogo in cui archiviare tutti i risultati correlati. Ecco un esempio di questo tipo di Engagement: + +#### **Engagement:** ExampleSoftware 1\.5\.2 \- Sforzo di test interattivo + +*In questo esempio, un team di sicurezza esegue più test nello stesso giorno come parte di un rilascio software.* + +* **Test:** Risultati Nessus Scan (12 marzo\) +* **Test:** Risultati NPM Scan Audit (12 marzo\) +* **Test:** Risultati Snyk Scan (12 marzo\) +​ +Puoi anche organizzare i risultati dei Test CI/CD all'interno di un Engagement. Questi tipi di Engagement sono 'Open\-Ended' (senza fine), il che significa che non hanno una data e aggiungeranno invece dati aggiuntivi ogni volta che vengono eseguite le azioni CI/CD associate. + +#### Engagement: ExampleSoftware - Test CI/CD + +*In questo esempio, più scansioni CI/CD vengono importate automaticamente come Test ogni volta che viene creato un nuovo rilascio software.* + +* Test: Risultati scansione 1\.5\.2 (12 marzo\) +* Test: Risultati scansione 1\.5\.1 (3 marzo\) +* Test: Risultati scansione 1\.5\.0 (14 febbraio\) + +Gli Engagement possono essere organizzati nel modo più adatto al tuo team. Tutti gli Engagement annidati sotto un Asset possono essere visualizzati dal team assegnato a lavorare sull'Asset. + +## **Test** + +I Test sono un raggruppamento di attività svolte dagli ingegneri per cercare di individuare le falle in un Asset. + +I Test hanno sempre: + +* un **Titolo del Test** univoco +* un **Tipo di Test** specifico (API Test, Nessus Scan, ecc.) +* un **Ambiente** di test associato +* un **Engagement** associato + +I Test possono essere creati in diversi modi. I Test possono essere creati automaticamente quando i dati di scansione vengono importati direttamente in un Engagement, generando un nuovo Test contenente i dati della scansione. I Test possono anche essere creati in previsione della pianificazione di futuri engagement, oppure per riscontri di sicurezza inseriti manualmente che richiedono tracciamento e correzione. + +### **Tipi di Test** + +DefectDojo supporta due categorie di Tipi di Test: + +1. **Tipi di Test basati su parser**: corrispondono a scanner di sicurezza specifici che producono output in formati come XML, JSON o CSV. Durante l'importazione dei risultati della scansione, DefectDojo utilizza parser specializzati per convertire l'output dello scanner in Riscontri. + +2. **Tipi di Test senza parser**: vengono utilizzati per i Riscontri creati manualmente e non importati da file di scansione. Questi Tipi di Test utilizzano il metodo [Generic Findings Import](/supported_tools/parsers/generic_findings_import/) per visualizzare Riscontri e metadati. + +I seguenti Tipi di Test compaiono nel menu a discesa "Scan Type" durante la creazione di un nuovo test. + * API Test + * Static Check + * Pen Test + * Web Application Test + * Security Research + * Threat Modeling + * Manual Code Review + +I Tipi di Test senza parser devono essere utilizzati quando è necessario creare manualmente riscontri che richiedono una correzione ma non provengono dall'output di uno scanner automatizzato. + +#### **Tipi di Test basati su parser** + +I tipi di test basati su parser possono essere classificati in base al modo in cui viene determinato il nome del tipo di test: + +- **Nomi di Tipo di Test fissi**: il nome del tipo di test è predefinito e noto prima dell'importazione (ad es. "ZAP Scan", "Nessus Scan"). + +- **Nomi di Tipo di Test definiti dal report**: il nome del tipo di test viene estratto dal contenuto del report di scansione al momento dell'importazione. + +Alcuni esempi includono: + - **Generic Findings Import**: crea tipi di test in base al campo `type` nei report JSON + - **SARIF**: crea tipi di test in base ai nomi degli strumenti nel report SARIF (ad es. "Dockle Scan (SARIF)") + - **OpenReports**: crea tipi di test separati per ogni fonte trovata nel report + +**Regole di denominazione dei Tipi di Test definiti dal report:** +- Se il campo `type` del report è uguale al tipo di scansione → utilizza direttamente il tipo di scansione (ad es. "Generic Findings Import") +- Se il campo `type` del report è diverso → crea il formato "{type} Scan ({scan_type})" (ad es. "Tool1 Scan (Generic Findings Import)") +- Se il campo `type` del report termina già con il suffisso " ({scan_type})" → viene utilizzato così com'è, in modo che il suffisso non venga mai duplicato (ad es. "Tool1 (Generic Findings Import)" resta "Tool1 (Generic Findings Import)") +- Se non viene fornito alcun campo `type` → utilizza direttamente il tipo di scansione + +**Considerazioni importanti:** +- I tipi di test definiti dal report vengono creati automaticamente quando viene rilevato un nuovo tipo durante l'importazione o la reimportazione. +- Per le reimportazioni, il nome del tipo di test deve corrispondere esattamente: eventuali discrepanze genereranno un errore di validazione +- Le impostazioni di deduplicazione (`HASHCODE_FIELDS_PER_SCANNER`) utilizzano i nomi dei tipi di test come chiavi, quindi i nomi definiti dal report devono essere configurati di conseguenza se si desidera un comportamento di deduplicazione personalizzato + +#### **In che modo i Test interagiscono tra loro?** + +I Test prendono i tuoi dati di test e li raggruppano in Riscontri. Generalmente, i team di sicurezza eseguono ripetutamente lo stesso sforzo di test, e i Test in DefectDojo ti consentono di gestire questo processo in modo efficiente. + +**I test importati in precedenza possono essere reimportati** \- Se stai eseguendo lo stesso tipo di test all'interno dello stesso contesto di Engagement, puoi reimportare i risultati del test dopo ogni scansione completata. DefectDojo confronterà i dati reimportati con il risultato esistente e non creerà nuovi Riscontri se nei dati di scansione sono presenti duplicati. + +**I test possono essere importati separatamente** \- Se esegui lo stesso test su un Asset all'interno di Engagement separati, DefectDojo confronterà comunque i dati con i Test precedenti per individuare i Riscontri duplicati. Questo ti consente di tenere traccia dei Riscontri precedentemente mitigati o con rischio accettato. + +Se un Test viene aggiunto direttamente a un Asset senza un Engagement, verrà creato automaticamente un Engagement generico per contenerlo. Questo consente importazioni di dati ad\-hoc. + +**Esempi di Test:** + +* Burp Scan dal 29 ott. 2015 al 29 ott. 2015 +* Nessus Scan dal 31 ott. 2015 al 31 ott. 2015 +* API Test dal 15 ott. 2015 al 20 ott. 2015 + +## **Riscontri** + +Una volta che i dati sono stati caricati in un Test, i risultati di tali dati verranno elencati nel Test come singoli **Riscontri** da esaminare. + +Un riscontro rappresenta una falla specifica scoperta durante il test. + +I Riscontri hanno sempre: + +* un **Nome del Riscontro** univoco +* la **Data** in cui sono stati scoperti +* più **Stati** associati, come Attivo, Verificato o Falso positivo +* un **Test** associato +* un livello di **Gravità**: Critica, Alta, Media, Bassa e Informativo (Info). + +I Riscontri possono essere aggiunti tramite un'importazione di dati, ma possono anche essere aggiunti manualmente a un Test. + +**Esempi di Riscontri:** + +* Potenziale vulnerabilità MiTM OpenSSL 'ChangeCipherSpec' +* Applicazione web potenzialmente vulnerabile al Clickjacking +* Protezione XSS del browser web non abilitata + +## **Endpoint** + +I dati di scansione generalmente contengono riferimenti agli host o agli endpoint interessati da un determinato Riscontro. DefectDojo aggrega automaticamente i Riscontri per endpoint, quindi puoi utilizzare la visualizzazione Endpoint per esaminare tutti i Riscontri che interessano un determinato Endpoint o Hostname. + +Esempi: +- https://www.example.com +- https://www.example.com:8080/products +- 192.168.0.36 diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.pt-br.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.pt-br.md new file mode 100644 index 0000000000..c8f6fa3057 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.pt-br.md @@ -0,0 +1,216 @@ +--- +title: 'Hierarquia de Ativos: Visão Geral' +description: Entenda Organizações, Ativos, Engajamentos, Testes e Achados +weight: 1 +audience: opensource +aliases: +- /pt-br/en/working_with_findings/organizing_engagements_tests/product_hierarchy +- /pt-br/asset_modelling/os_hierarchy/product_hierarchy/ +- /pt-br/en/asset_modelling/os_hierarchy/product_hierarchy/ +--- + +O DefectDojo usa cinco classes principais de dados para organizar seu trabalho: **Organizações, Ativos**, **Engajamentos**, **Testes**, e **Achados**. + +O DefectDojo foi criado para se adaptar à sua equipe, em vez de exigir que sua equipe se adapte à ferramenta. Você poderá projetar um ambiente de trabalho robusto e adaptável assim que entender como essas classes de dados podem ser usadas para organizar seu trabalho. + +### Diagrama de Hierarquia de Ativos +![image](images/Asset_Hierarchy_Full.png) + + +## **Organizações** + +A primeira categoria de dados que você precisará configurar no DefectDojo é uma Organização. As Organizações têm como objetivo categorizar Ativos de uma maneira específica. Isso pode ser: + +* por domínio de negócio +* por equipe de desenvolvimento +* por equipe de segurança + +![image](images/Asset_Hierarchy_Overview.png) +*Os Ativos são agrupados e aninhados sob sua Organização.* + +Organizações podem ter regras de Controle de Acesso Baseado em Função aplicadas, que limitam a capacidade dos membros da equipe de visualizar e interagir com seus dados (incluindo quaisquer Ativos subjacentes com dados de Engajamento, Teste e Achado). Para mais informações sobre funções de usuário, consulte nosso artigo **Introdução às Funções**. + +#### O que uma Organização pode representar? + +* Se um determinado projeto de software tiver várias implantações ou versões distintas, pode valer a pena criar uma única Organização que cubra o escopo de todo o projeto, com cada versão existindo como Ativos individuais. +​ +* Você também pode considerar o uso de Organizações para representar estágios do seu processo de desenvolvimento de software: uma Organização para 'Em Desenvolvimento', uma Organização para 'Em Produção', etc. +​ +* No final das contas, a decisão de como organizar seus Ativos, e o que você deseja que suas Organizações representem, é sua. Sua hierarquia do DefectDojo pode precisar mudar para atender às necessidades da sua equipe de segurança. + +## **Ativos** + +Um **Ativo** no DefectDojo tem como objetivo representar qualquer projeto, programa ou aplicação que você esteja testando no momento. O Ativo hospeda todo o trabalho de segurança e o histórico de testes relacionados ao objetivo subjacente. + +![image](images/Asset_Hierarchy_Overview_2.png) + +* um **Nome** único +* uma **Descrição** +* uma **Organização** +* uma **Configuração de SLA** atribuída + +Os Ativos podem ter um escopo tão amplo ou específico quanto você desejar. Por padrão, os Ativos são objetos completamente separados na hierarquia, mas podem ser agrupados por **Organização**. + +Os Ativos são 'isolados' e não interagem com outros Ativos. Os Recursos Inteligentes do DefectDojo, como a **Deduplicação**, se aplicam apenas no contexto de um único Ativo. + +Assim como as **Organizações**, os **Ativos** podem ter regras de Controle de Acesso Baseado em Função aplicadas, que limitam a capacidade dos membros da equipe de visualizar e interagir com eles (bem como com quaisquer dados subjacentes de Engajamento, Teste e Achado). Para mais informações sobre funções de usuário, consulte nosso artigo **Introdução às Funções**. + +#### O que um Ativo pode representar? + +O conceito de 'Ativo' do DefectDojo não corresponde necessariamente 1:1 ao que sua organização chamaria de 'Produto'. O desenvolvimento de software é complexo, e as necessidades de segurança podem variar muito mesmo dentro do escopo de um único software. + +Os cenários a seguir são bons motivos para considerar a criação de um Ativo separado no DefectDojo: + +* "**ExampleAsset**" tem uma versão para Windows, uma versão para Mac e uma versão para Cloud +* "**ExampleAsset 1.0**" usa componentes de software completamente diferentes de "**ExampleAsset 2.0**", e ambas as versões são ativamente suportadas pela sua empresa. +* A equipe designada para trabalhar em "**ExampleAsset version A**" é diferente da equipe de Ativo designada para trabalhar em "**ExampleAsset version B**", e por isso precisa ter permissões de segurança diferentes atribuídas. + +Essas variações dentro de um único Ativo também podem ser tratadas no nível do Engajamento. Observe que os Engajamentos não têm controle de acesso da mesma forma que os Ativos e as Organizações. + +## **Engajamentos** + +Depois que um Ativo é configurado, você pode começar a criar e agendar Engajamentos. Os Engajamentos têm como objetivo representar momentos no tempo em que os testes estão ocorrendo, e contêm um ou mais **Testes**. + +Os Engajamentos sempre têm: + +* um **Nome** único +* **Datas de início e término** previstas +* **Status** (Not Started, In Progress, Cancelled, Completed...) +* um **Testing Lead** atribuído +* um **Ativo** associado + +Existem dois tipos de Engajamento: **Interactive** e **CI/CD**. + +* Um **Interactive Engagement** é normalmente executado por um engenheiro. Os Interactive Engagements se concentram em testar a aplicação enquanto ela está em execução, usando um teste automatizado, um testador humano ou qualquer atividade que "interaja" com a funcionalidade da aplicação. Veja [a definição de IAST da OWASP](https://owasp.org/www-project-devsecops-guideline/latest/02c-Interactive-Application-Security-Testing#:~:text=Interactive%20Application%20Security%20Testing,interacting%E2%80%9D%20with%20the%20application%20functionality.). +* Um **CI/CD Engagement** é destinado à integração automatizada com um pipeline de CI/CD. Os CI/CD Engagements têm como objetivo importar dados como uma ação automatizada, disparada por uma etapa do processo de release. + +Os Engajamentos podem ser acompanhados usando a visualização de **Calendar** do DefectDojo. + +#### O que um Engajamento pode representar? + +Os Engajamentos têm como objetivo representar grupos de esforços de teste relacionados. A forma como você deseja agrupar seus esforços de teste depende da sua abordagem. + +Se você tem um esforço de teste planejado e agendado, um Engajamento oferece um local para armazenar todos os resultados relacionados. Aqui está um exemplo desse tipo de Engajamento: + +#### **Engajamento:** ExampleSoftware 1.5.2 - Esforço de Teste Interativo + +*Neste exemplo, uma equipe de segurança executa múltiplos testes no mesmo dia como parte de um release de software.* + +* **Teste:** Resultados do Nessus Scan (12 de março) +* **Teste:** Resultados do NPM Scan Audit (12 de março) +* **Teste:** Resultados do Snyk Scan (12 de março) +​ +Você também pode organizar resultados de Teste de CI/CD dentro de um Engajamento. Esse tipo de Engajamento é 'Open-Ended' (sem prazo definido), o que significa que eles não têm uma data e, em vez disso, adicionam dados adicionais toda vez que as ações de CI/CD associadas são executadas. + +#### Engajamento: ExampleSoftware CI/CD Testing + +*Neste exemplo, vários scans de CI/CD são importados automaticamente como Testes toda vez que um novo release de software é criado.* + +* Teste: Resultados do Scan 1.5.2 (12 de março) +* Teste: Resultados do Scan 1.5.1 (3 de março) +* Teste: Resultados do Scan 1.5.0 (14 de fevereiro) + +Os Engajamentos podem ser organizados da forma que funcionar melhor para sua equipe. Todos os Engajamentos aninhados sob um Ativo podem ser visualizados pela equipe designada para trabalhar nesse Ativo. + +## **Testes** + +Os Testes são um agrupamento de atividades realizadas por engenheiros na tentativa de descobrir falhas em um Ativo. + +Os Testes sempre têm: + +* um **Título de Teste** único +* um **Tipo de Teste** específico (API Test, Nessus Scan etc.) +* um **Ambiente** de teste associado +* um **Engajamento** associado + +Os Testes podem ser criados de diferentes maneiras. Eles podem ser criados automaticamente quando os dados de um scan são importados diretamente em um Engajamento, resultando em um novo Teste contendo os dados do scan. Os Testes também podem ser criados antecipadamente, para planejar futuros engajamentos, ou para achados de segurança inseridos manualmente que exijam acompanhamento e remediação. + +### **Tipos de Teste** + +O DefectDojo oferece suporte a duas categorias de Tipos de Teste: + +1. **Tipos de Teste baseados em parser**: Correspondem a scanners de segurança específicos que produzem saída em formatos como XML, JSON ou CSV. Ao importar resultados de scan, o DefectDojo usa parsers especializados para converter a saída do scanner em Achados. + +2. **Tipos de Teste sem parser**: São usados para Achados criados manualmente, não importados de arquivos de scan. Esses Tipos de Teste usam o método [Generic Findings Import](/supported_tools/parsers/generic_findings_import/) para renderizar Achados e metadados. + +Os seguintes Tipos de Teste aparecem no menu suspenso "Scan Type" ao criar um novo teste. + * API Test + * Static Check + * Pen Test + * Web Application Test + * Security Research + * Threat Modeling + * Manual Code Review + +Os Tipos de Teste sem parser devem ser usados quando você precisa criar manualmente achados que exigem remediação, mas que não se originam da saída de um scanner automatizado. + +#### **Tipos de Teste baseados em parser** + +Os tipos de teste baseados em parser podem ser categorizados pela forma como o nome do tipo de teste é determinado: + +- **Nomes de Tipo de Teste fixos**: O nome do tipo de teste é predefinido e conhecido antes da importação (por exemplo, "ZAP Scan", "Nessus Scan"). + +- **Nomes de Tipo de Teste definidos pelo relatório**: O nome do tipo de teste é extraído do conteúdo do relatório de scan no momento da importação. + +Exemplos incluem: + - **Generic Findings Import**: Cria tipos de teste com base no campo `type` em relatórios JSON + - **SARIF**: Cria tipos de teste com base nos nomes das ferramentas no relatório SARIF (por exemplo, "Dockle Scan (SARIF)") + - **OpenReports**: Cria tipos de teste separados para cada origem encontrada no relatório + +**Regras de Nomenclatura de Tipo de Teste Definido pelo Relatório:** +- Se o campo `type` do relatório for igual ao tipo de scan → usa o tipo de scan diretamente (por exemplo, "Generic Findings Import") +- Se o campo `type` do relatório for diferente → cria o formato "{type} Scan ({scan_type})" (por exemplo, "Tool1 Scan (Generic Findings Import)") +- Se o campo `type` do relatório já terminar com o sufixo " ({scan_type})" → ele é usado literalmente, de modo que o sufixo nunca é duplicado (por exemplo, "Tool1 (Generic Findings Import)" permanece "Tool1 (Generic Findings Import)") +- Se nenhum campo `type` for fornecido → usa o tipo de scan diretamente + +**Considerações Importantes:** +- Tipos de teste definidos pelo relatório são criados automaticamente quando um novo tipo é detectado durante a importação ou reimportação. +- Para reimportações, o nome do tipo de teste deve corresponder exatamente - divergências gerarão um erro de validação +- As configurações de Deduplicação (`HASHCODE_FIELDS_PER_SCANNER`) usam os nomes dos tipos de teste como chaves, portanto, os nomes definidos pelo relatório devem ser configurados adequadamente caso você deseje um comportamento de deduplicação personalizado + +#### **Como os Testes interagem entre si?** + +Os Testes pegam seus dados de teste e os agrupam em Achados. Geralmente, as equipes de segurança executam o mesmo esforço de teste repetidamente, e os Testes no DefectDojo permitem lidar com esse processo de forma elegante. + +**Testes previamente importados podem ser reimportados** - Se você estiver executando o mesmo tipo de teste dentro do mesmo contexto de Engajamento, você pode Reimportar os resultados do teste após cada scan concluído. DefectDojo comparará os dados Reimportados com o resultado existente, e não criará novos Achados se houver duplicatas nos dados do scan. + +**Testes podem ser importados separadamente** - Se você executar o mesmo teste em um Ativo dentro de Engajamentos separados, DefectDojo ainda comparará os dados com Testes anteriores para encontrar Achados duplicados. Isso permite acompanhar Achados previamente mitigados ou com risco aceito. + +Se um Teste for adicionado diretamente a um Ativo sem um Engajamento, um Engajamento genérico será criado automaticamente para contê-lo. Isso permite importações de dados ad-hoc. + +**Exemplos de Testes:** + +* Burp Scan de 29 de out. de 2015 a 29 de out. de 2015 +* Nessus Scan de 31 de out. de 2015 a 31 de out. de 2015 +* API Test de 15 de out. de 2015 a 20 de out. de 2015 + +## **Achados** + +Depois que os dados forem enviados para um Teste, os resultados desses dados serão listados no Teste como **Achados** individuais para revisão. + +Um achado representa uma falha específica descoberta durante o teste. + +Os Achados sempre têm: + +* um **Nome de Achado** único +* a **Data** em que foram descobertos +* múltiplos **Status** associados, como Ativo, Verificado ou Falso positivo +* um **Teste** associado +* um nível de **Severidade**: Crítica, Alto, Médio, Baixo e Informativa (Info). + +Os Achados podem ser adicionados por meio de uma importação de dados, mas também podem ser adicionados manualmente a um Teste. + +**Exemplos de Achados:** + +* OpenSSL 'ChangeCipherSpec' MiTM Potential Vulnerability +* Web Application Potentially Vulnerable to Clickjacking +* Web Browser XSS Protection Not Enabled + +## **Endpoints** + +Os dados de scan geralmente contêm referências aos hosts ou endpoints afetados por um determinado Achado. DefectDojo agrega automaticamente os Achados por endpoint, para que você possa usar a visualização de Endpoint para ver todos os Achados que afetam um determinado Endpoint ou Hostname. + +Exemplos: +- https://www.example.com +- https://www.example.com:8080/products +- 192.168.0.36 diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.zh-hans.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.zh-hans.md new file mode 100644 index 0000000000..40bb3511ac --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.zh-hans.md @@ -0,0 +1,216 @@ +--- +title: 资产层级结构：概览 +description: 了解组织、资产、测试活动、测试和发现项 +weight: 1 +audience: opensource +aliases: +- /zh-hans/en/working_with_findings/organizing_engagements_tests/product_hierarchy +- /zh-hans/asset_modelling/os_hierarchy/product_hierarchy/ +- /zh-hans/en/asset_modelling/os_hierarchy/product_hierarchy/ +--- + +DefectDojo 使用五个主要的数据类来组织您的工作：**组织、资产**、**测试活动**、**测试**和**发现项**。 + +DefectDojo 的设计目的是灵活地适应您的团队，而不是让您的团队去迁就工具。一旦您了解了如何使用这些数据类来组织工作，就能够设计出一个健壮、可适应的工作空间。 + +### 资产层级关系图 +![image](images/Asset_Hierarchy_Full.png) + + +## **组织** + +您需要在 DefectDojo 中设置的第一类数据是组织。组织旨在以特定方式对资产进行分类。这可以是： + +* 按业务领域 +* 按开发团队 +* 按安全团队 + +![image](images/Asset_Hierarchy_Overview.png) +*资产按其所属组织进行分组并嵌套在其下。* + +组织可以应用基于角色的访问控制规则，从而限制团队成员查看和操作其数据的能力（包括其下属资产中的测试活动、测试和发现项数据）。有关用户角色的更多信息，请参阅我们的**角色介绍**一文。 + +#### 组织可以代表什么？ + +* 如果某个软件项目有许多不同的部署或版本，那么创建一个涵盖整个项目范围的组织，并让每个版本作为单独的资产存在，可能是值得的。 +​ +* 您也可以考虑使用组织来代表软件开发流程中的各个阶段：一个组织代表“开发中”，一个组织代表“生产中”，依此类推。 +​ +* 归根结底，如何组织您的资产、以及您希望组织代表什么，完全取决于您自己的决定。您的 DefectDojo 层级结构可能需要根据安全团队的需求进行调整。 + +## **资产** + +DefectDojo 中的**资产**旨在代表您当前正在测试的任何项目、程序或应用程序。资产承载着与其底层目标相关的所有安全工作和测试历史。 + +![image](images/Asset_Hierarchy_Overview_2.png) + +* 唯一的**名称** +* **描述** +* 所属**组织** +* 分配的 **SLA 配置** + +资产的范围可宽可窄，完全取决于您的意愿。默认情况下，资产在层级结构中是完全独立的对象，但可以通过**组织**将它们分组在一起。 + +资产是“隔离”的，不会与其他资产相互影响。DefectDojo 的智能功能（例如**去重**）仅在单个资产的范围内生效。 + +与**组织**一样，**资产**也可以应用基于角色的访问控制规则，从而限制团队成员查看和操作它们（以及其下属的测试活动、测试和发现项数据）的能力。有关用户角色的更多信息，请参阅我们的**角色介绍**一文。 + +#### 资产可以代表什么？ + +DefectDojo 中“资产”的概念不一定与您所在组织所称的“产品”一一对应。软件开发是复杂的，即使在单个软件的范围内，安全需求也可能存在很大差异。 + +以下场景是考虑创建单独 DefectDojo 资产的合理理由： + +* “**ExampleAsset**”有 Windows 版本、Mac 版本和云版本 +* “**ExampleAsset 1\.0**”使用的软件组件与“**ExampleAsset 2\.0**”完全不同，且这两个版本都由贵公司积极维护。 +* 负责“**ExampleAsset version A**”的团队与负责“**ExampleAsset version B**”的资产团队不同，因此需要分配不同的安全权限。 + +单个资产内的这些差异也可以在测试活动层面进行处理。请注意，测试活动不像资产和组织那样具有访问控制。 + +## **测试活动** + +设置好资产后，您就可以开始创建和安排测试活动。测试活动旨在代表正在进行测试的时间点，并包含一个或多个**测试**。 + +测试活动始终具有： + +* 唯一的**名称** +* 目标**开始和结束日期** +* **状态**（未开始、进行中、已取消、已完成……） +* 指定的**测试负责人** +* 关联的**资产** + +测试活动有两种类型：**交互式**和 **CI/CD**。 + +* **交互式测试活动**通常由工程师运行。交互式测试活动侧重于在应用程序运行期间对其进行测试，使用自动化测试、人工测试人员，或任何与应用程序功能“交互”的活动。请参阅 [OWASP 对 IAST 的定义](https://owasp.org/www-project-devsecops-guideline/latest/02c-Interactive-Application-Security-Testing#:~:text=Interactive%20Application%20Security%20Testing,interacting%E2%80%9D%20with%20the%20application%20functionality.)。 +* **CI/CD 测试活动**用于与 CI/CD 流水线进行自动化集成。CI/CD 测试活动旨在作为一个自动化操作导入数据，由发布流程中的某个步骤触发。 + +可以使用 DefectDojo 的**日历**视图来跟踪测试活动。 + +#### 测试活动可以代表什么？ + +测试活动旨在代表一组相关的测试工作。您希望如何对测试工作进行分组，取决于您自己的方式。 + +如果您已经安排了一项计划中的测试工作，测试活动可以为您提供一个存储所有相关结果的地方。以下是这类测试活动的一个示例： + +#### **测试活动：** ExampleSoftware 1\.5\.2 \- 交互式测试工作 + +*在此示例中，一个安全团队在同一天内运行了多项测试，作为软件发布的一部分。* + +* **测试：** Nessus 扫描结果（3 月 12 日） +* **测试：** NPM 扫描审计结果（3 月 12 日） +* **测试：** Snyk 扫描结果（3 月 12 日） +​ +您也可以在一个测试活动中组织 CI/CD 测试结果。这类测试活动是“开放式”的，意味着它们没有固定日期，而是每次运行相关的 CI/CD 操作时都会添加额外的数据。 + +#### 测试活动：ExampleSoftware CI/CD Testing + +*在此示例中，每次创建新的软件发布时，多个 CI/CD 扫描都会自动作为测试导入。* + +* 测试：1\.5\.2 扫描结果（3 月 12 日） +* 测试：1\.5\.1 扫描结果（3 月 3 日） +* 测试：1\.5\.0 扫描结果（2 月 14 日） + +测试活动可以按照最适合您团队的方式进行组织。嵌套在某个资产下的所有测试活动，都可以被负责该资产的团队查看。 + +## **测试** + +测试是工程师为尝试发现资产中的缺陷而进行的一组活动。 + +测试始终具有： + +* 唯一的**测试标题** +* 特定的**测试类型**（API 测试、Nessus 扫描等） +* 关联的测试**环境** +* 关联的**测试活动** + +测试可以通过不同方式创建。当扫描数据直接导入某个测试活动时，可以自动创建包含该扫描数据的新测试。也可以为规划未来的测试活动提前创建测试，或者为需要跟踪和修复的手动录入安全发现项创建测试。 + +### **测试类型** + +DefectDojo 支持两类测试类型： + +1. **基于解析器的测试类型**：这些类型对应于以 XML、JSON 或 CSV 等格式生成输出的特定安全扫描器。在导入扫描结果时，DefectDojo 会使用专门的解析器将扫描器输出转换为发现项。 + +2. **非解析器测试类型**：用于并非从扫描文件导入、而是手动创建的发现项。这些测试类型使用 [通用发现项导入](/supported_tools/parsers/generic_findings_import/) 方法来呈现发现项和元数据。 + +创建新测试时，以下测试类型会出现在“扫描类型”下拉菜单中。 + * API 测试 + * 静态检查 + * 渗透测试 + * Web 应用程序测试 + * 安全研究 + * 威胁建模 + * 人工代码审查 + +当您需要手动创建需要修复、但并非源自自动化扫描器输出的发现项时，应使用非解析器测试类型。 + +#### **基于解析器的测试类型** + +基于解析器的测试类型可以根据其测试类型名称的确定方式进行分类： + +- **固定的测试类型名称**：测试类型名称是预先定义好的，在导入之前就已知（例如 "ZAP Scan"、"Nessus Scan"）。 + +- **由报告定义的测试类型名称**：测试类型名称是在导入时从扫描报告内容中提取的。 + +示例包括： + - **Generic Findings Import**：根据 JSON 报告中的 `type` 字段创建测试类型 + - **SARIF**：根据 SARIF 报告中的工具名称创建测试类型（例如 "Dockle Scan (SARIF)"） + - **OpenReports**：为报告中发现的每个来源创建单独的测试类型 + +**由报告定义的测试类型命名规则：** +- 如果报告的 `type` 字段等于扫描类型 → 直接使用扫描类型（例如 "Generic Findings Import"） +- 如果报告的 `type` 字段不同 → 创建 "{type} Scan ({scan_type})" 格式（例如 "Tool1 Scan (Generic Findings Import)"） +- 如果报告的 `type` 字段已经以 " ({scan_type})" 后缀结尾 → 按原样使用，因此后缀不会被重复添加（例如 "Tool1 (Generic Findings Import)" 仍保持为 "Tool1 (Generic Findings Import)"） +- 如果未提供 `type` 字段 → 直接使用扫描类型 + +**重要注意事项：** +- 在导入或重新导入期间检测到新类型时，会自动创建由报告定义的测试类型。 +- 对于重新导入，测试类型名称必须完全匹配——不匹配会引发验证错误 +- 去重设置（`HASHCODE_FIELDS_PER_SCANNER`）使用测试类型名称作为键，因此如果您需要自定义去重行为，必须相应地配置由报告定义的名称 + +#### **测试之间如何相互影响？** + +测试会将您的测试数据整理并归类为发现项。通常，安全团队会重复运行相同的测试工作，而 DefectDojo 中的测试可以让您优雅地处理这一过程。 + +**之前导入的测试可以重新导入** \- 如果您在同一测试活动的上下文中运行相同类型的测试，可以在每次完成扫描后重新导入测试结果。DefectDojo 会将重新导入的数据与现有结果进行比较，如果扫描数据中存在重复项，则不会创建新的发现项。 + +**测试也可以分开导入** \- 如果您在不同的测试活动中对同一资产运行相同的测试，DefectDojo 仍会将该数据与之前的测试进行比较，以查找重复的发现项。这使您能够跟踪之前已缓解或风险已接受的发现项。 + +如果在没有测试活动的情况下将测试直接添加到资产中，系统会自动创建一个通用测试活动来容纳该测试。这样便可以进行临时性的数据导入。 + +**测试示例：** + +* Burp 扫描，时间为 2015 年 10 月 29 日至 2015 年 10 月 29 日 +* Nessus 扫描，时间为 2015 年 10 月 31 日至 2015 年 10 月 31 日 +* API 测试，时间为 2015 年 10 月 15 日至 2015 年 10 月 20 日 + +## **发现项** + +一旦数据被添加/上传到某个测试中，该数据的结果就会在该测试中以单独的**发现项**形式列出，供审查。 + +一个发现项代表在测试过程中发现的一个具体缺陷。 + +发现项始终具有： + +* 唯一的**发现项名称** +* 被发现的**日期** +* 多个关联的**状态**，例如活动、已验证或误报 +* 关联的**测试** +* 一个**严重程度**级别：严重、高、中、低和信息性（信息）。 + +发现项可以通过数据导入添加，但也可以手动添加到测试中。 + +**发现项示例：** + +* OpenSSL “ChangeCipherSpec” 中间人攻击潜在漏洞 +* Web 应用程序可能易受点击劫持攻击 +* Web 浏览器未启用 XSS 防护 + +## **端点** + +扫描数据通常会包含对受某个发现项影响的主机或端点的引用。DefectDojo 会自动按端点汇总发现项，因此您可以使用端点视图来查看影响某个特定端点或主机名的所有发现项。 + +Examples: +- https://www.example.com +- https://www.example.com:8080/products +- 192.168.0.36 diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.it.md b/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.it.md new file mode 100644 index 0000000000..6340003212 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.it.md @@ -0,0 +1,79 @@ +--- +title: Configurazione SLA +description: Configura gli Accordi sul Livello di Servizio per Prodotti diversi +weight: 2 +audience: opensource +aliases: +- /it/en/working_with_findings/sla_configuration +--- + +Ogni Prodotto in DefectDojo può avere una propria configurazione di Service Level Agreement (SLA), che rappresenta i giorni a disposizione della tua organizzazione per correggere o comunque gestire un Riscontro. + +Lo SLA può essere impostato in base alla **[Gravità del Riscontro](/asset_modelling/os_hierarchy/product_hierarchy/#findings)** oppure al **[Rischio del Riscontro](/asset_modelling/pro_hierarchy/priority_sla/)** (in DefectDojo Pro). + +![image](images/sla_multiple.png) + +Gli SLA applicano un conto alla rovescia di giorni a un Riscontro in base al giorno in cui il Riscontro è stato creato in DefectDojo. Se un Riscontro non viene chiuso entro il conto alla rovescia, verrà etichettato come in violazione dello SLA. + +## Utilizzo degli SLA + +Puoi utilizzare gli SLA come un modo per rappresentare le politiche di correzione della tua organizzazione. Puoi anche utilizzarli come un modo per dare priorità ai Riscontri attivi da più tempo e più critici nella tua istanza DefectDojo. + +* Puoi ordinare o filtrare le tabelle dei Riscontri in base ai giorni di SLA. +* Le violazioni dello SLA possono essere configurate per attivare [Notifiche](/admin/notifications/about_notifications/) agli utenti DefectDojo assegnati al Prodotto correlato. +* In **DefectDojo Pro**, le prestazioni dello SLA vengono monitorate anche nelle Dashboard delle metriche [Executive Insights and Remediation](/metrics_reports/pro_metrics/pro__overview/). +* La conformità allo SLA può anche essere mostrata su una [dashboard](/metrics_reports/dashboards/custom-dashboards/) personalizzata in **DefectDojo Pro** — ad esempio con un SLA Burndown o un widget Count filtrato. + +### Stato Mitigated Within SLA + +Se un Riscontro viene Mitigato con successo entro la scadenza dello SLA, il Riscontro registrerà un segno di spunta verde ✅ nella colonna Mitigated Within SLA. + +![image](images/sla_mitigated_within.png) + +Se un Riscontro è stato Mitigato, ma non prima che lo SLA venisse violato, il Riscontro registrerà una X rossa ❌ nella colonna Mitigated Within SLA. + +### Violazione degli SLA + +Quando lo SLA di un determinato Riscontro viene violato (il Riscontro non viene chiuso entro i tempi previsti dallo SLA), il segno di spunta verde ✅ si trasformerà in una X rossa ❌. Lo SLA continuerà a essere monitorato con un numero negativo, per rappresentare da quanti giorni è stato violato. + +![image](images/sla_breached.png) + +## Gestione delle Configurazioni SLA (Pro) + +In DefectDojo Pro, una o più Configurazioni SLA vengono gestite nella sezione **Configuration > Service Level Agreements** della barra laterale. Puoi creare un **New Service Level Agreement** oppure lavorare con le configurazioni SLA esistenti dalla pagina **All Service Level Agreements**. + +![image](images/pro_sla_risk.png) + +Le Configurazioni SLA possono essere modificate solo dai Superuser o da un utente con la [Configuration Permission](/admin/user_management/user_permission_chart/#configuration-permission-chart) corrispondente. + +### Configurazione dello SLA + +Le configurazioni SLA contengono i giorni assegnati a ciascun valore di **Gravità** o **Rischio** di DefectDojo. + +![image](images/pro_new_sla.png) + +Ogni Service Level Agreement può avere un nome univoco, insieme a una descrizione opzionale. + +**Restart SLA on Finding Reactivation**: se abilitata, questa opzione riavvia lo SLA da capo quando un Riscontro viene Riaperto. In caso contrario, lo SLA si baserà sulla data di creazione del Riscontro. + +Quando modifichi uno SLA, puoi scegliere se utilizzare la **Gravità** o il **Rischio** come parametro di riferimento per assegnare i Days To Remediate. Questo si effettua selezionando l'opzione corrispondente nella sezione **Service Level configuration Type** del modulo. + +Da qui, puoi impostare il numero di giorni consentiti per ciascun livello di **Gravità** o **Rischio**. Puoi anche applicare gli SLA in modo selettivo; deselezionando **Enforce ___ Finding Days** puoi escludere il calcolo dello SLA per quei livelli di Gravità o Rischio. + +## Applicare una Configurazione SLA a un Prodotto (Pro) + +I Prodotti appena creati in DefectDojo applicheranno sempre la **Default SLA Configuration**, che può essere impostata su valori diversi se lo desideri. + +Se disponi di configurazioni SLA, puoi scegliere quale applicare al tuo Prodotto dal modulo **Edit Product**. + +![image](images/pro_sla_product.png) + +### Ricalcolo dello SLA + +Una volta selezionato un nuovo SLA per un Prodotto, DefectDojo dovrà ricalcolare gli SLA di tutti i Riscontri associati. Durante l'esecuzione di questo processo, non è possibile modificare lo SLA di un Prodotto. + +## Note sugli SLA + +* Gli SLA possono essere facoltativamente riavviati quando un Riscontro con [Rischio accettato](/triage_findings/findings_workflows/os__risk_acceptance/) si riattiva. Questo viene impostato durante la creazione dell'Accettazione del rischio tramite il campo **Restart SLA Expired**. +* La reimportazione di un Riscontro non riavvia lo SLA: gli SLA vengono sempre calcolati a partire dal momento in cui il Riscontro è stato rilevato per la prima volta, a meno che non sia abilitata l'opzione **Restart SLA on Finding Reactivation**. +* La scadenza dell'Accettazione del rischio o la riattivazione di un Riscontro chiuso sono gli unici modi per reimpostare o ricalcolare lo SLA di un Riscontro una volta creato (senza modificare la configurazione SLA del Prodotto). diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.pt-br.md b/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.pt-br.md new file mode 100644 index 0000000000..fac0acb3c3 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.pt-br.md @@ -0,0 +1,79 @@ +--- +title: Configuração de SLA +description: Configure Acordos de Nível de Serviço para diferentes Produtos +weight: 2 +audience: opensource +aliases: +- /pt-br/en/working_with_findings/sla_configuration +--- + +Cada Produto no DefectDojo pode ter sua própria configuração de Acordo de Nível de Serviço (SLA), que representa os dias que sua organização tem para remediar ou, de outra forma, gerenciar um Achado. + +O SLA pode ser definido com base na **[Severidade do Achado](/asset_modelling/os_hierarchy/product_hierarchy/#findings)** ou no **[Risco do Achado](/asset_modelling/pro_hierarchy/priority_sla/)** (no DefectDojo Pro). + +![image](images/sla_multiple.png) + +Os SLAs aplicam uma contagem regressiva de dias a um Achado com base no dia em que o Achado foi criado no DefectDojo. Se um Achado não for Fechado dentro da contagem regressiva, ele será rotulado como em violação do SLA. + +## Trabalhando com SLAs + +Você pode usar os SLAs como uma forma de representar as políticas de remediação da sua organização. Você também pode usá-los como uma forma de priorizar os Achados mais críticos e ativos há mais tempo na sua instância do DefectDojo. + +* Você pode ordenar ou filtrar tabelas de Achados por dias de SLA. +* As violações de SLA podem ser configuradas para disparar [Notificações](/admin/notifications/about_notifications/) para usuários do DefectDojo atribuídos ao Produto relacionado. +* No **DefectDojo Pro**, o desempenho do SLA também é acompanhado nos Painéis de Métricas de [Executive Insights and Remediation](/metrics_reports/pro_metrics/pro__overview/). +* A conformidade com o SLA também pode ser exibida em um [painel](/metrics_reports/dashboards/custom-dashboards/) personalizado no **DefectDojo Pro** — por exemplo, com um SLA Burndown ou um widget de Contagem filtrado. + +### O status Mitigated Within SLA + +Se um Achado for Mitigado com sucesso até o prazo do SLA, ele registrará uma marca de verificação verde ✅ na coluna Mitigated Within SLA. + +![image](images/sla_mitigated_within.png) + +Se um Achado foi Mitigado, mas não antes de o SLA ser violado, ele registrará um X vermelho ❌ na coluna Mitigated Within SLA. + +### Violação de SLAs + +Quando o SLA de um determinado Achado é violado (o Achado não é Fechado dentro do prazo do SLA) a marca de verificação verde ✅ muda para um X vermelho ❌. O SLA continuará sendo acompanhado com um número negativo, para representar há quantos dias o SLA foi violado. + +![image](images/sla_breached.png) + +## Gerenciando Configurações de SLA (Pro) + +No DefectDojo Pro, uma ou mais Configurações de SLA são gerenciadas na seção **Configuration > Service Level Agreements** da barra lateral. Você pode criar um **New Service Level Agreement** ou trabalhar com configurações de SLA existentes na página **All Service Level Agreements**. + +![image](images/pro_sla_risk.png) + +As Configurações de SLA só podem ser editadas por Superusuários ou por um usuário com a [Permissão de Configuração](/admin/user_management/user_permission_chart/#configuration-permission-chart) correspondente. + +### Configurando o SLA + +As configurações de SLA contêm os dias atribuídos a cada valor de **Severidade** ou **Risco** do DefectDojo. + +![image](images/pro_new_sla.png) + +Cada Acordo de Nível de Serviço pode ter um nome único, junto com uma descrição opcional. + +**Restart SLA on Finding Reactivation**: se habilitada, essa opção reiniciará o SLA quando um Achado for Reaberto. Caso contrário, o SLA será baseado em quando o Achado foi criado. + +Ao editar um SLA, você pode escolher se esse SLA usará **Severidade** ou **Risco** como referência para atribuir os Days To Remediate. Isso é feito selecionando a opção correspondente na seção **Service Level configuration Type** do formulário. + +A partir daqui, você pode definir o número de dias permitido para cada nível de **Severidade** ou **Risco**. Você também pode aplicar os SLAs seletivamente; desmarcando **Enforce ___ Finding Days**, você pode ignorar o cálculo do SLA para esses níveis de Severidade ou Risco. + +## Aplicar uma Configuração de SLA a um Produto (Pro) + +Produtos recém-criados no DefectDojo sempre aplicarão a **Default SLA Configuration**, que pode ser definida com valores diferentes, se desejado. + +Se você tiver configurações de SLA, pode escolher qual delas será aplicada ao seu Produto no formulário **Edit Product**. + +![image](images/pro_sla_product.png) + +### Recálculo de SLA + +Depois que um novo SLA for selecionado para um Produto, os SLAs de todos os Achados associados precisarão ser recalculados pelo DefectDojo. Enquanto esse processo estiver em execução, o SLA do Produto não pode ser alterado. + +## Observações sobre SLAs + +* Os SLAs podem, opcionalmente, ser reiniciados quando um Achado com [Risco aceito](/triage_findings/findings_workflows/os__risk_acceptance/) é reativado. Isso é definido ao criar a Aceitação de Risco, configurando o campo **Restart SLA Expired**. +* Reimportar um Achado não reinicia o SLA - os SLAs são sempre calculados a partir do momento em que um Achado foi detectado pela primeira vez, a menos que **Restart SLA on Finding Reactivation** esteja habilitado. +* A expiração da Aceitação de Risco ou a reativação de um Achado Fechado são as únicas formas de redefinir ou recalcular um SLA para um Achado depois de criado (sem alterar a configuração de SLA do Produto). diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.zh-hans.md b/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.zh-hans.md new file mode 100644 index 0000000000..e2203159f9 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.zh-hans.md @@ -0,0 +1,79 @@ +--- +title: SLA 配置 +description: 为不同产品配置服务级别协议 +weight: 2 +audience: opensource +aliases: +- /zh-hans/en/working_with_findings/sla_configuration +--- + +DefectDojo 中的每个产品都可以拥有自己的服务级别协议（SLA）配置，该配置表示您的组织修复或以其他方式管理某个发现项所拥有的天数。 + +SLA 可以基于**[发现项严重程度](/asset_modelling/os_hierarchy/product_hierarchy/#findings)**或**[发现项风险](/asset_modelling/pro_hierarchy/priority_sla/)**（在 DefectDojo Pro 中）来设置。 + +![image](images/sla_multiple.png) + +SLA 会根据发现项在 DefectDojo 中创建的日期，为其应用天数倒计时。如果发现项未能在倒计时内关闭，该发现项将被标记为违反 SLA。 + +## 使用 SLA + +您可以使用 SLA 来体现您组织的修复策略。您也可以使用它们来对 DefectDojo 实例中活动时间最长、最严重的发现项进行优先排序。 + +* 您可以按 SLA 天数对发现项表格进行排序或筛选。 +* 可以将 SLA 违规配置为向分配到相关产品的 DefectDojo 用户触发[通知](/admin/notifications/about_notifications/)。 +* 在 **DefectDojo Pro** 中，SLA 表现还会在[高管洞察与修复](/metrics_reports/pro_metrics/pro__overview/)指标仪表板中进行跟踪。 +* 在 **DefectDojo Pro** 中，SLA 合规情况也可以在自定义[仪表板](/metrics_reports/dashboards/custom-dashboards/)中呈现——例如通过 SLA 燃尽图或经过筛选的计数小组件。 + +### “在 SLA 内已缓解”状态 + +如果发现项在 SLA 截止日期前成功缓解，该发现项会在“在 SLA 内已缓解”列中记录一个 ✅ 绿色对勾。 + +![image](images/sla_mitigated_within.png) + +如果发现项已缓解，但是在 SLA 被违反之后才缓解的，该发现项会在“在 SLA 内已缓解”列中记录一个 ❌ 红叉。 + +### SLA 违规 + +当某个发现项的 SLA 被违反时（即发现项未能在 SLA 时限内关闭），✅ 绿色对勾会切换为 ❌ 红叉。系统会继续以负数跟踪该 SLA，以表示 SLA 已被违反了多少天。 + +![image](images/sla_breached.png) + +## 管理 SLA 配置（Pro） + +在 DefectDojo Pro 中，一个或多个 SLA 配置在侧边栏的**配置 > 服务级别协议**部分进行管理。您可以创建**新服务级别协议**，也可以在**所有服务级别协议**页面中处理现有的 SLA 配置。 + +![image](images/pro_sla_risk.png) + +SLA 配置只能由超级用户，或拥有相应[配置权限](/admin/user_management/user_permission_chart/#configuration-permission-chart)的用户进行编辑。 + +### 配置 SLA + +SLA 配置包含分配给 DefectDojo 中每个**严重程度**或**风险**值的天数。 + +![image](images/pro_new_sla.png) + +每个服务级别协议都可以拥有一个唯一的名称，以及一个可选的描述。 + +**发现项重新激活时重启 SLA**：如果启用此选项，当某个发现项被重新打开时，其 SLA 将重新开始计算。否则，SLA 将以发现项的创建时间为准。 + +在编辑 SLA 时，您可以选择该 SLA 使用**严重程度**还是**风险**作为分配修复天数的基准。这是通过在表单的**服务级别配置类型**部分选择相应的选项来完成的。 + +在此处，您可以为每个**严重程度**或**风险**级别设置允许的天数。您还可以选择性地强制执行 SLA；取消勾选**强制执行 ___ 发现项天数**，即可忽略对该严重程度或风险级别的 SLA 计算。 + +## 为产品应用 SLA 配置（Pro） + +DefectDojo 中新创建的产品始终会应用**默认 SLA 配置**，如果您愿意，可以将其设置为不同的值。 + +如果您已经有多个 SLA 配置，可以在**编辑产品**表单中选择将哪一个应用于您的产品。 + +![image](images/pro_sla_product.png) + +### SLA 重新计算 + +为某个产品选择新的 SLA 后，DefectDojo 需要重新计算所有相关发现项的 SLA。此过程运行期间，无法更改该产品的 SLA。 + +## 关于 SLA 的说明 + +* 当[风险已接受](/triage_findings/findings_workflows/os__risk_acceptance/)的发现项重新激活时，SLA 可以选择性地重新开始。这是在创建风险接受时通过设置**过期后重启 SLA**字段来配置的。 +* 重新导入某个发现项不会重启其 SLA - 除非启用了**发现项重新激活时重启 SLA**，否则 SLA 始终从该发现项首次被发现的时间开始计算。 +* 风险接受到期或已关闭发现项的重新激活，是在不更改产品 SLA 配置的情况下，重置或重新计算某个发现项 SLA 的唯一方式（该发现项一旦创建）。 diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.it.md b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.it.md new file mode 100644 index 0000000000..4c74c2da99 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.it.md @@ -0,0 +1,59 @@ +--- +title: Collega i Riscontri al codice sorgente +description: Integrazione dei repository per accedere alla posizione dei riscontri + nel codice sorgente. +draft: false +weight: 5 +audience: opensource +aliases: +- /it/en/working_with_findings/organizing_engagements_tests/source-code-repositories +--- + +Alcuni strumenti (in particolare gli strumenti SAST) includono il nome del file e il numero di riga associati nei dati sulla vulnerabilità. Se il repository del codice sorgente è specificato nell'Engagement, DefectDojo presenterà il percorso del file come link e l'utente potrà accedere direttamente alla posizione della vulnerabilità. + +## Impostare il repository nell'Engagement e nel Test + +### Engagement + +Durante la modifica dell'Engagement, gli utenti possono impostare l'URL dello specifico repository di Source Code Management. **(Nell'interfaccia Pro, questo campo può essere impostato in Edit Engagement > Optional Fields > Repo)**. + +Per un Engagement Interattivo, deve essere un URL che specifica il branch: +- per GitHub - come https://github.com/DefectDojo/django-DefectDojo/tree/dev +![Edit Engagement (GitHub)](images/source-code-repositories_1.png) +- per GitLab - come https://gitlab.com/gitlab-org/gitlab/-/tree/master +![Edit Engagement (Gitlab)](images/source-code-repositories-gitlab_1.png) +- per BitBucket pubblico - come (come l'URL di git clone) +![Edit Engagement (Bitbucket public)](images/source-code-repositories-bitbucket_1.png) +- per BitBucket standalone/onpremise https://bb.example.com/scm/some-project/some-repo.git oppure https://bb.example.com/scm/some-user-name/some-repo.git per un repository pubblico dell'utente (come l'URL di git clone) +![Edit Engagement (Bitbucket standalone)](images/source-code-repositories-bitbucket-onpremise_1.png) + +Per gli Engagement CI/CD, l'hash del commit, il branch/tag e la riga di codice possono variare, quindi è necessario includere solo l'URL del repository. +- per GitHub - come `https://github.com/DefectDojo/django-DefectDojo` +- per GitLab - come `https://gitlab.com/gitlab-org/gitlab` +- per BitBucket pubblico, Gitea e Codeberg - come `https://bitbucket.org/some-user/some-project.git` (come l'URL di git clone) +- per BitBucket standalone/onpremise `https://bb.example.com/scm/some-project.git` oppure `https://bb.example.com/scm/some-user-name/some-repo.git` per un repository pubblico dell'utente (come l'URL di git clone) + +In un Engagement CI/CD, è possibile specificare un hash di commit o un branch/tag nel form **Edit Engagement**, che verrà aggiunto a tutti i link generati da DefectDojo. Se questi non sono impostati, l'URL SCM dovrà contenere un link completo che includa il branch del codice. + +L'URL di navigazione SCM viene composto a partire dall'URL del Repo utilizzando il tipo di SCM. Un tipo di SCM specifico può essere impostato nel campo personalizzato dell'Asset "scm-type". Se non viene impostato alcun "scm-type" e l'URL contiene "https://github.com", viene assunto un tipo di SCM "github". + +Campi personalizzati dell'Asset: + +![Asset custom fields](images/asset-custom-fields_1.png) + +Aggiunta del tipo SCM dell'Asset: + +![Asset scm type](images/asset-scm-type_1.png) + +I possibili tipi di SCM sono 'github', 'gitlab', 'bitbucket', 'bitbucket-standalone', 'gitea', 'codeberg' oppure nessuno (per il valore predefinito github). + + +## Link al codice sorgente nei Riscontri + +Durante la visualizzazione di un riscontro, la posizione verrà presentata come un link, se il repository del codice sorgente è stato impostato nell'Engagement: + +![Link to location](images/source-code-repositories_2.png) + +Facendo clic su questo link si aprirà una nuova scheda nel browser, con il file sorgente della vulnerabilità alla riga corrispondente: + +![View in repository](images/source-code-repositories_3.png) diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.pt-br.md b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.pt-br.md new file mode 100644 index 0000000000..8e24e61d80 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.pt-br.md @@ -0,0 +1,59 @@ +--- +title: Vincular Achados ao código-fonte +description: Integração de repositórios para navegar até a localização dos achados + no código-fonte. +draft: false +weight: 5 +audience: opensource +aliases: +- /pt-br/en/working_with_findings/organizing_engagements_tests/source-code-repositories +--- + +Algumas ferramentas (particularmente ferramentas SAST) incluem o nome do arquivo associado e o número da linha nos dados de vulnerabilidade. Se o repositório do código-fonte for especificado no Engajamento, o DefectDojo apresentará o caminho do arquivo como um link, e o usuário poderá navegar diretamente até a localização da vulnerabilidade. + +## Definindo o repositório no Engajamento e no Teste + +### Engajamento + +Ao editar o Engajamento, os usuários podem definir a URL do repositório específico de Gerenciamento de Código-Fonte (SCM). **(Na UI do Pro, esse campo pode ser definido em Editar Engajamento > Campos Opcionais > Repositório)**. + +Para um Engajamento Interativo, é necessário informar uma URL que especifique a branch: +- para o GitHub - como https://github.com/DefectDojo/django-DefectDojo/tree/dev +![Editar Engajamento (GitHub)](images/source-code-repositories_1.png) +- para o GitLab - como https://gitlab.com/gitlab-org/gitlab/-/tree/master +![Editar Engajamento (Gitlab)](images/source-code-repositories-gitlab_1.png) +- para o BitBucket público - como (como uma URL de git clone) +![Editar Engajamento (Bitbucket público)](images/source-code-repositories-bitbucket_1.png) +- para o BitBucket standalone/on-premise https://bb.example.com/scm/some-project/some-repo.git ou https://bb.example.com/scm/some-user-name/some-repo.git para o repositório público do usuário (como uma URL de git clone) +![Editar Engajamento (Bitbucket standalone)](images/source-code-repositories-bitbucket-onpremise_1.png) + +Para Engajamentos de CI/CD, o hash do commit, a branch/tag e a linha de código podem variar, então você só precisa incluir a URL do repositório. +- para o GitHub - como `https://github.com/DefectDojo/django-DefectDojo` +- para o GitLab - como `https://gitlab.com/gitlab-org/gitlab` +- para o BitBucket público, Gitea e Codeberg - como `https://bitbucket.org/some-user/some-project.git` (como uma URL de git clone) +- para o BitBucket standalone/on-premise `https://bb.example.com/scm/some-project.git` ou `https://bb.example.com/scm/some-user-name/some-repo.git` para o repositório público do usuário (como uma URL de git clone) + +Em um Engajamento de CI/CD, você pode especificar um hash de commit ou uma branch/tag no formulário **Editar Engajamento**, que será anexado a todos os links renderizados pelo DefectDojo. Se esses valores não forem definidos, a URL do SCM precisará conter um link completo que inclua a branch de código. + +A URL de navegação do SCM é composta a partir da URL do Repo usando o Tipo de SCM. Um tipo de SCM específico pode ser definido no campo personalizado do Ativo "scm-type". Se nenhum "scm-type" for definido e a URL contiver "https://github.com", será assumido o tipo de SCM "github". + +Campos personalizados do Ativo: + +![Campos personalizados do Ativo](images/asset-custom-fields_1.png) + +Adição do tipo de SCM do Ativo: + +![Tipo de SCM do Ativo](images/asset-scm-type_1.png) + +Os possíveis tipos de SCM podem ser 'github', 'gitlab', 'bitbucket', 'bitbucket-standalone', 'gitea', 'codeberg' ou nenhum (para o padrão github). + + +## Links para o código-fonte nos Achados + +Ao visualizar um achado, a localização será apresentada como um link, caso o repositório do código-fonte tenha sido definido no Engajamento: + +![Link para a localização](images/source-code-repositories_2.png) + +Clicar nesse link abrirá uma nova aba no navegador, com o arquivo de origem da vulnerabilidade na linha correspondente: + +![Ver no repositório](images/source-code-repositories_3.png) diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.zh-hans.md b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.zh-hans.md new file mode 100644 index 0000000000..3acc7a9014 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.zh-hans.md @@ -0,0 +1,58 @@ +--- +title: 将发现项链接到源代码 +description: 集成代码仓库以便跳转到发现项在源代码中的位置。 +draft: false +weight: 5 +audience: opensource +aliases: +- /zh-hans/en/working_with_findings/organizing_engagements_tests/source-code-repositories +--- + +某些工具(尤其是 SAST 工具)会在漏洞数据中包含相关的文件名和行号。如果在测试活动(Engagement)中指定了源代码的代码仓库,DefectDojo 会将文件路径显示为链接,用户可以直接跳转到该漏洞所在的位置。 + +## 在测试活动和测试中设置代码仓库 + +### 测试活动(Engagement) + +在编辑测试活动时,用户可以设置特定源代码管理(SCM)仓库的 URL。**(在 Pro UI 中,可在 Edit Engagement > Optional Fields > Repo 下设置此字段。)** + +对于交互式测试活动(Interactive Engagement),该 URL 需要指定分支: +- 对于 GitHub——例如 https://github.com/DefectDojo/django-DefectDojo/tree/dev +![编辑测试活动(GitHub)](images/source-code-repositories_1.png) +- 对于 GitLab——例如 https://gitlab.com/gitlab-org/gitlab/-/tree/master +![编辑测试活动(GitLab)](images/source-code-repositories-gitlab_1.png) +- 对于公开的 BitBucket——例如 (类似 git clone 使用的 url) +![编辑测试活动(Bitbucket 公开仓库)](images/source-code-repositories-bitbucket_1.png) +- 对于独立部署/本地部署(standalone/onpremise)的 BitBucket,例如 https://bb.example.com/scm/some-project/some-repo.git,或对于用户的公开仓库,例如 https://bb.example.com/scm/some-user-name/some-repo.git(类似 git clone 使用的 url) +![编辑测试活动(Bitbucket 独立部署)](images/source-code-repositories-bitbucket-onpremise_1.png) + +对于 CI/CD 测试活动,提交哈希(commit hash)、分支/标签以及代码行号可能会有所变化,因此您只需提供仓库的 URL 即可。 +- 对于 GitHub——例如 `https://github.com/DefectDojo/django-DefectDojo` +- 对于 GitLab——例如 `https://gitlab.com/gitlab-org/gitlab` +- 对于公开的 BitBucket、Gitea 和 Codeberg——例如 `https://bitbucket.org/some-user/some-project.git`(类似 git clone 使用的 url) +- 对于独立部署/本地部署的 BitBucket,例如 `https://bb.example.com/scm/some-project.git`,或对于用户的公开仓库,例如 `https://bb.example.com/scm/some-user-name/some-repo.git`(类似 git clone 使用的 url) + +在 CI/CD 测试活动中,您可以在 **Edit Engagement** 表单中指定提交哈希或分支/标签,DefectDojo 渲染链接时会将其附加到链接末尾。如果未设置这些内容,则 SCM URL 必须包含完整的链接,其中需包含代码分支。 + +SCM 跳转链接由仓库 URL 结合 SCM 类型组成。可以在资产(Asset)的自定义字段 "scm-type" 中设置特定的 SCM 类型。如果未设置 "scm-type",且 URL 中包含 "https://github.com",则会默认采用 "github" 作为 SCM 类型。 + +资产自定义字段: + +![资产自定义字段](images/asset-custom-fields_1.png) + +添加资产 SCM 类型: + +![资产 SCM 类型](images/asset-scm-type_1.png) + +可选的 SCM 类型包括 'github'、'gitlab'、'bitbucket'、'bitbucket-standalone'、'gitea'、'codeberg',或留空(默认使用 github)。 + + +## 发现项中的源代码链接 + +在查看某个发现项时,如果该测试活动已设置源代码的代码仓库,则漏洞位置会显示为一个链接: + +![指向位置的链接](images/source-code-repositories_2.png) + +点击该链接会在浏览器中打开一个新标签页,并定位到该漏洞对应行号的源代码文件: + +![在代码仓库中查看](images/source-code-repositories_3.png) diff --git a/docs/content/asset_modelling/OS_hierarchy/_index.it.md b/docs/content/asset_modelling/OS_hierarchy/_index.it.md new file mode 100644 index 0000000000..093ea60d20 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/_index.it.md @@ -0,0 +1,11 @@ +--- +title: Gerarchia degli Asset +audience: opensource +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/OS_hierarchy/_index.pt-br.md b/docs/content/asset_modelling/OS_hierarchy/_index.pt-br.md new file mode 100644 index 0000000000..b5d6272632 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/_index.pt-br.md @@ -0,0 +1,11 @@ +--- +title: Hierarquia de Ativos +audience: opensource +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/OS_hierarchy/_index.zh-hans.md b/docs/content/asset_modelling/OS_hierarchy/_index.zh-hans.md new file mode 100644 index 0000000000..5a1f3d6dbd --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/_index.zh-hans.md @@ -0,0 +1,11 @@ +--- +title: 资产层级结构 +audience: opensource +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/OS_hierarchy/benchmarks.it.md b/docs/content/asset_modelling/OS_hierarchy/benchmarks.it.md new file mode 100644 index 0000000000..0dcee79c9b --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/benchmarks.it.md @@ -0,0 +1,39 @@ +--- +title: Benchmark OWASP ASVS +description: Confronta un Prodotto con lo OWASP Application Security Verification + Standard +weight: 6 +audience: opensource +--- + +DefectDojo supporta il confronto dei Prodotti con lo [OWASP Application Security Verification Standard (ASVS)](https://owasp.org/www-project-application-security-verification-standard/), che fornisce una base per testare i controlli di sicurezza tecnici delle applicazioni web. + +I benchmark consentono di misurare quanto un Prodotto soddisfi i requisiti di sicurezza definiti dalla propria organizzazione e di pubblicare un punteggio nella pagina del Prodotto per garantirne la visibilità. + +## Accedere ai Benchmark + +I benchmark sono disponibili dalla pagina **Prodotto**. Per aprire la vista Benchmark, selezionare il menu a discesa nell'area in alto a destra della pagina Prodotto e scegliere **OWASP ASVS v.3.1** verso la fine del menu. + +## Livelli di Benchmark + +OWASP ASVS definisce tre livelli di copertura della verifica: + +- **Livello 1** – Per tutto il software. Copre i requisiti di sicurezza più critici con il costo di verifica più basso. Questo è il livello predefinito in DefectDojo. +- **Livello 2** – Per le applicazioni che contengono dati sensibili. Appropriato per la maggior parte delle applicazioni. +- **Livello 3** – Per le applicazioni più critiche, come quelle che eseguono transazioni di alto valore o memorizzano dati sensibili medici, finanziari o di sicurezza. + +È possibile passare da un livello all'altro utilizzando il menu a discesa in alto a destra della vista Benchmark. + +## Punteggio del Benchmark + +Il lato sinistro della vista Benchmark mostra il punteggio attuale del Prodotto al livello ASVS selezionato: + +- Il **punteggio desiderato** che l'organizzazione ha impostato come obiettivo +- La **percentuale di benchmark superati** rispetto al raggiungimento di tale punteggio +- Il **numero totale di benchmark abilitati** per il livello selezionato + +Abilitando la casella **Publish** il punteggio ASVS verrà visualizzato direttamente nella pagina del Prodotto. + +## Gestire le voci di Benchmark + +Le singole voci di benchmark possono essere contrassegnate come superate o non superate man mano che il team esamina i controlli ASVS. Ulteriori voci di benchmark, oltre all'insieme predefinito ASVS, possono essere aggiunte o aggiornate tramite il **sito di amministrazione Django**. diff --git a/docs/content/asset_modelling/OS_hierarchy/benchmarks.pt-br.md b/docs/content/asset_modelling/OS_hierarchy/benchmarks.pt-br.md new file mode 100644 index 0000000000..a085e0c08e --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/benchmarks.pt-br.md @@ -0,0 +1,39 @@ +--- +title: Benchmarks do OWASP ASVS +description: Compare um Produto com o OWASP Application Security Verification Standard + por meio de Benchmarks +weight: 6 +audience: opensource +--- + +O DefectDojo oferece suporte à realização de benchmark de Produtos em relação ao [OWASP Application Security Verification Standard (ASVS)](https://owasp.org/www-project-application-security-verification-standard/), que fornece uma base para testar controles técnicos de segurança de aplicações web. + +Os Benchmarks permitem medir o quanto um Produto atende aos requisitos de segurança definidos pela sua organização, além de publicar uma pontuação na página do Produto para maior visibilidade. + +## Acessando Benchmarks + +Os Benchmarks estão disponíveis na página **Product**. Para abrir a visualização de Benchmarks, selecione o menu suspenso no canto superior direito da página do Produto e escolha **OWASP ASVS v.3.1** próximo à parte inferior do menu. + +## Níveis de Benchmark + +O OWASP ASVS define três níveis de cobertura de verificação: + +- **Nível 1** – Para todo software. Cobre os requisitos de segurança mais críticos com o menor custo de verificação. Este é o nível padrão no DefectDojo. +- **Nível 2** – Para aplicações que contêm dados sensíveis. Adequado para a maioria das aplicações. +- **Nível 3** – Para as aplicações mais críticas, como aquelas que realizam transações de alto valor ou armazenam dados sensíveis médicos, financeiros ou de segurança. + +Você pode alternar entre os níveis usando o menu suspenso no canto superior direito da visualização de Benchmarks. + +## Pontuação de Benchmark + +O lado esquerdo da visualização de Benchmarks exibe a pontuação atual do seu Produto no nível ASVS selecionado: + +- A **pontuação desejada** que sua organização definiu como meta +- A **porcentagem de benchmarks aprovados** em direção a essa pontuação +- O **número total de benchmarks habilitados** para o nível selecionado + +Habilitar a caixa de seleção **Publicar** exibirá a pontuação do ASVS diretamente na página do Produto. + +## Gerenciando Entradas de Benchmark + +Entradas individuais de benchmark podem ser marcadas como aprovadas ou reprovadas à medida que sua equipe avança pelos controles do ASVS. Entradas adicionais de benchmark, além do conjunto padrão do ASVS, podem ser adicionadas ou atualizadas por meio do **Django admin site**. diff --git a/docs/content/asset_modelling/OS_hierarchy/benchmarks.zh-hans.md b/docs/content/asset_modelling/OS_hierarchy/benchmarks.zh-hans.md new file mode 100644 index 0000000000..30c3c9aad6 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/benchmarks.zh-hans.md @@ -0,0 +1,38 @@ +--- +title: OWASP ASVS 基准测试 +description: 根据 OWASP 应用程序安全验证标准(ASVS)对产品进行基准评估 +weight: 6 +audience: opensource +--- + +DefectDojo 支持根据 [OWASP 应用程序安全验证标准(ASVS)](https://owasp.org/www-project-application-security-verification-standard/) 对产品(Product)进行基准评估,该标准为测试 Web 应用程序的技术安全控制提供了依据。 + +基准测试可以帮助您衡量产品在多大程度上满足了组织所定义的安全要求,并可以在产品页面上发布得分以便查看。 + +## 访问基准测试 + +可以在**产品**页面访问基准测试。要打开基准测试视图,请在产品页面右上角选择下拉菜单,并在菜单底部附近选择 **OWASP ASVS v.3.1**。 + +## 基准测试级别 + +OWASP ASVS 定义了三个验证覆盖级别: + +- **一级(Level 1)** – 适用于所有软件。以最低的验证成本覆盖最关键的安全要求。这是 DefectDojo 中的默认级别。 +- **二级(Level 2)** – 适用于包含敏感数据的应用程序。适用于大多数应用程序。 +- **三级(Level 3)** – 适用于最关键的应用程序,例如执行高价值交易或存储敏感医疗、金融或安全数据的应用程序。 + +您可以使用基准测试视图右上角的下拉菜单在不同级别之间切换。 + +## 基准测试得分 + +基准测试视图的左侧会显示您的产品在所选 ASVS 级别下的当前得分: + +- 您的组织设定的**目标得分** +- 达成该目标得分的**基准测试通过百分比** +- 所选级别下**已启用的基准测试总数** + +启用 **Publish** 复选框后,ASVS 得分会直接显示在产品页面上。 + +## 管理基准测试条目 + +当团队逐项完成 ASVS 控制项时,可以将各个基准测试条目标记为通过或未通过。除默认的 ASVS 条目集之外,还可以通过 **Django admin site** 添加或更新其他基准测试条目。 diff --git a/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.it.md b/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.it.md new file mode 100644 index 0000000000..d7842b0858 --- /dev/null +++ b/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.it.md @@ -0,0 +1,274 @@ +--- +title: Questionari +description: Capire i Questionari in OS DefectDojo +audience: opensource +weight: 2 +--- + +In DefectDojo, un Questionario è un insieme riutilizzabile di domande che raccoglie informazioni da sviluppatori, team e stakeholder sia interni che esterni. Possono essere utilizzati per raccogliere input prima dell'inizio del lavoro, garantire l'allineamento tra individui e team durante l'avanzamento del lavoro e consentire un'analisi retrospettiva una volta completato il lavoro. + +## Modelli di Questionario + +Un modello di Questionario definisce la struttura e il contenuto del Questionario, incluso il suo nome, la descrizione e le Domande associate. Creare un modello di Questionario non lo rende automaticamente disponibile per le risposte. Per raccogliere risposte, un modello di Questionario deve essere distribuito come **Questionario Generale** oppure come **Questionario Collegato**. + +### Questionari Generali e Collegati + +I Questionari Generali e Collegati differiscono per diversi aspetti, tra cui il modo in cui vengono distribuiti, chi può rispondere e dove vengono archiviate le risposte. + +| Questionari Generali | Questionari Collegati | +|---|---| +| Richiedono la pubblicazione | Non richiedono la pubblicazione | +| Richiedono una data di scadenza | Rimangono attivi se l'Engagement è ancora attivo | +| Consentono risposte anonime | Non consentono risposte anonime | +| Sono condivisibili sia internamente che esternamente | Sono condivisibili solo internamente | +| Non consentono di modificare le risposte | Consentono di modificare le risposte | +| Le risposte sono visibili solo dopo la scadenza | Le risposte sono visibili immediatamente | +| Le risposte sono visibili in "Tutti i Questionari" | Le risposte sono visibili all'interno dell'Engagement | +| Possono essere convertiti in un Engagement | Sono già collegati a un Engagement | + +#### Ciclo di vita della distribuzione del Questionario + +I modelli di Questionario seguono cicli di vita diversi a seconda del tipo di distribuzione: + +**Questionari Generali** +Modello → Pubblicato → Accetta Risposte → Scade → Conversione opzionale in Engagement + +**Questionari Collegati** +Modello → Collegato all'Engagement → Accetta Risposte → Rimane attivo finché l'Engagement è attivo + +#### Separazione delle risposte + +Un singolo modello di Questionario può essere distribuito più volte contemporaneamente, sia come Questionario Generale che Collegato. Ogni distribuzione crea il proprio set indipendente di risposte. + +Se lo stesso modello di Questionario viene distribuito come Questionario Generale ed è anche collegato a un Engagement, le risposte inviate tramite ciascuna distribuzione vengono archiviate in modo indipendente e non vengono combinate. Questo consente di riutilizzare lo stesso modello di Questionario in contesti diversi mantenendo separati i set di risposte. + +## Accedere a Questionari e Domande + +È possibile accedere a Questionari e Domande dalla barra laterale facendo clic sull'opzione **Questionnaires**. Il sottomenu offre accesso a **All Questionnaires** e **All Questions**. + +![image](images/q_ss1.png) + +È importante notare che l'accesso alle viste All Questionnaires e All Questions è riservato agli Utenti con stato di Superuser. Solo i Superuser possono creare modelli di Questionario, creare Domande e distribuire Questionari. Gli Utenti senza stato di Superuser possono comunque rispondere ai Questionari Generali condivisi con loro e rispondere anche ai Questionari Collegati degli Engagement a cui hanno accesso, ma non possono crearli né gestirli. + +### Questionari + +La vista All Questionnaires include due tabelle: +- **Questionnaires** + - Questa sezione include tutti i modelli di Questionario esistenti. +- **General Questionnaires** + - Questa sezione include tutti i Questionari Generali attualmente aperti alle risposte. + +Entrambe le sezioni possono essere filtrate per nome, descrizione o stato attivo. + +### Domande + +La vista All Questions include una tabella delle Domande che possono attualmente essere aggiunte a un Questionario. Può anche essere filtrata in base allo stato opzionale di ciascuna Domanda, al contenuto o al tipo di domanda (ad esempio, domanda testuale o domanda a scelta multipla). + +## Gestire i modelli di Questionario + +### Creare Questionari + +È possibile creare nuovi Questionari utilizzando il pulsante Create Questionnaire nella vista All Questionnaires. + +![image](images/q_ss2.png) + +Dopo aver inserito un nome e una descrizione, il Questionario può essere creato senza Domande (che possono essere aggiunte in seguito) oppure le Domande possono essere aggiunte immediatamente. + +#### Aggiungere immediatamente Domande a un nuovo Questionario + +Se le Domande vengono aggiunte immediatamente, selezionare tutte le Domande applicabili dal menu a discesa successivo. È anche possibile creare una nuova Domanda da aggiungere al Questionario facendo clic sul segno + a destra del menu a discesa. + +![image](images/q_ss12.png) + +Una volta selezionate tutte le Domande applicabili, fare clic su **Update Questionnaire Questions** per aggiungere tutte le Domande selezionate al Questionario. + +#### Aggiungere Domande a un Questionario preesistente + +Per aggiungere Domande a un Questionario preesistente, fare clic sul nome del Questionario nella tabella Questionnaires, fare clic su **Edit Questions**, selezionare eventuali nuove Domande da aggiungere al Questionario dal menu a discesa, quindi fare clic su **Update Questionnaire Questions**. + +### Creare Domande + +È possibile creare nuove Domande utilizzando il pulsante **Create Question** nella vista All Questions. + +![image](images/q_ss3.png) + +Inoltre, le Domande possono anche essere create al momento di decidere quali Domande aggiungere a un Questionario, facendo clic sul segno + a destra del menu a discesa. + +#### Tipi di Domanda + +Quando si crea una nuova Domanda, questa può essere formattata come domanda testuale o come domanda a scelta multipla selezionando **Text** oppure **Choice** dal menu a discesa. + +#### Consentire risposte multiple e risposte facoltative + +Il numero massimo di risposte consentite in una domanda a scelta multipla è sei. Selezionando la casella **Multichoice** è possibile scegliere più risposte (disponibile solo per le domande a scelta multipla). Le Domande possono anche essere contrassegnate come **Optional** selezionando la casella corrispondente. + +Consultare la sezione [Editing Questions](#editing-questions) per sapere come aggiungere ulteriori risposte a una domanda a scelta multipla. + +#### Ordine delle Domande + +Determinare l'ordine di una Domanda assegnandole un numero d'ordine. Ad esempio, se una Domanda ha 1 nel campo Order, quella Domanda apparirà sopra una Domanda con 2 nel campo Order. + +![image](images/q_ss13.png) + +### Modificare le Domande + +Una volta creata, una Domanda può essere modificata accedendo al sottomenu All Questions e facendo clic sulla Domanda da modificare. Le Domande non possono essere eliminate. + +È importante evitare di modificare Domande che fanno parte di Questionari attivi. Se una qualsiasi parte di una Domanda viene modificata (ad esempio l'ordine, lo stato facoltativo, la correzione di un errore di battitura, l'aggiunta di una possibile risposta, ecc.) e quella Domanda faceva parte di un Questionario attivo per il quale erano già state inviate risposte, tutte le risposte precedentemente inviate verranno invalidate e sarà necessario inviarle nuovamente. + +#### Modificare le Domande testuali + +Dopo la creazione, le uniche modifiche che possono essere apportate alle Domande testuali sono l'ordine, lo stato facoltativo e la formulazione della domanda. + +#### Modificare le Domande a scelta multipla + +Sebbene il numero predefinito di possibili risposte a una domanda a scelta multipla sia sei, questo può essere aumentato dopo la creazione del Questionario. Per farlo, fare clic sulla Domanda nella vista All Questions, fare clic sul segno **+** a destra del menu a discesa Choices, aggiungere la nuova risposta e fare clic su **Submit**. + +![image](images/q_ss16.png) + +![image](images/q_ss17.png) + +La nuova opzione creata non verrà aggiunta automaticamente al Questionario. Per aggiungerla, fare clic sul menu a discesa **Choices** e selezionare l'opzione appena aggiunta. Accanto ad essa apparirà un segno di spunta che indica che è ora inclusa come possibile risposta nel Questionario. + +![image](images/q_ss18.png) + +## Distribuire i Questionari + +Una volta creato correttamente un modello di Questionario, può essere distribuito per accettare risposte. Il processo di distribuzione è leggermente diverso a seconda del tipo di Questionario. + +### Distribuzione di un Questionario Generale + +Per distribuire un Questionario Generale: +1. Accedere alla vista All Questionnaires. +2. Fare clic sul segno **+** sul lato destro della tabella General Questionnaires. +3. Selezionare il Questionario da distribuire. +4. Impostare la data di scadenza. +5. Fare clic su **Add Questionnaire**. + +#### Condividere un Questionario Generale + +Una volta distribuito, un Questionario Generale può essere condiviso facendo clic su **Share Questionnaire** all'interno della colonna Actions della tabella General Questionnaires. Questo genererà un link che può essere condiviso con i destinatari previsti, consentendo anche di confermare che il Questionario sia formattato come previsto prima di procedere. + +![image](images/q_ss14.png) + +Notare quanto segue: +- Le eventuali risposte a un Questionario Generale non saranno visibili finché il Questionario non sarà scaduto. +- Non è possibile modificare la data di scadenza una volta che il Questionario è stato pubblicato. +- L'orario predefinito in cui un Questionario scade è mezzanotte (ad esempio, un Questionario con scadenza il 31 dicembre 2026 sarà visibile solo fino alle 23:59:59 di quella data). +- Non è possibile impostare un orario di scadenza personalizzato. + +Vedere [Enabling Anonymous Responses](#enabling-anonymous-responses) qui sotto riguardo alla possibilità di consentire risposte da Utenti esterni. + +### Distribuzione di un Questionario Collegato + +Per distribuire un Questionario Collegato: +1. Accedere all'Engagement a cui verrà collegato il Questionario. +2. Fare clic sulla freccia verso il basso nella tabella **Additional Features**. +3. Fare clic sul segno **+** sul lato destro della sottotabella Questionnaires. +4. Selezionare il Questionario da collegare dal menu a discesa. +5. Fare clic su **Add Questionnaire** oppure **Add Questionnaire and Respond**. + +Il Questionario Collegato sarà ora attivo per tutti gli Utenti con accesso all'Engagement. + +#### Condividere un Questionario Collegato + +Per condividere il Questionario Collegato direttamente con gli Utenti interni di DefectDojo, fare clic sul menu kebab ⋮ e selezionare **Share Questionnaire** dal menu a discesa. Apparirà un link che può essere copiato e inoltrato al destinatario previsto. + +![image](images/q_ss10.png) + +Come già accennato, i Questionari Collegati possono essere condivisi solo con Utenti DefectDojo. + +## Rispondere ai Questionari + +Il flusso di lavoro delle risposte differisce leggermente a seconda che il Questionario sia Generale o Collegato. + +### Rispondere a un Questionario Generale + +Per rispondere a un Questionario Generale, gli utenti non Superuser devono ricevere il link direttamente da un Superuser, come descritto [qui](#sharing-a-general-questionnaire). + +#### Abilitare le risposte anonime + +Per impostazione predefinita, i Questionari Generali sono accessibili solo dagli Utenti DefectDojo. Per consentire a soggetti esterni di rispondere ai Questionari DefectDojo, assicurarsi che l'opzione **Allow Anonymous Survey Responses** sia stata attivata nelle System Settings, che si trovano all'interno della sezione **Configurations** della barra laterale. + +![image](images/q_ss4.png) + +![image](images/q_ss5.png) + +Le risposte esterne appariranno come anonime poiché non è associato alla risposta alcun ID utente DefectDojo. + +Se l'ambito di un Questionario include sia Utenti interni che esterni, creare un Questionario Generale e specificare il nome dell'Engagement nella descrizione al momento della creazione, il che consentirà di filtrare i risultati. + +![image](images/q_ss8.png) + +![image](images/q_ss9.png) + +### Rispondere ai Questionari Collegati + +Per rispondere a un Questionario Collegato: +1. Accedere alla vista dell'Engagement. +2. Espandere la tabella Additional Features. +3. Espandere la sottotabella Questionnaires. +4. Fare clic sul menu kebab ⋮ del Questionario Collegato. +5. Fare clic su **Answer Questionnaire**. + +![image](images/q_ss15.png) + +I Questionari Collegati non consentono risposte esterne/anonime poiché per accedere all'Engagement è necessario l'accesso a DefectDojo. + +## Risposte + +Come già accennato, ogni distribuzione di un modello di Questionario crea il proprio contenitore di risposte. Collegare lo stesso modello di Questionario a più Engagement produce set di risposte separati, e la pubblicazione di un Questionario Generale non influisce sui set di risposte dei Questionari Collegati. + +### Risposte del Questionario Generale + +Una volta trascorsa la scadenza di un Questionario Generale: +- Non sarà più possibile inviare ulteriori risposte. +- Tutte le risposte precedenti verranno salvate e diventeranno visibili. +- Il Questionario verrà elencato come Unassigned Answered Engagement Questionnaire nella dashboard di DefectDojo. + +Ci sono tre azioni che possono essere intraprese quando la finestra di risposta di un Questionario si è chiusa: **View Responses**, **Create Engagement** e **Assign User**. + +#### Visualizzare le risposte del Questionario + +Selezionando **View Responses** verranno visualizzate tutte le risposte del Questionario. + +#### Creare un Engagement da un Questionario + +Alla scadenza, un Questionario Generale può essere collegato a un Asset tramite un Engagement selezionando l'azione **Create Engagement**. Selezionare un Asset dall'elenco a discesa successivo e fare clic su **Create Engagement**. Sarà quindi possibile creare un nuovo Engagement e fornirgli dettagli specifici simili ad altri Engagement in DefectDojo, come Description, Version, Status, Tags, ecc. + +![image](images/q_ss6.png) + +![image](images/q_ss7.png) + +#### Assegnare Utente + +L'azione Assign User richiederà di selezionare un Utente dal menu a discesa degli Utenti disponibili. Selezionare un Utente dal menu a discesa e fare clic su **Assign Questionnaire**, il che lo renderà il proprietario di quel Questionario. + +### Risposte del Questionario Collegato + +I Questionari Collegati rimangono disponibili finché l'Engagement associato è attivo. Pertanto, le risposte sono visibili in qualsiasi momento. + +Il menu kebab ⋮ di un Questionario Collegato include diverse funzioni per gestire il Questionario e le relative risposte: +- **Answer Questionnaire**: Questa opzione apparirà se un Utente non ha ancora risposto al Questionario Collegato. Una volta risposto, appariranno View Responses e Edit Responses. +- **View responses**: Consente agli Utenti di vedere tutte le risposte al Questionario fino a quel momento. +- **Edit Responses**: Consente ai singoli Utenti di modificare le proprie Risposte precedenti. +- **Assign User**: Assegna il questionario a un Utente. +- **Link to a Different Engagement**: Apre un menu a discesa di altri Engagement a cui assegnare il Questionario. +- **Share Questionnaire**: Genera un link per condividere il Questionario con gli Utenti interni. +- **Delete Questionnaire**: Scollegherà il Questionario dall'Engagement ed eliminerà tutte le risposte raccolte in precedenza. + +## Eliminare i Questionari + +L'eliminazione dei Questionari Generali e Collegati ha effetti a valle diversi a seconda del risultato previsto dell'eliminazione. + +### Eliminare i Questionari Generali + +L'eliminazione di un Questionario Generale dalla tabella General Questionnaires nella sezione All Questionnaires eliminerà tutte le risposte raccolte da quella distribuzione prima dell'eliminazione. Eventuali Questionari Collegati che utilizzavano lo stesso modello di Questionario non verranno eliminati. + +### Eliminare i Questionari Collegati + +L'eliminazione di un Questionario Collegato scollegherà il Questionario dall'Engagement. Tutte le risposte raccolte all'interno dell'Engagement prima dell'eliminazione andranno perse. I Questionari Generali che erano stati distribuiti in precedenza utilizzando lo stesso modello di Questionario non ne risentiranno. + +### Eliminare i modelli di Questionario + +Per eliminare completamente un modello di Questionario, selezionarlo dalla tabella Questionnaires nella vista All Questionnaires e fare clic su **Delete Questionnaire**. Questo eliminerà definitivamente il modello di Questionario e tutte le risposte associate da tutte le distribuzioni. Questa azione non può essere annullata. diff --git a/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.pt-br.md b/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.pt-br.md new file mode 100644 index 0000000000..ffc303eb2c --- /dev/null +++ b/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.pt-br.md @@ -0,0 +1,274 @@ +--- +title: Questionários +description: Entendendo os Questionários no DefectDojo OS +audience: opensource +weight: 2 +--- + +No DefectDojo, um Questionário é um conjunto reutilizável de perguntas que coleta informações de desenvolvedores, equipes e partes interessadas tanto internas quanto externas. Eles podem ser usados para reunir informações antes do início do trabalho, garantir o alinhamento entre indivíduos e equipes à medida que o trabalho avança, e permitir uma análise retrospectiva após a conclusão do trabalho. + +## Modelos de Questionário + +Um modelo de Questionário define a estrutura e o conteúdo do Questionário, incluindo seu nome, descrição e Perguntas associadas. Criar um modelo de Questionário não o torna automaticamente disponível para receber respostas. Para coletar respostas, um modelo de Questionário deve ser implantado como um **Questionário Geral** ou um **Questionário Vinculado**. + +### Questionários Gerais e Vinculados + +Os Questionários Gerais e Vinculados diferem de várias formas, incluindo como são distribuídos, quem pode responder e onde as respostas são armazenadas. + +| Questionários Gerais | Questionários Vinculados | +|---|---| +| Exigem publicação | Não exigem publicação | +| Exigem uma data de expiração | Permanecem ativos se o Engajamento ainda estiver ativo | +| Permitem respostas anônimas | Não permitem respostas anônimas | +| São compartilháveis interna e externamente | São compartilháveis apenas internamente | +| Não permitem alterar respostas | Permitem alterar respostas | +| Respostas só ficam visíveis após a expiração | Respostas ficam visíveis imediatamente | +| Respostas ficam visíveis em "Todos os Questionários" | Respostas ficam visíveis dentro do Engajamento | +| Podem ser convertidos em um Engajamento | Já está vinculado a um Engajamento | + +#### Ciclo de Vida da Implantação do Questionário + +Os modelos de Questionário seguem ciclos de vida diferentes, dependendo do tipo de implantação: + +**Questionários Gerais** +Modelo → Publicado → Aceita Respostas → Expira → Conversão Opcional em Engajamento + +**Questionários Vinculados** +Modelo → Vinculado ao Engajamento → Aceita Respostas → Permanece ativo enquanto o Engajamento estiver ativo + +#### Separação de Respostas + +Um único modelo de Questionário pode ser implantado várias vezes simultaneamente, tanto como Questionário Geral quanto Vinculado. Cada implantação cria seu próprio conjunto independente de respostas. + +Se o mesmo modelo de Questionário for implantado como um Questionário Geral e também vinculado a um Engajamento, as respostas enviadas por meio de cada implantação são armazenadas de forma independente e não são combinadas. Isso permite que o mesmo modelo de Questionário seja reutilizado em diferentes contextos, mantendo os conjuntos de respostas separados. + +## Acessando Questionários e Perguntas + +Questionários e Perguntas podem ser acessados na barra lateral clicando na opção **Questionários**. O submenu oferece acesso a **Todos os Questionários** e **Todas as Perguntas**. + +![imagem](images/q_ss1.png) + +Vale destacar que o acesso às visualizações Todos os Questionários e Todas as Perguntas é restrito a Usuários com status de Superusuário. Apenas Superusuários podem criar modelos de Questionário, criar Perguntas e implantar Questionários. Usuários sem status de Superusuário ainda podem responder aos Questionários Gerais compartilhados com eles, bem como responder aos Questionários Vinculados dos Engajamentos aos quais têm acesso, mas não podem criá-los nem gerenciá-los. + +### Questionários + +A visualização de Todos os Questionários inclui duas tabelas: +- **Questionários** + - Esta seção inclui todos os modelos de Questionário existentes. +- **Questionários Gerais** + - Esta seção inclui todos os Questionários Gerais que estão atualmente abertos para respostas. + +Ambas as seções podem ser filtradas por nome, descrição ou status de atividade. + +### Perguntas + +A visualização de Todas as Perguntas inclui uma tabela de Perguntas que podem atualmente ser adicionadas a um Questionário. Ela também pode ser filtrada pelo status opcional de cada Pergunta, pelo conteúdo ou pelo tipo de pergunta (por exemplo, pergunta de texto ou pergunta de múltipla escolha). + +## Gerenciando Modelos de Questionário + +### Criar Questionários + +Novos Questionários podem ser criados usando o botão Criar Questionário na visualização Todos os Questionários. + +![imagem](images/q_ss2.png) + +Depois de incluir um nome e uma descrição, o Questionário pode ser criado sem Perguntas (que podem ser adicionadas posteriormente) ou as Perguntas podem ser adicionadas imediatamente. + +#### Adicionar Perguntas Imediatamente a um Novo Questionário + +Se as Perguntas estiverem sendo adicionadas imediatamente, selecione todas as Perguntas aplicáveis no menu suspenso que aparece em seguida. Você também pode criar uma nova Pergunta para adicionar ao Questionário clicando no sinal + à direita do menu suspenso. + +![imagem](images/q_ss12.png) + +Depois que todas as Perguntas aplicáveis tiverem sido selecionadas, clique em **Atualizar Perguntas do Questionário** para adicionar todas as Perguntas selecionadas ao Questionário. + +#### Adicionar Perguntas a um Questionário Já Existente + +Para adicionar Perguntas a um Questionário já existente, clique no nome do Questionário na tabela de Questionários, clique em **Editar Perguntas**, selecione quaisquer novas Perguntas a adicionar ao Questionário no menu suspenso e, em seguida, clique em **Atualizar Perguntas do Questionário**. + +### Criar Perguntas + +Novas Perguntas podem ser criadas usando o botão **Criar Pergunta** na visualização Todas as Perguntas. + +![imagem](images/q_ss3.png) + +Além disso, as Perguntas também podem ser criadas no momento de decidir quais Perguntas adicionar a um Questionário, clicando no sinal + à direita do menu suspenso. + +#### Tipos de Pergunta + +Ao criar uma nova Pergunta, ela pode ser formatada como uma pergunta baseada em texto ou como uma pergunta de múltipla escolha, selecionando **Texto** ou **Múltipla Escolha** no menu suspenso. + +#### Permitindo Múltiplas Respostas e Respostas Opcionais + +O número máximo de respostas permitidas em uma pergunta de múltipla escolha é seis. Marcar a caixa de seleção **Múltipla Escolha** permite que várias respostas sejam selecionadas (disponível apenas para perguntas de múltipla escolha). As Perguntas também podem ser marcadas como **Opcional** ao clicar na caixa de seleção correspondente. + +Consulte a seção [Editando Perguntas](#editing-questions) para saber como adicionar respostas adicionais a uma pergunta de múltipla escolha. + +#### Ordem das Perguntas + +Determine a ordem de uma Pergunta atribuindo a ela um número de ordem. Por exemplo, se uma Pergunta tiver 1 no campo Ordem, essa Pergunta aparecerá acima de uma Pergunta com 2 no campo Ordem. + +![imagem](images/q_ss13.png) + +### Editando Perguntas + +Depois que uma Pergunta é criada, ela pode ser editada acessando o submenu Todas as Perguntas e clicando na Pergunta a ser alterada. As Perguntas não podem ser excluídas. + +É importante evitar editar Perguntas que fazem parte de Questionários ativos. Se qualquer parte de uma Pergunta for alterada (por exemplo, ordem, status opcional, correção de um erro de digitação, adição de uma resposta possível etc.) e essa Pergunta fizer parte de um Questionário ativo que já tenha recebido respostas, todas as respostas enviadas anteriormente serão invalidadas e será necessário reenviá-las. + +#### Editando Perguntas de Texto + +Após a criação, as únicas alterações que podem ser feitas em Perguntas baseadas em texto são a ordem, o status opcional e a formulação da pergunta. + +#### Editando Perguntas de Múltipla Escolha + +Embora o número padrão de respostas possíveis para uma pergunta de múltipla escolha seja seis, esse número pode ser aumentado depois que o Questionário for criado. Para isso, clique na Pergunta na visualização Todas as Perguntas, clique no sinal **+** à direita do menu suspenso Choices, adicione a nova resposta e clique em **Submit**. + +![imagem](images/q_ss16.png) + +![imagem](images/q_ss17.png) + +A opção recém-criada não será adicionada automaticamente ao Questionário. Para adicioná-la, clique no menu suspenso **Choices** e selecione a opção recém-adicionada. Uma marca de seleção aparecerá ao lado dela, indicando que ela agora está incluída como uma resposta possível no Questionário. + +![imagem](images/q_ss18.png) + +## Implantando Questionários + +Depois que um modelo de Questionário é criado com sucesso, ele pode ser implantado para aceitar respostas. O processo de implantação é ligeiramente diferente, dependendo do tipo de Questionário. + +### Implantação de Questionário Geral + +Para implantar um Questionário Geral: +1. Acesse a visualização Todos os Questionários. +2. Clique no **+** no lado direito da tabela de Questionários Gerais. +3. Selecione o Questionário a ser implantado. +4. Defina a data de expiração. +5. Clique em **Adicionar Questionário**. + +#### Compartilhando um Questionário Geral + +Depois de implantado, um Questionário Geral pode ser compartilhado clicando em **Compartilhar Questionário** na coluna Ações da tabela de Questionários Gerais. Isso gerará um link que você pode compartilhar com os destinatários pretendidos, além de permitir confirmar se o Questionário está formatado como esperado antes de fazer isso. + +![imagem](images/q_ss14.png) + +Observe o seguinte: +- Nenhuma resposta a um Questionário Geral ficará visível até que o Questionário tenha expirado. +- Não é possível alterar a data de expiração depois que o Questionário tiver sido publicado. +- O horário padrão de expiração de um Questionário é meia-noite (por exemplo, um Questionário com expiração em 31 de dezembro de 2026 só ficará visível até as 23:59:59 dessa data). +- Não é possível definir um horário de expiração personalizado. + +Consulte [Habilitando Respostas Anônimas](#enabling-anonymous-responses) abaixo para saber como permitir respostas de Usuários externos. + +### Implantação de Questionário Vinculado + +Para implantar um Questionário Vinculado: +1. Acesse o Engajamento que será vinculado ao Questionário. +2. Clique na seta para baixo na tabela **Additional Features**. +3. Clique no **+** no lado direito da subtabela de Questionários. +4. Selecione o Questionário a ser vinculado no menu suspenso. +5. Clique em **Adicionar Questionário** ou em **Adicionar Questionário e Responder**. + +O Questionário Vinculado agora estará ativo para qualquer Usuário com acesso ao Engajamento. + +#### Compartilhando um Questionário Vinculado + +Para compartilhar o Questionário Vinculado diretamente com Usuários internos do DefectDojo, clique no menu kebab ⋮ e selecione **Compartilhar Questionário** no menu suspenso. Um link aparecerá, que pode ser copiado e encaminhado ao destinatário pretendido. + +![imagem](images/q_ss10.png) + +Como mencionado, os Questionários Vinculados só podem ser compartilhados com Usuários do DefectDojo. + +## Respondendo Questionários + +O fluxo de resposta é ligeiramente diferente dependendo se o Questionário é Geral ou Vinculado. + +### Respondendo a um Questionário Geral + +Para responder a um Questionário Geral, os usuários que não são Superusuários precisam receber o link diretamente de um Superusuário, conforme descrito [aqui](#sharing-a-general-questionnaire). + +#### Habilitando Respostas Anônimas + +Por padrão, os Questionários Gerais só podem ser acessados por Usuários do DefectDojo. Para permitir que partes externas respondam aos Questionários do DefectDojo, certifique-se de que a opção **Allow Anonymous Survey Responses** esteja ativada nas Configurações do Sistema, encontradas na seção **Configurations** da barra lateral. + +![imagem](images/q_ss4.png) + +![imagem](images/q_ss5.png) + +As respostas externas aparecerão como anônimas porque não há nenhum ID de usuário do DefectDojo associado à resposta. + +Se o escopo de um Questionário incluir Usuários tanto internos quanto externos, crie um Questionário Geral e especifique o nome do Engajamento na descrição no momento da criação, o que permitirá filtrar os resultados. + +![imagem](images/q_ss8.png) + +![imagem](images/q_ss9.png) + +### Respondendo a Questionários Vinculados + +Para responder a um Questionário Vinculado: +1. Acesse a visualização do Engajamento. +2. Expanda a tabela Additional Features. +3. Expanda a subtabela de Questionários. +4. Clique no menu kebab ⋮ do Questionário Vinculado. +5. Clique em **Responder Questionário**. + +![imagem](images/q_ss15.png) + +Os Questionários Vinculados não permitem respostas externas/anônimas porque é necessário ter acesso ao DefectDojo para acessar o Engajamento. + +## Respostas + +Como mencionado, cada implantação de um modelo de Questionário cria seu próprio container de respostas. Vincular o mesmo modelo de Questionário a vários Engajamentos resulta em conjuntos de respostas separados, e publicar um Questionário Geral não afeta os conjuntos de respostas dos Questionários Vinculados. + +### Respostas de Questionário Geral + +Depois que a expiração de um Questionário Geral tiver passado: +- Não será mais possível enviar respostas adicionais. +- Todas as respostas anteriores serão salvas e ficarão visíveis. +- O Questionário será listado como um Questionário de Engajamento Respondido e Não Atribuído no painel do DefectDojo. + +Há três ações que podem ser realizadas quando a janela de respostas de um Questionário for encerrada: **Ver Respostas**, **Criar Engajamento** e **Atribuir Usuário**. + +#### Visualizando Respostas do Questionário + +Selecionar **Ver Respostas** exibirá todas as respostas do Questionário. + +#### Criando um Engajamento a partir de um Questionário + +Após a expiração, um Questionário Geral pode ser conectado a um Ativo por meio de um Engajamento, selecionando a ação **Criar Engajamento**. Selecione um Ativo na lista suspensa que aparece em seguida e clique em **Criar Engajamento**. Um novo Engajamento poderá então ser criado e receber detalhes específicos, semelhantes aos de outros Engajamentos no DefectDojo, como Descrição, Versão, Status, Tags etc. + +![imagem](images/q_ss6.png) + +![imagem](images/q_ss7.png) + +#### Atribuir Usuário + +A ação Atribuir Usuário solicitará que um Usuário seja selecionado no menu suspenso de Usuários disponíveis. Selecione um Usuário no menu suspenso e clique em **Atribuir Questionário**, o que tornará esse Usuário o proprietário do Questionário. + +### Respostas de Questionário Vinculado + +Os Questionários Vinculados permanecem disponíveis enquanto o Engajamento associado estiver ativo. Dessa forma, as respostas ficam visíveis a qualquer momento. + +O menu kebab ⋮ de um Questionário Vinculado inclui várias funções para gerenciar o Questionário e suas respostas: +- **Responder Questionário**: Esta opção aparece se um Usuário ainda não tiver respondido ao Questionário Vinculado. Depois de respondido, as opções Ver Respostas e Editar Respostas serão exibidas. +- **Ver respostas**: Permite que os Usuários vejam todas as respostas do Questionário até o momento. +- **Editar Respostas**: Permite que Usuários individuais editem suas Respostas anteriores. +- **Atribuir Usuário**: Atribui o questionário a um Usuário. +- **Vincular a um Engajamento Diferente**: Abre um menu suspenso com outros Engajamentos aos quais o Questionário pode ser atribuído. +- **Compartilhar Questionário**: Gera um link para compartilhar o Questionário com Usuários internos. +- **Excluir Questionário**: Desvincula o Questionário do Engajamento e exclui todas as respostas coletadas anteriormente. + +## Excluindo Questionários + +Excluir Questionários Gerais e Vinculados tem efeitos posteriores diferentes, dependendo do resultado pretendido com a exclusão. + +### Excluindo Questionários Gerais + +Excluir um Questionário Geral da tabela de Questionários Gerais na seção Todos os Questionários excluirá todas as respostas coletadas nessa implantação antes da exclusão. Quaisquer Questionários Vinculados que usem o mesmo modelo de Questionário não serão excluídos. + +### Excluindo Questionários Vinculados + +Excluir um Questionário Vinculado desvinculará o Questionário do Engajamento. Todas as respostas coletadas dentro do Engajamento antes da exclusão serão perdidas. Os Questionários Gerais implantados anteriormente usando o mesmo modelo de Questionário não serão afetados. + +### Excluindo Modelos de Questionário + +Para excluir completamente um modelo de Questionário, selecione-o na tabela de Questionários na visualização Todos os Questionários e clique em **Excluir Questionário**. Isso exclui permanentemente o modelo de Questionário e todas as respostas associadas de todas as implantações. Esta ação não pode ser desfeita. diff --git a/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.zh-hans.md b/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.zh-hans.md new file mode 100644 index 0000000000..0736423ede --- /dev/null +++ b/docs/content/asset_modelling/OS_questionnaires/OS__questionnaires.zh-hans.md @@ -0,0 +1,274 @@ +--- +title: 问卷 +description: 了解 OS DefectDojo 中的问卷功能 +audience: opensource +weight: 2 +--- + +在 DefectDojo 中,问卷(Questionnaire)是一组可重复使用的问题,用于从开发人员、团队以及内部和外部利益相关者那里收集信息。它们可用于在工作开始前收集意见、确保个人和团队在工作推进过程中保持一致,并在工作完成后进行回顾性分析。 + +## 问卷模板 + +问卷模板定义了问卷的结构和内容,包括名称、描述以及关联的问题。创建问卷模板并不会自动使其可以接受回复。要收集回复,必须将问卷模板部署为**通用问卷(General Questionnaire)**或**关联问卷(Linked Questionnaire)**。 + +### 通用问卷与关联问卷 + +通用问卷与关联问卷在多个方面存在差异,包括分发方式、可回复的对象,以及回复的存储位置。 + +| 通用问卷 | 关联问卷 | +|---|---| +| 需要发布 | 不需要发布 | +| 需要设置到期日期 | 只要测试活动仍处于活动状态就会保持有效 | +| 允许匿名回复 | 不允许匿名回复 | +| 可在内部和外部共享 | 仅可在内部共享 | +| 不允许更改已提交的回复 | 允许更改回复 | +| 回复只有在到期后才可查看 | 回复可立即查看 | +| 回复显示在"所有问卷"中 | 回复显示在测试活动内 | +| 可以转换为测试活动 | 已经关联到一个测试活动 | + +#### 问卷部署生命周期 + +问卷模板的生命周期会因部署类型不同而有所差异: + +**通用问卷** +模板 → 已发布 → 接受回复 → 到期 → 可选择转换为测试活动 + +**关联问卷** +模板 → 关联到测试活动 → 接受回复 → 在测试活动处于活动状态期间保持有效 + +#### 回复的分离 + +同一个问卷模板可以同时以通用问卷和关联问卷的形式多次部署。每次部署都会创建各自独立的一组回复。 + +如果同一个问卷模板既被部署为通用问卷,又被关联到某个测试活动,那么通过每种部署方式提交的回复会被独立存储,不会合并在一起。这样就可以在不同的场景下重复使用同一个问卷模板,同时保持各自的回复集相互独立。 + +## 访问问卷和问题 + +可以通过点击侧边栏中的**问卷**选项来访问问卷和问题。子菜单提供了对**所有问卷**和**所有问题**的访问入口。 + +![image](images/q_ss1.png) + +需要注意的是,只有具有超级用户(Superuser)权限的用户才能访问"所有问卷"和"所有问题"视图。只有超级用户可以创建问卷模板、创建问题以及部署问卷。不具有超级用户权限的用户仍然可以回复已与其共享的通用问卷,也可以回复其有权访问的测试活动中的关联问卷,但无法创建或管理它们。 + +### 问卷 + +"所有问卷"视图包含两个表格: +- **问卷** + - 该部分包含所有已存在的问卷模板。 +- **通用问卷** + - 该部分包含当前所有开放接受回复的通用问卷。 + +这两个部分都可以按名称、描述或活动状态进行筛选。 + +### 问题 + +"所有问题"视图包含一个问题表格,列出了当前可添加到问卷中的问题。该表格也可以按每个问题的可选状态、内容或问题类型(例如文本类问题或多选类问题)进行筛选。 + +## 管理问卷模板 + +### 创建问卷 + +可以使用"所有问卷"视图中的 Create Questionnaire 按钮创建新问卷。 + +![image](images/q_ss2.png) + +填写名称和描述后,可以选择创建不包含任何问题的问卷(问题可稍后添加),也可以立即添加问题。 + +#### 立即向新问卷添加问题 + +如果选择立即添加问题,请从随后出现的下拉菜单中选择所有适用的问题。您也可以点击下拉菜单右侧的 + 号来创建一个新问题并将其添加到该问卷中。 + +![image](images/q_ss12.png) + +选定所有适用的问题后,点击 **Update Questionnaire Questions** 即可将所有选定的问题添加到该问卷中。 + +#### 向已有问卷添加问题 + +要向已有问卷添加问题,请在问卷表格中点击该问卷的名称,点击 **Edit Questions**,从下拉菜单中选择要添加到该问卷的任何新问题,然后点击 **Update Questionnaire Questions**。 + +### 创建问题 + +可以使用"所有问题"视图中的 **Create Question** 按钮创建新问题。 + +![image](images/q_ss3.png) + +此外,在决定要将哪些问题添加到某个问卷时,也可以通过点击下拉菜单右侧的 + 号来创建问题。 + +#### 问题类型 + +创建新问题时,可以通过在下拉菜单中选择 **Text** 或 **Choice**,将其设置为文本类问题或多选类问题。 + +#### 允许多个答案和可选答案 + +多选类问题允许的最大答案数量为六个。勾选 **Multichoice** 复选框可以允许选择多个答案(仅适用于多选类问题)。问题也可以通过勾选相应的复选框标记为**可选(Optional)**。 + +有关如何为多选类问题添加更多答案选项,请参阅 [编辑问题](#editing-questions) 部分。 + +#### 问题顺序 + +通过为问题指定一个顺序编号来确定其显示顺序。例如,如果某个问题的 Order 字段值为 1,该问题会显示在 Order 字段值为 2 的问题之上。 + +![image](images/q_ss13.png) + +### 编辑问题 + +问题创建完成后,可以通过进入"所有问题"子菜单并点击要修改的问题来对其进行编辑。问题无法被删除。 + +需要特别注意,应避免编辑属于活动问卷的问题。如果某个问题的任何部分被更改(例如顺序、可选状态、更正拼写错误、添加新的可选答案等),而该问题属于一个已经收到回复的活动问卷,那么此前所有已提交的回复都将失效,需要重新提交回复。 + +#### 编辑文本类问题 + +创建完成后,文本类问题只能修改顺序、可选状态以及问题的措辞。 + +#### 编辑多选类问题 + +虽然多选类问题默认可提供的答案数量为六个,但在问卷创建完成后仍可增加该数量。具体操作为:在"所有问题"视图中点击该问题,点击 Choices 下拉菜单右侧的 **+** 号,添加新的答案,然后点击 **Submit**。 + +![image](images/q_ss16.png) + +![image](images/q_ss17.png) + +新创建的选项不会自动添加到问卷中。要添加它,请点击 **Choices** 下拉菜单并选择新添加的选项。选项旁边会出现一个勾选标记,表明它现已被纳入该问卷的可选答案之中。 + +![image](images/q_ss18.png) + +## 部署问卷 + +问卷模板成功创建后,即可部署以接受回复。部署流程会因问卷类型不同而略有差异。 + +### 通用问卷的部署 + +要部署通用问卷: +1. 进入"所有问卷"视图。 +2. 点击通用问卷表格右侧的 **+** 号。 +3. 选择要部署的问卷。 +4. 设置到期日期。 +5. 点击 **Add Questionnaire**。 + +#### 共享通用问卷 + +部署完成后,可以通过点击通用问卷表格 Actions 列中的 **Share Questionnaire** 来共享该通用问卷。这会生成一个链接,您可以将其分享给预定的接收人,并且在此之前还可以确认该问卷的格式符合预期。 + +![image](images/q_ss14.png) + +请注意以下几点: +- 通用问卷的任何回复在问卷到期之前都无法查看。 +- 问卷一旦发布,就无法更改其到期日期。 +- 问卷到期的默认时间为午夜(例如,到期日期设置为 2026 年 12 月 31 日的问卷,只能在当天的 11:59:59 之前查看)。 +- 无法设置自定义的到期时间。 + +有关允许外部用户回复的内容,请参阅下方的 [启用匿名回复](#enabling-anonymous-responses)。 + +### 关联问卷的部署 + +要部署关联问卷: +1. 进入将要关联该问卷的测试活动。 +2. 点击 **Additional Features** 表格上的下箭头。 +3. 点击问卷子表格右侧的 **+** 号。 +4. 从下拉菜单中选择要关联的问卷。 +5. 点击 **Add Questionnaire** 或 **Add Questionnaire and Respond**。 + +此时,该关联问卷会对任何有权访问该测试活动的用户生效。 + +#### 共享关联问卷 + +要将关联问卷直接与内部 DefectDojo 用户共享,请点击 ⋮ 竖排菜单(kebab menu),并从下拉菜单中选择 **Share Questionnaire**。此时会出现一个链接,可以将其复制并转发给预定的接收人。 + +![image](images/q_ss10.png) + +如前所述,关联问卷只能与 DefectDojo 用户共享。 + +## 回复问卷 + +回复流程会因问卷是通用问卷还是关联问卷而略有不同。 + +### 回复通用问卷 + +要回复通用问卷,非超级用户必须由超级用户直接将链接分享给他们,具体方法见[此处](#sharing-a-general-questionnaire)。 + +#### 启用匿名回复 + +默认情况下,通用问卷仅可供 DefectDojo 用户访问。要允许外部人员回复 DefectDojo 问卷,请确保在侧边栏 **Configurations** 部分下的系统设置中,已启用 **Allow Anonymous Survey Responses** 选项。 + +![image](images/q_ss4.png) + +![image](images/q_ss5.png) + +外部回复会显示为匿名,因为该回复没有关联任何 DefectDojo 用户 ID。 + +如果某个问卷的适用范围同时包括内部和外部用户,请创建一个通用问卷,并在创建时于描述中注明该测试活动的名称,以便对结果进行筛选。 + +![image](images/q_ss8.png) + +![image](images/q_ss9.png) + +### 回复关联问卷 + +要回复关联问卷: +1. 进入测试活动视图。 +2. 展开 Additional Features 表格。 +3. 展开问卷子表格。 +4. 点击该关联问卷的 ⋮ 竖排菜单。 +5. 点击 **Answer Questionnaire**。 + +![image](images/q_ss15.png) + +关联问卷不允许外部/匿名回复,因为访问该测试活动本身就需要 DefectDojo 的访问权限。 + +## 回复记录 + +如前所述,问卷模板的每一次部署都会创建各自独立的回复容器。将同一个问卷模板关联到多个测试活动会产生各自独立的回复集,发布通用问卷也不会影响关联问卷的回复集。 + +### 通用问卷的回复 + +通用问卷到期后: +- 将无法再提交新的回复。 +- 此前的所有回复都会被保存并变为可查看状态。 +- 该问卷会在 DefectDojo 仪表板上列为"未分配的已回复测试活动问卷(Unassigned Answered Engagement Questionnaire)"。 + +当问卷的回复窗口关闭后,可以执行三种操作:**View Responses**、**Create Engagement** 和 **Assign User**。 + +#### 查看问卷回复 + +选择 **View Responses** 会显示该问卷的所有回复。 + +#### 根据问卷创建测试活动 + +问卷到期后,可以通过选择 **Create Engagement** 操作,借助一个测试活动将该通用问卷与某个资产关联起来。从随后出现的下拉列表中选择一个资产,然后点击 **Create Engagement**。随后即可创建一个新的测试活动,并为其填写与 DefectDojo 中其他测试活动类似的具体信息,例如 Description、Version、Status、Tags 等。 + +![image](images/q_ss6.png) + +![image](images/q_ss7.png) + +#### 分配用户 + +Assign User 操作会提示您从可用用户的下拉列表中选择一名用户。从下拉菜单中选择一名用户,然后点击 **Assign Questionnaire**,即可将其设为该问卷的所有者。 + +### 关联问卷的回复 + +只要相关联的测试活动处于活动状态,关联问卷就会一直可用。因此,其回复可以随时查看。 + +关联问卷的 ⋮ 竖排菜单包含若干用于管理该问卷及其回复的功能: +- **Answer Questionnaire**:如果用户尚未回复该关联问卷,则会显示此选项。回复完成后,会显示 View Responses 和 Edit Responses。 +- **View responses**:允许用户查看该问卷迄今为止的所有回复。 +- **Edit Responses**:允许用户各自编辑自己此前提交的回复。 +- **Assign User**:将该问卷分配给某个用户。 +- **Link to a Different Engagement**:打开一个下拉菜单,列出可将该问卷关联到的其他测试活动。 +- **Share Questionnaire**:生成一个链接,用于与内部用户共享该问卷。 +- **Delete Questionnaire**:会将该问卷与测试活动解除关联,并删除此前收集到的所有回复。 + +## 删除问卷 + +删除通用问卷和关联问卷所产生的后续影响不同,具体取决于删除操作的预期结果。 + +### 删除通用问卷 + +从"所有问卷"部分的通用问卷表格中删除某个通用问卷,会删除该次部署在删除之前所收集到的所有回复。使用相同问卷模板的任何关联问卷都不会被删除。 + +### 删除关联问卷 + +删除关联问卷会将该问卷与测试活动解除关联。该测试活动中此前收集到的所有回复都将丢失。此前使用相同问卷模板部署的通用问卷不会受到影响。 + +### 删除问卷模板 + +要彻底删除一个问卷模板,请在"所有问卷"视图的问卷表格中选中该模板,然后点击 **Delete Questionnaire**。此操作会永久删除该问卷模板以及所有部署中与之关联的全部回复。此操作无法撤销。 diff --git a/docs/content/asset_modelling/OS_questionnaires/_index.it.md b/docs/content/asset_modelling/OS_questionnaires/_index.it.md new file mode 100644 index 0000000000..fefef14faf --- /dev/null +++ b/docs/content/asset_modelling/OS_questionnaires/_index.it.md @@ -0,0 +1,9 @@ +--- +title: Questionari +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +audience: opensource +--- diff --git a/docs/content/asset_modelling/OS_questionnaires/_index.pt-br.md b/docs/content/asset_modelling/OS_questionnaires/_index.pt-br.md new file mode 100644 index 0000000000..fae824b25d --- /dev/null +++ b/docs/content/asset_modelling/OS_questionnaires/_index.pt-br.md @@ -0,0 +1,9 @@ +--- +title: Questionários +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +audience: opensource +--- diff --git a/docs/content/asset_modelling/OS_questionnaires/_index.zh-hans.md b/docs/content/asset_modelling/OS_questionnaires/_index.zh-hans.md new file mode 100644 index 0000000000..720f202d87 --- /dev/null +++ b/docs/content/asset_modelling/OS_questionnaires/_index.zh-hans.md @@ -0,0 +1,9 @@ +--- +title: 问卷 +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +audience: opensource +--- diff --git a/docs/content/asset_modelling/PRO_hierarchy/_index.it.md b/docs/content/asset_modelling/PRO_hierarchy/_index.it.md new file mode 100644 index 0000000000..3dcacb7cd9 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/_index.it.md @@ -0,0 +1,11 @@ +--- +title: Gerarchia degli Asset +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +audience: pro +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/PRO_hierarchy/_index.pt-br.md b/docs/content/asset_modelling/PRO_hierarchy/_index.pt-br.md new file mode 100644 index 0000000000..3a313ac7a9 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/_index.pt-br.md @@ -0,0 +1,11 @@ +--- +title: Hierarquia de Ativos +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +audience: pro +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/PRO_hierarchy/_index.zh-hans.md b/docs/content/asset_modelling/PRO_hierarchy/_index.zh-hans.md new file mode 100644 index 0000000000..147011de34 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/_index.zh-hans.md @@ -0,0 +1,11 @@ +--- +title: 资产层级结构 +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +audience: pro +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.it.md b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.it.md new file mode 100644 index 0000000000..b9a5285e4c --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.it.md @@ -0,0 +1,149 @@ +--- +title: Gerarchia degli Asset +description: DefectDojo Pro - Revisione della Gerarchia dei Prodotti +audience: pro +weight: 1 +aliases: +- /it/en/working_with_findings/organizing_engagements_tests/pro_assets_organizations +- /it/asset_modelling/pro_hierarchy/assets_organizations +--- + +DefectDojo Pro sta estendendo le classi di oggetti Prodotto/Product Type per fornire maggiore flessibilità al modello dei dati. + +## Abilitare la funzionalità di gerarchia + +I due elementi seguenti sono separati e sono controllati con mezzi diversi. + +### Gerarchia degli Asset + +**Gerarchia degli Asset** abilita le relazioni padre/figlio tra gli Asset. La gerarchia viene visualizzata e gestita dalla scheda **Prodotto** nella navigazione. + +La Gerarchia degli Asset è disponibile in generale ed è attiva per ogni istanza, sia Cloud che On-Premise. Non c'è nulla da abilitare, e non è più elencata nella pagina Feature Flags. + +### Modifiche alle etichette (opzionale) + +**Modifiche alle etichette** rinomina "Product Type" in "Organization" e "Product" in "Asset" in tutta la UI. Questo è un passaggio separato dall'abilitazione della gerarchia e può essere eseguito contemporaneamente o in un secondo momento. + +Le modifiche alle etichette sono attive per impostazione predefinita a partire dalla versione 3.0. Ci sono due controlli, che coprono parti diverse dell'applicazione: + +* **UI Pro** (la UI predefinita): un superuser attiva "Organization / Asset Relabeling" in **Settings > Feature Flags**, sia sulle istanze Cloud che On-Premise. Le nuove etichette appaiono al caricamento della pagina successiva. Vedi [Feature Flags](/admin/feature_flags/pro__feature_flags/). +* **Pagine della UI classica e report generati**: le loro etichette e URL provengono dall'impostazione di deployment `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL`, che viene letta all'avvio di DefectDojo. On-premise, impostala e riavvia DefectDojo. Su [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), invia un'email a [support@defectdojo.com](mailto:support@defectdojo.com) con l'URL della tua istanza. + +Entrambe sono attive per impostazione predefinita, e il valore in Feature Flags è stato inizializzato a partire dall'impostazione di deployment, quindi i due valori coincidono a meno che tu non ne modifichi uno. Mantienili sincronizzati se utilizzi sia la UI classica che la UI Pro. + +Nota che le modifiche alle etichette sono solo estetiche: gli endpoint API e i nomi dei campi rimangono invariati, quindi l'automazione esistente continuerà a funzionare. + +## Modifiche significative + +* I **Product Type** sono stati rinominati in "Organizations", e i **Products** sono stati rinominati in "Assets". A partire dalla versione 3.0 questa modifica del nome è attiva per impostazione predefinita. Vedi [Modifiche alle etichette](#label-changes-optional) per i controlli che la disattivano. +* Gli **Asset** possono ora avere relazioni padre/figlio tra loro per suddividere ulteriormente in sotto-categorie i componenti organizzativi. + +### Organizations + +Come per i Product Type, le **Organizations** dovrebbero essere intese come una categoria di primo livello. Puoi usarle per separare le applicazioni software principali, i reparti o le funzioni aziendali della tua azienda. + +Ad esempio, potresti creare un'Organization per molti raggruppamenti di repository: "Core Application", "Infrastructure", "DevOps", "Analytics", "SDK" potrebbero contenere tutti più repository di codice. + +Tieni presente che, ai fini della reportistica, è più facile combinare più Organizations in un unico documento che suddividere una singola Organization in documenti separati. Pertanto, raccomandiamo di impostare le Organizations al livello di granularità che ha più senso per i report del tuo team. Ad esempio, non c'è bisogno di rappresentare una grande divisione aziendale come un'Organization se prevedi principalmente di produrre report sui singoli reparti all'interno di quella divisione. + +### Assets + +Gli Asset hanno lo scopo di rappresentare le suddivisioni delle tue Organizations. Tuttavia, a differenza dei Products, gli Asset possono essere annidati e avere relazioni padre-figlio tra loro. + +## Esempi di annidamento degli Asset + +### Rappresentazione dei branch a livello di Asset + +I branch di sviluppo e delle funzionalità possono essere rappresentati in vari modi; Engagement o Test separati sono modi già esistenti per rappresentare la differenza tra i tuoi branch di Produzione, Sviluppo e altri branch di funzionalità. + +Puoi anche rappresentarli utilizzando Asset annidati. Considera il seguente albero di Asset: + +``` +Core Application [Organization] +└── webapp-frontend + ├── webapp-frontend/prod + └── webapp-frontend/dev + ├── webapp-frontend/dev/feature-a + └── webapp-frontend/dev/feature-b +``` + +In questo ambiente, ogni branch (`prod`, `dev`, `feature a`, `feature b`) potrebbe avere i propri Engagement e Test isolati dagli altri Asset, in modo che non si deduplichino tra loro. Questa configurazione può anche facilitare la navigazione, poiché i nomi degli Asset possono corrispondere direttamente al percorso su Git. + +### Mono-Repo: componenti separati + +Se utilizzi un unico repository per tutto il tuo codice, ma hai team diversi che contribuiscono a directory all'interno di quel repository, puoi impostare l'annidamento dei tuoi Asset per rappresentare quella struttura. + +``` +Core Application [Organization] +├── webapp-frontend [Parent Asset] +│ ├── mobile-ios +│ ├── mobile-android +│ └── mobile-sdk +├── webapp-backend [Parent Asset] +│ ├── database +│ └── api +└── infra [Parent Asset] + ├── docker + ├── kubernetes + └── nginx +``` + +In questo diagramma, ogni elemento sotto "Core Application" potrebbe essere registrato come un Asset separato, con una propria criticità aziendale (vedi: [Priorità e Rischio](/asset_modelling/pro_hierarchy/priority_sla/#prioritization-engines)), RBAC, ed Engagement e Test corrispondenti. Potresti continuare a testare e archiviare i risultati sull'Asset padre (ad esempio, `webapp-backend`), ma potresti anche eseguire test isolati su un particolare Asset figlio (ad esempio, `database`). + +### Pen Test: RBAC isolato + +Se vuoi archiviare i risultati dei pen test all'interno di un singolo asset, ma non vuoi che i tester possano visualizzare i dati dell'asset, puoi creare asset figli per ogni gruppo di test in cui caricare i propri risultati. + +``` +Core Application [Organization] +└── webapp-frontend [Parent Asset] + ├── Pen Test Group A + └── Pen Test Group B +``` + +Cosa fondamentale, concedere a un utente l'accesso RBAC a un singolo Asset figlio (ad es. `Pen Test Group A`) qui non gli consente di vedere alcun Riscontro degli altri Asset figli (ad es. `Pen Test Group B`), né gli consente di vedere i Riscontri nell'Asset padre (`webapp-frontend`). + +L'Asset padre potrebbe contenere Engagement che rappresentano risultati CI/CD, test interni, dati storici o altri dati sui Riscontri che non vuoi che terze parti possano scoprire. Creare un Asset figlio per risultati di Test specifici consente al tuo team interno di produrre report su quei risultati in combinazione con lo stato dell'Asset padre. + +## Visualizzare gli Asset - Gerarchia + +Puoi visualizzare la struttura degli Asset in DefectDojo e modificare le relazioni utilizzando l'opzione Asset Hierarchy nel menu. + +![image](images/asset_hierarchy.png) + +Aprendo Asset Hierarchy verrà visualizzata una tabella di tutti i tuoi Asset che può essere filtrata. Selezionando uno o più Asset da questa tabella verrà visualizzato un diagramma della gerarchia. + +![image](images/asset_hierarchy_diagram.png) + +### Navigazione del diagramma + +Le icone in alto a sinistra del diagramma della gerarchia consentono di ingrandire e rimpicciolire la vista. Cliccando e trascinando in questo diagramma è possibile scorrerlo. + +Ogni Asset viene rappresentato come un singolo nodo in questo diagramma, che può essere spostato per motivi di visualizzazione. + +Gli Asset sono collegati tra loro tramite percorsi etichettati, che rappresentano il tipo di relazione che ogni nodo ha con l'altro. Attualmente, `parent` è l'unica etichetta supportata. + +### Esplorare i nodi Asset + +Ogni nodo Asset può essere utilizzato cliccando sui pulsanti blu. Questi pulsanti appaiono solo quando un nodo Asset è selezionato (cliccando sul nodo). + +![image](images/asset_hierarchy_node.png) + +* 👁️ (icona occhio) ti porterà direttamente alla vista Asset corrispondente (precedentemente nota come vista Prodotto). +* ✏️ (icona matita) aprirà una finestra modale con il modulo Modifica Asset (precedentemente noto come modulo Modifica Prodotto) +* ➕ (icona più) ti permetterà di aggiungere un nuovo Asset figlio a questo Asset. L'Asset non deve essere necessariamente visibile nel diagramma, ma deve far parte della stessa Organization. +* ✥ (icona quattro frecce) consente di modificare l'Asset padre dell'Asset attualmente selezionato. +* 🗑️ (icona cestino) consente di rimuovere la relazione padre di un Asset. Questa icona appare solo se un Asset ha già un padre. + +Se il tuo diagramma mostra un Asset con Asset padre non selezionati, puoi cliccare sul pulsante Load More per popolare il diagramma con l'Asset padre (così come i figli di quell'Asset padre). + +![image](images/assets_loadmore.png) + +## Note + +* Nota che gli ambiti di deduplicazione non sono cambiati; gli Asset deduplicano i Riscontri solo al proprio interno, e non considerano i Riscontri in altri Asset, indipendentemente dalle relazioni Padre/Figlio. +* Gli ambiti RBAC non sono cambiati in questo sistema; ogni Asset è ancora considerato un oggetto individuale ai fini dell'assegnazione dei permessi. Non è stata creata alcuna nuova ereditarietà RBAC. + * Concedere a un utente l'accesso a un'intera Organization gli darà comunque accesso a tutti gli Asset contenuti in quella Organization (come per i Product Type). + * Concedere a un utente l'accesso a un singolo Asset non gli dà accesso ad alcun Asset padre o figlio correlato, né accesso all'Organization. +* Non c'è alcun limite al numero di relazioni Padre/Figlio che possono essere create. Teoricamente, potresti rappresentare l'intera struttura di directory di un repository con Asset separati, se lo desiderassi. +* Le relazioni cicliche non sono consentite: gli Asset padre non possono essere figli dei loro Asset figli. diff --git a/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.pt-br.md b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.pt-br.md new file mode 100644 index 0000000000..d632d85f2d --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.pt-br.md @@ -0,0 +1,149 @@ +--- +title: Hierarquia de Ativos +description: DefectDojo Pro - Reformulação da Hierarquia de Produtos +audience: pro +weight: 1 +aliases: +- /pt-br/en/working_with_findings/organizing_engagements_tests/pro_assets_organizations +- /pt-br/asset_modelling/pro_hierarchy/assets_organizations +--- + +O DefectDojo Pro está estendendo as classes de objeto Produto/Tipo de Produto para oferecer maior flexibilidade ao modelo de dados. + +## Habilitando o recurso de Hierarquia + +As duas partes abaixo são separadas e controladas por meios diferentes. + +### Hierarquia de Ativos + +**Hierarquia de Ativos** habilita relações pai/filho entre Ativos. A hierarquia é visualizada e gerenciada a partir da aba **Produto** na navegação. + +A Hierarquia de Ativos está disponível de forma geral e ativa para toda instância, seja Cloud ou On-Premise. Não há nada a habilitar, e ela não está mais listada na página de Feature Flags. + +### Alterações de rótulo (opcional) + +**Alterações de rótulo** renomeia "Tipo de Produto" para "Organização" e "Produto" para "Ativo" em toda a UI. Esta é uma etapa separada da habilitação da hierarquia e pode ser feita ao mesmo tempo ou posteriormente. + +As alterações de rótulo estão ativas por padrão a partir da versão 3.0. Existem dois controles, cobrindo partes diferentes da aplicação: + +* **UI Pro** (a UI padrão): um superusuário alterna "Organization / Asset Relabeling" em **Settings > Feature Flags**, tanto em instâncias Cloud quanto On-Premise. Os novos rótulos aparecem no próximo carregamento de página. Veja [Feature Flags](/admin/feature_flags/pro__feature_flags/). +* **Páginas da UI Clássica e relatórios gerados**: seus rótulos e URLs vêm da configuração de implantação `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL`, que é lida quando o DefectDojo é iniciado. No modelo on-premise, defina-a e reinicie o DefectDojo. No [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), envie um e-mail para [support@defectdojo.com](mailto:support@defectdojo.com) com a URL da sua instância. + +Ambos vêm ativados por padrão, e o valor de Feature Flags foi originado a partir da configuração de implantação, portanto os dois concordam a menos que você altere um deles. Mantenha-os sincronizados se você também usar a UI Clássica, além da UI Pro. + +Observe que as alterações de rótulo são apenas cosméticas: os endpoints da API e os nomes de campo permanecem inalterados, portanto a automação existente continuará funcionando. + +## Alterações significativas + +* **Tipos de Produto** foram renomeados para "Organizações", e **Produtos** foram renomeados para "Ativos". A partir da versão 3.0, essa mudança de nome está ativa por padrão. Veja [Alterações de rótulo](#label-changes-optional) para os controles que a desativam. +* **Ativos** agora podem ter relações pai/filho entre si para subcategorizar ainda mais os componentes organizacionais. + +### Organizações + +Assim como os Tipos de Produto, as **Organizações** devem ser entendidas como uma categoria de nível superior. Você pode usá-las para separar as principais aplicações de software, departamentos ou funções de negócio da sua empresa. + +Por exemplo, você poderia criar uma Organização para diversos agrupamentos de repositórios: "Aplicação Principal", "Infraestrutura", "DevOps", "Analytics", "SDK" poderiam conter, cada uma, múltiplos repositórios de código. + +Tenha em mente que, para fins de relatório, é mais fácil combinar múltiplas Organizações em um único documento do que subdividir uma única Organização em documentos separados. Portanto, recomendamos configurar as Organizações no nível mais granular que fizer sentido para os relatórios da sua equipe. Por exemplo, não há necessidade de representar uma grande divisão de negócio como uma Organização se você pretende, principalmente, gerar relatórios sobre departamentos individuais dentro dessa divisão. + +### Ativos + +Os Ativos têm o objetivo de representar subdivisões das suas Organizações. No entanto, diferentemente dos Produtos, os Ativos podem ser aninhados e ter relações pai-filho entre si. + +## Exemplos de aninhamento de Ativos + +### Representação de branch no nível de Ativo + +Branches de desenvolvimento e de funcionalidades podem ser representados de várias formas; Engajamentos ou Testes separados são formas já existentes de representar a diferença entre seus branches de Produção, Dev e outras funcionalidades. + +Você também pode representar isso usando Ativos aninhados. Considere a seguinte árvore de Ativos: + +``` +Core Application [Organization] +└── webapp-frontend + ├── webapp-frontend/prod + └── webapp-frontend/dev + ├── webapp-frontend/dev/feature-a + └── webapp-frontend/dev/feature-b +``` + +Nesse ambiente, cada branch (`prod`, `dev`, `feature a`, `feature b`) poderia ter seus próprios Engajamentos e Testes, isolados dos demais Ativos, de modo que não deduplicam entre si. Essa configuração também pode facilitar a navegação, já que os nomes dos Ativos podem corresponder diretamente ao caminho no Git. + +### Mono-repo: componentes separados + +Se você usa um único repositório para todo o seu código, mas tem diferentes equipes contribuindo para diretórios dentro desse repositório, você pode configurar o aninhamento de Ativos para representar essa estrutura. + +``` +Core Application [Organization] +├── webapp-frontend [Parent Asset] +│ ├── mobile-ios +│ ├── mobile-android +│ └── mobile-sdk +├── webapp-backend [Parent Asset] +│ ├── database +│ └── api +└── infra [Parent Asset] + ├── docker + ├── kubernetes + └── nginx +``` + +Neste diagrama, cada elemento sob "Core Application" poderia ser registrado como um Ativo separado, com criticidade de negócio (veja: [Priority & Risk](/asset_modelling/pro_hierarchy/priority_sla/#prioritization-engines)), RBAC e Engajamentos e Testes correspondentes próprios. Você poderia continuar testando e armazenando resultados no Ativo pai (por exemplo, `webapp-backend`), mas também poderia executar testes isolados em um Ativo filho específico (por exemplo, `database`). + +### Testes de invasão: RBAC isolado + +Se você quiser armazenar resultados de testes de invasão dentro de um único ativo, mas não quiser que os testadores consigam visualizar os dados do ativo, você poderia criar ativos filhos para que cada grupo de teste envie seus resultados. + +``` +Core Application [Organization] +└── webapp-frontend [Parent Asset] + ├── Pen Test Group A + └── Pen Test Group B +``` + +Fundamentalmente, dar a um usuário acesso RBAC a um único Ativo Filho (por exemplo, `Pen Test Group A`) aqui não permite que ele visualize nenhum Achado de outros Ativos Filhos (por exemplo, `Pen Test Group B`), nem permite que ele visualize Achados no Ativo Pai (`webapp-frontend`). + +O Ativo Pai poderia conter Engajamentos representando resultados de CI/CD, Testes internos, dados históricos ou outros dados de Achados que você não deseja que terceiros consigam descobrir. Criar um Ativo Filho para resultados de testes específicos permite que sua equipe interna gere relatórios sobre esses resultados em combinação com o estado do Ativo pai. + +## Visualizando Ativos - Hierarquia + +Você pode visualizar a estrutura dos Ativos no DefectDojo e alterar as relações usando a opção Asset Hierarchy no menu. + +![image](images/asset_hierarchy.png) + +Abrir o Asset Hierarchy exibirá uma tabela com todos os seus Ativos, que pode ser filtrada. Selecionar um ou mais Ativos nessa tabela renderizará um diagrama de hierarquia. + +![image](images/asset_hierarchy_diagram.png) + +### Navegação no diagrama + +Os ícones no canto superior esquerdo do diagrama de hierarquia permitem que você aumente e diminua o zoom. Clicar e arrastar nesse diagrama permite rolar por ele. + +Cada Ativo é renderizado como um único nó nesse diagrama, que pode ser movido para fins de exibição. + +Os Ativos são conectados entre si por meio de caminhos rotulados, que representam o tipo de relação que cada um tem com o outro. Atualmente, `parent` é o único rótulo suportado. + +### Explorando nós de Ativo + +É possível interagir com cada nó de Ativo clicando nos botões azuis. Esses botões aparecem somente quando um nó de Ativo está selecionado (clicando no nó). + +![image](images/asset_hierarchy_node.png) + +* 👁️ (ícone de olho) leva você diretamente para a View de Ativo correspondente (anteriormente conhecida como View de Produto). +* ✏️ (ícone de lápis) abre um modal com o formulário Edit Asset (anteriormente conhecido como formulário Edit Product) +* ➕ (ícone de mais) permite adicionar um novo Ativo Filho a este Ativo. O Ativo não precisa estar visível no diagrama no momento, mas deve fazer parte da mesma Organização. +* ✥ (ícone de quatro setas) permite alterar o Ativo Pai do Ativo atualmente selecionado. +* 🗑️ (ícone de lixeira) permite remover a relação de Ativo pai de um Ativo. Este ícone só aparece se um Ativo já tiver um Pai. + +Se o seu diagrama exibir um Ativo com Ativos Pai não selecionados, você pode clicar no botão Load More para preencher o diagrama com o Ativo Pai (assim como os filhos desse Ativo Pai). + +![image](images/assets_loadmore.png) + +## Notas + +* Observe que os escopos de deduplicação não mudaram; os Ativos deduplicam Achados apenas dentro de si mesmos, e não consideram Achados em outros Ativos, independentemente das relações Pai/Filho. +* Os escopos de RBAC não mudaram nesse sistema; cada Ativo ainda é considerado um objeto individual para fins de atribuição de permissões. Nenhuma nova herança de RBAC foi criada. + * Conceder a um usuário acesso a uma Organização inteira ainda dará a esse usuário acesso a todos os Ativos contidos nessa Organização (assim como ocorre com os Tipos de Produto). + * Conceder a um usuário acesso a um único Ativo não dá a esse usuário acesso a nenhum Ativo Pai ou Filho relacionado, nem acesso à Organização. +* Não há limite para o número de relações Pai/Filho que podem ser criadas. Teoricamente, você poderia representar toda a estrutura de diretórios de um repositório usando Ativos separados, se quisesse. +* Relações cíclicas não são permitidas: Ativos Pai não podem ser Filhos de seus Ativos Filhos. diff --git a/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.zh-hans.md b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.zh-hans.md new file mode 100644 index 0000000000..f1aeb1753c --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.zh-hans.md @@ -0,0 +1,149 @@ +--- +title: 资产层级结构 +description: DefectDojo Pro — 产品层级结构改造 +audience: pro +weight: 1 +aliases: +- /zh-hans/en/working_with_findings/organizing_engagements_tests/pro_assets_organizations +- /zh-hans/asset_modelling/pro_hierarchy/assets_organizations +--- + +DefectDojo Pro 正在扩展产品/产品类型（Product/Product Type）对象类，以便为数据模型提供更强的灵活性。 + +## Enabling the Hierarchy Feature + +以下两部分功能相互独立，通过不同的方式进行控制。 + +### Asset Hierarchy + +**资产层级结构（Asset Hierarchy）**支持在资产（Asset）之间建立父子关系。该层级结构可以从导航栏中的**产品（Product）**选项卡查看和管理。 + +资产层级结构已正式发布（GA），在云端和本地部署的每个实例上均默认开启。无需进行任何启用操作，该功能也不再列在功能开关（Feature Flags）页面中。 + +### Label Changes (optional) + +**标签更改（Label Changes）**会在整个 UI 中将“产品类型（Product Type）”重命名为“组织（Organization）”，将“产品（Product）”重命名为“资产（Asset）”。这是与启用层级结构相独立的一个步骤，可以同时进行，也可以稍后再做。 + +自 3.0 版本起，标签更改默认处于启用状态。共有两个控制项，分别涵盖应用程序的不同部分： + +* **Pro UI**（默认界面）：超级用户可以在**设置 > 功能开关（Settings > Feature Flags）**中切换“组织/资产重新标注（Organization / Asset Relabeling）”，云端和本地部署的实例均适用。新标签会在下次页面加载时显示。请参阅[功能开关](/admin/feature_flags/pro__feature_flags/)。 +* **经典 UI 页面及生成的报告**：其标签和 URL 来自 `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` 部署设置项，该设置在 DefectDojo 启动时读取。若为本地部署，请设置该项并重启 DefectDojo。若使用 [DefectDojo Pro（云端）](/get_started/pro/cloud/)，请将您的实例 URL 通过邮件发送至 [support@defectdojo.com](mailto:support@defectdojo.com)。 + +这两项设置默认均为开启状态，且功能开关的初始值是根据部署设置生成的，因此除非您单独更改其中一项，否则两者会保持一致。如果您同时使用经典 UI 和 Pro UI，请保持这两项设置同步。 + +请注意，标签更改仅是外观上的调整：API 端点和字段名称保持不变，因此现有的自动化流程将继续正常工作。 + +## Significant Changes + +* **产品类型（Product Types）**已重命名为“组织（Organizations）”，**产品（Products）**已重命名为“资产（Assets）”。自 3.0 版本起，此名称更改默认处于启用状态。有关关闭该功能的控制项，请参阅[标签更改](#label-changes-optional)。 +* **资产（Assets）**现在可以彼此建立父子关系，从而对组织内的组成部分进行进一步细分。 + +### Organizations + +与产品类型一样，**组织（Organizations）**应被理解为一个顶层类别。您可以使用组织来划分企业的核心软件应用、部门或业务职能。 + +例如，您可以为多个代码仓库分组创建一个组织：“Core Application”“Infrastructure”“DevOps”“Analytics”“SDK”都可以各自包含多个代码仓库。 + +请注意，出于报告目的，将多个组织合并到单个文档中，要比将单个组织拆分为多个独立文档更容易实现。因此，我们建议根据团队报告的实际需要，将组织设置在尽可能细粒度的层级上。例如，如果您主要是针对某个业务部门内部的各个部门分别进行报告，就没有必要将整个大型业务部门设为一个组织。 + +### Assets + +资产旨在表示组织内部的细分单元。但与产品不同的是，资产可以嵌套，并且彼此之间可以建立父子关系。 + +## Asset Nesting Examples + +### Asset-Level Branch Representation + +开发分支和功能分支可以通过多种方式表示；使用独立的测试活动或测试就是现有的一种方式，可用来体现生产环境、开发环境以及其他功能分支之间的差异。 + +您也可以使用嵌套资产来表示这些分支。请参考以下资产树： + +``` +Core Application [Organization] +└── webapp-frontend + ├── webapp-frontend/prod + └── webapp-frontend/dev + ├── webapp-frontend/dev/feature-a + └── webapp-frontend/dev/feature-b +``` + +在此结构下，每个分支（`prod`、`dev`、`feature a`、`feature b`）都可以拥有各自独立的测试活动和测试，与其他资产相互隔离，从而不会彼此去重。这种设置也有助于导航，因为资产名称可以直接对应 Git 上的路径。 + +### Mono-Repo: Separate Components + +如果您使用单一仓库存放所有代码，但由不同团队负责该仓库内的不同目录，您可以设置资产嵌套结构来表示这种情况。 + +``` +Core Application [Organization] +├── webapp-frontend [Parent Asset] +│ ├── mobile-ios +│ ├── mobile-android +│ └── mobile-sdk +├── webapp-backend [Parent Asset] +│ ├── database +│ └── api +└── infra [Parent Asset] + ├── docker + ├── kubernetes + └── nginx +``` + +在此图中，“Core Application”下的每个元素都可以被记录为一个独立的资产，拥有各自独立的业务重要性（参见：[优先级与风险](/asset_modelling/pro_hierarchy/priority_sla/#prioritization-engines)）、RBAC 以及相应的测试活动和测试。您既可以继续在父资产（例如 `webapp-backend`）上进行测试并存储结果，也可以在特定的子资产（例如 `database`）上运行隔离的测试。 + +### Pen Tests: Isolated RBAC + +如果您希望将渗透测试结果存储在单个资产内，但又不希望测试人员能够查看该资产的数据，您可以为每个测试小组创建子资产，用于各自上传测试结果。 + +``` +Core Application [Organization] +└── webapp-frontend [Parent Asset] + ├── Pen Test Group A + └── Pen Test Group B +``` + +关键在于，在此结构下，为用户授予对单个子资产（例如 `Pen Test Group A`）的 RBAC 访问权限，并不会让该用户看到其他子资产（例如 `Pen Test Group B`）中的任何发现项，也不会让其看到父资产（`webapp-frontend`）中的发现项。 + +父资产可以包含代表 CI/CD 结果、内部测试、历史数据，或其他您不希望第三方能够发现的发现项数据的测试活动。为特定测试结果创建子资产，可以让您的内部团队在报告这些结果的同时，结合父资产的整体状态一并呈现。 + +## Visualizing Assets - Hierarchy + +您可以在 DefectDojo 中可视化资产的结构，并通过菜单中的资产层级结构选项来更改它们之间的关系。 + +![image](images/asset_hierarchy.png) + +打开资产层级结构后，将显示一个包含您所有资产的表格，该表格支持筛选。从此表格中选择一个或多个资产，将渲染出一张层级结构图。 + +![image](images/asset_hierarchy_diagram.png) + +### Diagram navigation + +层级结构图左上角的图标可用于放大和缩小。在该图表中点击并拖动，可以滚动浏览整张图。 + +每个资产在此图中都渲染为一个单独的节点，可以出于展示目的自由移动。 + +各资产之间通过带标签的路径相连接，用以表示彼此之间的关系类型。目前仅支持 `parent` 这一种标签。 + +### Exploring Asset nodes + +每个资产节点都可以通过点击蓝色按钮进行交互。这些按钮仅在选中某个资产节点（通过点击该节点）后才会出现。 + +![image](images/asset_hierarchy_node.png) + +* 👁️（眼睛图标）将直接带您进入相应的资产视图（原称为产品视图）。 +* ✏️（铅笔图标）将打开一个包含编辑资产表单的弹窗（原称为编辑产品表单） +* ➕（加号图标）允许您为该资产添加一个新的子资产。该资产不需要当前在图中可见，但必须属于同一个组织。 +* ✥（四向箭头图标）允许您更改当前所选资产的父资产。 +* 🗑️（垃圾桶图标）允许您移除某个资产的父级关系。此图标仅在该资产已经拥有父资产时才会出现。 + +如果您的图表中显示的某个资产存在未被选中的父资产，您可以点击“加载更多（Load More）”按钮，将该父资产（以及该父资产的子资产）填充到图中。 + +![image](images/assets_loadmore.png) + +## Notes + +* 请注意，去重范围并未发生变化；资产仅在其自身范围内对发现项进行去重，不会考虑其他资产中的发现项，无论父子关系如何。 +* 此系统中的 RBAC 范围并未发生变化；就权限分配而言，每个资产仍被视为一个独立的对象。系统并未新增任何 RBAC 继承机制。 + * 为用户授予对整个组织的访问权限，仍会使该用户获得对该组织内所有资产的访问权限（与产品类型的情形一致）。 + * 为用户授予对单个资产的访问权限，并不会使该用户获得对相关父资产或子资产的访问权限，也不会获得对该组织的访问权限。 +* 可以创建的父子关系数量没有限制。理论上，如果您愿意，可以使用独立的资产来表示某个仓库的整个目录结构。 +* 不允许出现循环关系：父资产不能同时是其子资产的子级。 diff --git a/docs/content/asset_modelling/PRO_hierarchy/priority_sla.it.md b/docs/content/asset_modelling/PRO_hierarchy/priority_sla.it.md new file mode 100644 index 0000000000..a0d567248f --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/priority_sla.it.md @@ -0,0 +1,271 @@ +--- +title: Assegnare Priorità, Rischio e SLA +description: Come DefectDojo classifica i tuoi Riscontri +weight: 1 +audience: pro +aliases: +- /it/en/working_with_findings/finding_priority +- /it/en/working_with_findings/priority_adjustments +--- + +![image](images/pro_finding_priority.png) + +Un approccio efficace alla gestione del rischio basata sulle vulnerabilità richiede di considerare sia il contesto di business sia la sfruttabilità tecnica. Utilizzando la funzionalità Priorità e Rischio di DefectDojo Pro, gli utenti possono ordinare automaticamente i Riscontri in un contesto significativo, garantendo che le vulnerabilità ad alto impatto possano essere affrontate per prime. + +**Priorità** è un rango numerico calcolato applicato a tutti i Riscontri nella tua istanza +DefectDojo. Consente di comprendere rapidamente le vulnerabilità nel loro contesto, specialmente all’interno di grandi organizzazioni che gestiscono le esigenze di sicurezza per molti Riscontri e/o +Prodotti. + +**Rischio** è un sistema di classificazione a 4 livelli che tiene conto in misura maggiore della sfruttabilità di un Riscontro. È pensato come una versione meno granulare e più ‘a livello esecutivo’ della Priorità. + +![image](images/pro_risk_example.png) + +I valori di Priorità e Rischio possono essere utilizzati insieme ad altri filtri per confrontare i Riscontri in qualsiasi contesto, ad esempio: + +* all’interno di un singolo Prodotto, Engagement o Test +* a livello globale in tutti i Prodotti DefectDojo +* tra alcuni Prodotti specifici + +Applicare la Priorità e il Rischio dei Riscontri aiuta il tuo team a rispondere alle +vulnerabilità più rilevanti nella tua organizzazione, e fornisce inoltre un framework utile per la +conformità agli standard normativi. + + +Scopri di più su Priorità e Rischio con l'Office Hours di maggio 2025 di DefectDojo, Inc.: + + + +## Come vengono calcolati Priorità e Rischio +L’intervallo dei valori di Priorità va da 0 a 1150. Più alto è il numero, maggiore è +l’urgenza di triage o correzione del Riscontro. + +In modo simile alla Gravità, il Rischio è classificato da Bassa -> Media -> Richiede intervento -> Urgente. Il **Rischio** tiene conto dei campi di Priorità e può quindi differire dalla Gravità segnalata da uno strumento. + +![image](images/priority-overview.png) + +## Campi di Priorità: a livello di Prodotto + +Ogni Prodotto in DefectDojo dispone di metadati che tracciano la criticità di business e i fattori +di rischio. Questi metadati vengono utilizzati per calcolare la Priorità e il Rischio dei +Riscontri associati. + +Tutti questi campi di metadati possono essere impostati nel modulo **Modifica Prodotto** per un dato Prodotto. + +![image](images/priority_edit_product.png) + +* **Criticità** può essere impostata su uno dei seguenti valori: Nessuna, Molto bassa, Bassa, Media, Alta o Molto +Alta. La Criticità è un campo soggettivo, quindi nell’assegnare questo campo considera come il +Prodotto si confronta con gli altri Prodotti della tua organizzazione. +* **Record utente** è una stima numerica dei record utente presenti in un database (o in un sistema +che può accedere a quel database). +* **Ricavi** è una stima numerica dei ricavi annuali del Prodotto. Per calcolare la Priorità, DefectDojo calcolerà una percentuale confrontando i ricavi di questo Prodotto con la somma dei ricavi di tutti i Prodotti all’interno del Tipo di Prodotto. + +Non è possibile impostare un tipo di valuta in DefectDojo, quindi assicurati che tutte le tue stime di Ricavi +usino la stessa denominazione di valuta. (“50000” potrebbe significare $50.000 +Dollari USA oppure ¥50.000 Yen giapponesi - la denominazione non ha importanza, purché +tutti i tuoi Prodotti abbiano i ricavi calcolati nella stessa valuta). +* **Pubblico esterno** è un valore vero/falso - impostalo su Vero se questo Prodotto può +essere raggiunto da un pubblico esterno. Ad esempio, clienti, utenti o chiunque +al di fuori della tua organizzazione. +* **Accessibile da Internet** è un valore vero/falso. Se questo Prodotto può connettersi alla rete +internet pubblica, dovresti impostare questo valore su Vero. + +La Priorità è un calcolo ‘relativo’, pensato per confrontare diversi Prodotti all’interno della +tua istanza DefectDojo. Sta in definitiva alla tua organizzazione decidere come questi +filtri vengono impostati. Questi valori dovrebbero essere il più accurati possibile, ma l’obiettivo principale è +mettere in evidenza i tuoi Prodotti chiave in modo da poter dare priorità alle vulnerabilità secondo la +politica della tua organizzazione, quindi questi campi non devono necessariamente essere impostati alla perfezione. + +## Campi di Priorità: a livello di Riscontro + +I Riscontri all’interno di un Prodotto possono avere metadati aggiuntivi che possono ulteriormente modificare il livello di Priorità e Rischio del Riscontro: + +* Se il Riscontro ha un **Punteggio EPSS**, questo viene aggiunto automaticamente ai Riscontri e mantenuto aggiornato per gli utenti Pro. Il **Punteggio EPSS** è il campo che contribuisce al Punteggio di Priorità — il **Percentile EPSS** viene tracciato sul Riscontro come riferimento ma non alimenta direttamente il calcolo. +* Quanti Endpoint del Prodotto sono interessati da questo Riscontro +* Se il Riscontro è In revisione oppure no +* Se il Riscontro è presente nel database KEV (Known Exploited Vulnerabilities), che viene verificato regolarmente da DefectDojo +* La Gravità segnalata dallo strumento per un Riscontro (Info, Bassa, Media, Alta, Critica) + +#### Punteggio EPSS vs Percentile EPSS + +Due Riscontri che appaiono identici sui fattori visibili (Gravità, Criticità di business, Accessibile da Internet, Exploit disponibile) possono comunque ottenere Punteggi di Priorità diversi se i loro **Punteggi EPSS** differiscono. Questo è normale: il Punteggio EPSS è un input contestuale per il calcolo. + +Il Percentile EPSS viene mostrato sul Riscontro a scopo di contesto, ma non viene utilizzato nel calcolo del Punteggio di Priorità. Se hai bisogno di confrontare due Riscontri per capire una differenza nel Punteggio di Priorità, guarda i valori del Punteggio EPSS, non quelli del Percentile. + +Il peso esatto che il Punteggio EPSS (e gli altri fattori) ha nel calcolo del Punteggio di Priorità non viene volutamente pubblicato. Se hai bisogno di influenzare quanto il Punteggio EPSS incide sul punteggio nel tuo ambiente, regola il cursore **Sfruttabilità** nel tuo [Motore di Prioritizzazione](#prioritization-engines). + + +## Calcolo del Rischio del Riscontro + +![image](images/risk_table.png) + +La colonna Rischio in una tabella dei Riscontri è un altro modo per dare rapidamente priorità ai Riscontri. Il Rischio viene calcolato utilizzando il livello di Priorità di un Riscontro, ma tiene conto in misura maggiore anche della sfruttabilità del Riscontro. È pensato come una versione meno granulare e più ‘a livello esecutivo’ della Priorità. + +I quattro livelli di Rischio assegnabili sono: + +![image](images/pro_risk_levels.png) + +L’EPSS / la sfruttabilità di un Riscontro ha un peso molto maggiore nel calcolo del Rischio. Di conseguenza, un Riscontro può avere sia una priorità alta sia un valore di rischio basso. + +Il calcolo del Rischio in sé non può attualmente essere regolato direttamente. Tuttavia, se la [Threat Intelligence](/asset_modelling/pro_hierarchy/threat_intelligence/) è abilitata, la **Soglia minima di Rischio per elementi attivamente sfruttati** ti permette di controllare l’esito per il caso più importante: un Riscontro confermato come sfruttato attivamente viene portato almeno a una fascia di Rischio a tua scelta, invece di rimanere in una fascia bassa solo perché la sua gravità di base è Bassa. Viene fornita impostata su **Richiede intervento**, e ogni Motore di Prioritizzazione può alzarla, abbassarla o azzerarla per disattivare la soglia. Vedi [la Soglia minima di Rischio per elementi attivamente sfruttati](/asset_modelling/pro_hierarchy/threat_intelligence/#the-actively-exploited-risk-floor). + +## Dashboard Priority Insights + +Gli utenti possono avere una visione a livello esecutivo di Priorità e Rischio nel proprio ambiente utilizzando +la Dashboard Priority Insights (Metriche > Priority Insights nella barra laterale) + +![image](images/priority_dashboard.png) + +Questa dashboard può essere filtrata per includere Prodotti specifici o intervalli di date. Come le +altre dashboard Pro, questa dashboard può essere esportata da DefectDojo come PDF per +produrre rapidamente un report. + +## Impostare Priorità e Rischio per la conformità normativa + +Questo è un elenco non esaustivo di standard normativi che richiedono specificamente +metodi di prioritizzazione delle vulnerabilità: + +* La conformità a [SOX (Sarbanes-Oxley Act)](https://www.sarbanes-oxley-act.com/) richiede una prioritizzazione basata sui ricavi per i +sistemi che hanno un impatto sui dati finanziari. In DefectDojo, i ricavi di un sistema possono essere inseriti +a livello di Prodotto. +* La conformità a [PCI DSS](https://www.pcisecuritystandards.org/standards/pci-dss/) richiede una prioritizzazione basata su valutazioni di rischio e criticità per gli +ambienti dei dati dei titolari di carta. La Criticità di business e il Pubblico esterno possono essere +impostati a livello di Prodotto, mentre la sincronizzazione EPSS a livello di Riscontro di DefectDojo supporta l’approccio +basato sul rischio richiesto da PCI. +* [NIST SP 800-40](https://csrc.nist.gov/pubs/sp/800/40/r4/final) è una guida alla manutenzione preventiva che richiede specificamente la +prioritizzazione delle vulnerabilità basata su impatto di business, criticità del prodotto e +fattori di accessibilità da Internet. Tutti questi possono essere impostati a livello di Prodotto di DefectDojo. +* La conformità al Controllo A.12.6.1 di [ISO 27001/27002](https://www.iso.org/standard/27001) richiede la gestione delle vulnerabilità +tecniche con una Priorità basata sulla valutazione del rischio. +* [L'articolo 32 del GDPR](https://gdpr-info.eu/art-32-gdpr/) richiede misure di sicurezza basate sul rischio - i flag di record utente e pubblico +esterno a livello di Prodotto possono aiutare a dare priorità ai sistemi della tua organizzazione +che trattano dati personali. +* La conformità a [FISMA/FedRAMP](https://help.fedramp.gov/hc/en-us) richiede il monitoraggio continuo e la correzione delle vulnerabilità basata sul rischio. + +I calcoli di Priorità e Rischio di DefectDojo Pro possono essere regolati, permettendoti di adattare DefectDojo Pro per farlo corrispondere agli standard interni della tua organizzazione per la Priorità e il Rischio dei Riscontri. + +## Motori di Prioritizzazione + +In modo simile alle configurazioni SLA, i Motori di Prioritizzazione ti permettono di impostare le regole che governano il calcolo di Priorità e Rischio. + +![image](images/priority_default.png) + +DefectDojo include un Motore di Prioritizzazione predefinito, applicato a tutti i Prodotti. Tuttavia, puoi modificare questo Motore di Prioritizzazione per cambiare la ponderazione dei moltiplicatori di **Riscontro** e **Prodotto**, il che modificherà il modo in cui vengono assegnati Priorità e Rischio dei Riscontri. + +### Moltiplicatori del Riscontro + +Otto fattori contestuali influenzano il punteggio di Priorità di un Riscontro. Tre di questi sono specifici del Riscontro, mentre gli altri cinque vengono assegnati in base al Prodotto che contiene il Riscontro. + +Puoi regolare il tuo Motore di Prioritizzazione modificando il modo in cui questi fattori vengono applicati al calcolo finale. + +![image](images/priority_sliders.png) + +Seleziona un fattore facendo clic sul pulsante, e regolando questo cursore puoi controllare la percentuale con cui un determinato fattore viene applicato. Man mano che regoli il cursore, vedrai cambiare di conseguenza le soglie di Rischio. + +#### Moltiplicatori a livello di Riscontro + +* **Gravità** - il livello di Gravità di un Riscontro +* **Sfruttabilità** - il KEV e/o il punteggio EPSS di un Riscontro +* **Endpoint** - il numero di Endpoint associati a un Riscontro + +#### Moltiplicatori a livello di Prodotto + +* **Criticità di business** - la Criticità di business del Prodotto correlato (Nessuna, Molto bassa, Bassa, Media, Alta o Molto +Alta) +* **Record utente** - il conteggio dei Record utente del Prodotto correlato +* **Ricavi** - i ricavi del Prodotto correlato, relativi ai ricavi totali del Tipo di Prodotto +* **Pubblico esterno** - se il Prodotto correlato ha o meno un pubblico esterno +* **Accessibile da Internet** - se il Prodotto correlato è o meno accessibile da Internet + +### Soglie di Rischio + +In base alla regolazione del Motore di Priorità, DefectDojo consiglierà automaticamente delle Soglie di Rischio. Tuttavia, anche queste soglie possono essere regolate e impostate sui valori che ritieni più appropriati. + +![image](images/risk_threshold.png) + +## Creare nuovi Motori di Prioritizzazione + +Puoi utilizzare più Motori di Prioritizzazione, ciascuno assegnabile a Prodotti diversi. + +![image](images/priority_engine_new.png) + +Creando un nuovo Motore di Prioritizzazione si aprirà il modulo del Motore di Prioritizzazione. Una volta inviato questo modulo, un nuovo Motore di Prioritizzazione verrà aggiunto alla tabella. + +## Assegnare i Motori di Prioritizzazione ai Prodotti + +Ogni Prodotto può avere un Motore di Prioritizzazione attualmente in uso tramite il modulo **Modifica Prodotto** per un dato Prodotto. + +![image](images/priority_chooseengine.png) + +Nota che quando il Motore di Prioritizzazione di un Prodotto viene modificato, o un Motore di Prioritizzazione viene aggiornato, il Motore di Prioritizzazione del Prodotto o il Motore di Prioritizzazione stesso verrà “Bloccato” finché il calcolo di prioritizzazione non sarà completato. + +Ogni Prodotto in DefectDojo può avere la propria configurazione di Service Level Agreement (SLA), che rappresenta i giorni a disposizione della tua organizzazione per correggere o comunque gestire un Riscontro. + +Lo SLA può essere impostato in base alla **[Gravità del Riscontro](/asset_modelling/os_hierarchy/product_hierarchy/#findings)** oppure al **[Rischio del Riscontro](/asset_modelling/pro_hierarchy/priority_sla/)** (in DefectDojo Pro). + +![image](images/sla_multiple.png) + +Gli SLA applicano un conto alla rovescia di giorni a un Riscontro in base al giorno in cui il Riscontro è stato creato in DefectDojo. Se un Riscontro non viene Chiuso entro il conto alla rovescia, il Riscontro verrà etichettato come in violazione dello SLA. + +## Lavorare con gli SLA + +Puoi utilizzare gli SLA come modo per rappresentare le politiche di correzione della tua organizzazione. Puoi anche usarli come modo per dare priorità ai Riscontri più critici e attivi da più tempo nella tua istanza DefectDojo. + +* Puoi ordinare o filtrare le tabelle dei Riscontri in base ai giorni di SLA. +* Le violazioni SLA possono essere configurate per attivare [Notifiche](/admin/notifications/about_notifications/) agli utenti DefectDojo assegnati al Prodotto correlato. +* In **DefectDojo Pro**, le prestazioni SLA vengono tracciate anche nelle Dashboard delle Metriche [Executive Insights and Remediation](/metrics_reports/pro_metrics/pro__overview/). +* La conformità SLA può anche essere mostrata in una [dashboard](/metrics_reports/dashboards/custom-dashboards/) personalizzata in **DefectDojo Pro** — ad esempio con un widget SLA Burndown o un widget Count filtrato. + +### Stato Mitigato entro lo SLA + +Se un Riscontro viene Mitigato con successo entro la scadenza dello SLA, il Riscontro registrerà un segno di spunta verde ✅ nella colonna Mitigato entro lo SLA. + +![image](images/sla_mitigated_within.png) + +Se un Riscontro è stato Mitigato, ma non prima che lo SLA venisse violato, il Riscontro registrerà una X rossa ❌ nella colonna Mitigato entro lo SLA. + +### Violazione degli SLA + +Quando lo SLA di un dato Riscontro viene violato (il Riscontro non viene Chiuso entro la scadenza dello SLA) il segno di spunta verde ✅ passerà a una X rossa ❌. Lo SLA continuerà a essere tracciato con un numero negativo, per rappresentare da quanti giorni lo SLA è stato violato. + +![image](images/sla_breached.png) + +## Gestire le configurazioni SLA (Pro) + +In DefectDojo Pro, una o più configurazioni SLA vengono gestite nella sezione **Configurazione > Service Level Agreement** della barra laterale. Puoi creare un **Nuovo Service Level Agreement** oppure lavorare con le configurazioni SLA esistenti dalla pagina **Tutti i Service Level Agreement**. + +![image](images/pro_sla_risk.png) + +Le configurazioni SLA possono essere modificate solo dai Superuser o da un utente con il [Permesso di Configurazione](/admin/user_management/user_permission_chart/#configuration-permission-chart) corrispondente. + +### Configurare lo SLA + +Le configurazioni SLA contengono i giorni assegnati a ciascun valore di **Gravità** o **Rischio** di DefectDojo. + +![image](images/pro_new_sla.png) + +Ogni Service Level Agreement può avere un nome univoco, oltre a una descrizione facoltativa. + +**Riavvia SLA alla riattivazione del Riscontro**: se abilitata, questa opzione farà ripartire da zero uno SLA quando un Riscontro viene Riaperto. Altrimenti, lo SLA si baserà sul momento in cui il Riscontro è stato creato. + +Quando modifichi uno SLA, puoi scegliere se quello SLA utilizzerà **Gravità** o **Rischio** come parametro di riferimento per assegnare i Giorni per la Correzione. Questo si fa selezionando l’opzione corrispondente nella sezione **Tipo di configurazione del Service Level** del modulo. + +Da qui, puoi impostare il numero di giorni consentiti per ciascun livello di **Gravità** o **Rischio**. Puoi anche applicare gli SLA in modo selettivo; deselezionando **Applica i giorni per i Riscontri di livello ___** puoi ignorare il calcolo SLA per quei livelli di Gravità o Rischio. + +## Applicare una configurazione SLA a un Prodotto (Pro) + +I Prodotti appena creati in DefectDojo applicheranno sempre la **Configurazione SLA predefinita**, che può essere impostata su valori diversi se lo desideri. + +Se hai delle configurazioni SLA, puoi scegliere quale di queste applicare al tuo Prodotto dal modulo **Modifica Prodotto**. + +![image](images/pro_sla_product.png) + +### Ricalcolo SLA + +Una volta selezionato un nuovo SLA per un Prodotto, tutti gli SLA dei Riscontri associati dovranno essere ricalcolati da DefectDojo. Mentre questo processo è in esecuzione, lo SLA di un Prodotto non può essere modificato. + +## Note sugli SLA + +* Gli SLA possono essere facoltativamente riavviati quando un Riscontro con [Rischio accettato](/triage_findings/findings_workflows/pro__risk_acceptance/) viene riattivato. Questo viene impostato durante la creazione dell’Accettazione del rischio, impostando il campo **Riavvia SLA Scaduto**. +* Il reimport di un Riscontro non riavvia lo SLA - gli SLA vengono sempre calcolati a partire dal momento in cui un Riscontro è stato rilevato per la prima volta, a meno che **Riavvia SLA alla riattivazione del Riscontro** non sia abilitato. +* La scadenza dell’Accettazione del rischio o la riattivazione di un Riscontro Chiuso sono gli unici modi per reimpostare o ricalcolare uno SLA per un Riscontro dopo la sua creazione (senza modificare la configurazione SLA del Prodotto). diff --git a/docs/content/asset_modelling/PRO_hierarchy/priority_sla.pt-br.md b/docs/content/asset_modelling/PRO_hierarchy/priority_sla.pt-br.md new file mode 100644 index 0000000000..ea5a9ca208 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/priority_sla.pt-br.md @@ -0,0 +1,236 @@ +--- +title: Atribuir Prioridade, Risco e SLAs +description: Como o DefectDojo classifica seus Achados +weight: 1 +audience: pro +aliases: +- /pt-br/en/working_with_findings/finding_priority +- /pt-br/en/working_with_findings/priority_adjustments +--- + +![image](images/pro_finding_priority.png) + +Um gerenciamento eficaz de vulnerabilidades baseado em risco requer uma abordagem que considere tanto o contexto de negócio quanto a explorabilidade técnica. Usando o recurso de Prioridade e Risco do DefectDojo Pro, os usuários podem organizar automaticamente os Achados em um contexto significativo, garantindo que as vulnerabilidades de alto impacto sejam tratadas primeiro. + +**Prioridade** é uma classificação numérica calculada, aplicada a todos os Achados da sua instância do DefectDojo. Ela permite entender rapidamente as vulnerabilidades em contexto, especialmente em organizações grandes que supervisionam as necessidades de segurança de muitos Achados e/ou Produtos. + +**Risco** é um sistema de classificação de 4 níveis que leva em conta a explorabilidade de um Achado em maior grau. Trata-se de uma versão menos granular e mais voltada ao 'nível executivo' da Prioridade. + +![image](images/pro_risk_example.png) + +Os valores de Prioridade e Risco podem ser usados com outros filtros para comparar Achados em qualquer contexto, como: + +* dentro de um único Produto, Engajamento ou Teste +* globalmente em todos os Produtos do DefectDojo +* entre alguns Produtos específicos + +Aplicar Prioridade e Risco aos Achados ajuda sua equipe a responder às vulnerabilidades mais relevantes da sua organização, além de fornecer uma estrutura que auxilia na conformidade com padrões regulatórios. + + +Saiba mais sobre Prioridade e Risco no Office Hours de maio de 2025 da DefectDojo, Inc.: + + + +## Como a Prioridade e o Risco são calculados +O intervalo de valores de Prioridade vai de 0 a 1150. Quanto maior o número, maior a urgência do Achado para triagem ou remediação. + +De forma semelhante à Severidade, o Risco é pontuado de Baixo -> Médio -> Requer Ação -> Urgente. **Risco** leva em conta os campos de Prioridade e, por isso, pode ser diferente da Severidade reportada por uma ferramenta. + +![image](images/priority-overview.png) + +## Campos de Prioridade: Nível de Produto + +Cada Produto no DefectDojo possui metadados que rastreiam a criticidade de negócio e os fatores de risco. Esses metadados são usados para ajudar a calcular a Prioridade e o Risco de quaisquer Achados associados. + +Todos esses campos de metadados podem ser definidos no formulário **Editar Produto** de um determinado Produto. + +![image](images/priority_edit_product.png) + +* **Criticidade** pode ser definida com qualquer um dos valores Nenhuma, Muito Baixa, Baixa, Média, Alta ou Muito Alta. Criticidade é um campo subjetivo, então, ao atribuí-lo, considere como o Produto se compara a outros Produtos da sua organização. +* **Registros de Usuários** é uma estimativa numérica de registros de usuários em um banco de dados (ou em um sistema que pode acessar esse banco de dados). +* **Receita** é uma estimativa numérica da receita anual do Produto. Para calcular a Prioridade, o DefectDojo calculará uma porcentagem comparando a receita deste Produto com a soma de todos os Produtos dentro do Tipo de Produto. + +Não é possível definir um tipo de moeda no DefectDojo, então certifique-se de que todas as suas estimativas de Receita tenham a mesma denominação monetária. ("50000" pode significar 50.000 dólares americanos ou ¥50.000 ienes japoneses - a denominação não importa, desde que todos os seus Produtos tenham a receita calculada na mesma moeda). +* **Público Externo** é um valor verdadeiro/falso - defina como Verdadeiro se este Produto puder ser acessado por um público externo. Por exemplo, clientes, usuários ou qualquer pessoa fora da sua organização. +* **Acessível pela Internet** é um valor verdadeiro/falso. Se este Produto puder se conectar à internet aberta, você deve definir esse valor como Verdadeiro. + +A Prioridade é um cálculo "relativo", destinado a comparar diferentes Produtos dentro da sua instância do DefectDojo. No fim das contas, cabe à sua organização decidir como esses filtros são definidos. Esses valores devem ser o mais precisos possível, mas o objetivo principal é destacar seus Produtos-chave para que você possa priorizar vulnerabilidades de acordo com as políticas da sua organização - portanto, esses campos não precisam necessariamente estar definidos com perfeição. + +## Campos de Prioridade: Nível de Achado + +Os Achados dentro de um Produto podem ter metadados adicionais que ajustam ainda mais o nível de Prioridade e Risco do Achado: + +* Se o Achado tem ou não uma **Pontuação EPSS** - isso é adicionado automaticamente aos Achados e mantido atualizado para usuários Pro. A **Pontuação EPSS** é o campo que contribui para a Pontuação de Prioridade — o **Percentil EPSS** é registrado no Achado apenas para referência, mas não alimenta diretamente o cálculo. +* Quantos Endpoints do Produto são afetados por este Achado +* Se um Achado está ou não Em Revisão +* Se o Achado está ou não na base KEV (Known Exploited Vulnerabilities), verificada pelo DefectDojo regularmente +* A Severidade reportada pela ferramenta para um Achado (Informativa, Baixo, Médio, Alto, Crítica) + +#### Pontuação EPSS vs. Percentil EPSS + +Dois Achados que parecem idênticos nos fatores visíveis (Severidade, Criticidade de Negócio, Acessível pela Internet, Exploit Disponível) ainda podem acabar com Pontuações de Prioridade diferentes se suas **Pontuações EPSS** forem diferentes. Isso é esperado: a Pontuação EPSS é uma entrada contextual do cálculo. + +O Percentil EPSS é exibido no Achado para contexto, mas não é utilizado no cálculo da Pontuação de Prioridade. Se você precisar comparar dois Achados para entender uma diferença na Pontuação de Prioridade, observe os valores da Pontuação EPSS, não os valores do Percentil. + +O peso exato que a Pontuação EPSS (e os outros fatores) tem no cálculo da Pontuação de Prioridade não é divulgado intencionalmente. Se você precisar influenciar o quanto a Pontuação EPSS afeta a pontuação no seu ambiente, ajuste o controle deslizante de **Explorabilidade** no seu [Mecanismo de Priorização](#prioritization-engines). + + +## Cálculo de Risco do Achado + +![image](images/risk_table.png) + +A coluna Risco em uma tabela de Achados é outra forma de priorizar rapidamente os Achados. O Risco é calculado usando o nível de Prioridade de um Achado, mas também leva em conta a explorabilidade do Achado em maior grau. Trata-se de uma versão menos granular e mais voltada ao 'nível executivo' da Prioridade. + +Os quatro níveis de Risco atribuíveis são: + +![image](images/pro_risk_levels.png) + +O EPSS / a explorabilidade de um Achado é muito mais enfatizado no cálculo de Risco. Como resultado, um Achado pode ter tanto uma prioridade alta quanto um valor de risco baixo. + +O cálculo de Risco em si atualmente não pode ser ajustado diretamente. No entanto, se a [Inteligência de Ameaças](/asset_modelling/pro_hierarchy/threat_intelligence/) estiver habilitada, o **Piso de Risco de Exploração Ativa** permite controlar o resultado para o caso mais importante: um Achado confirmado como explorado ativamente é elevado a, no mínimo, uma faixa de Risco que você escolher, em vez de permanecer em uma faixa baixa só porque sua severidade base é Baixa. Por padrão, vem definido como **Requer Ação**, e cada Mecanismo de Priorização pode elevá-lo, reduzi-lo ou desativá-lo. Consulte [o Piso de Risco de Exploração Ativa](/asset_modelling/pro_hierarchy/threat_intelligence/#the-actively-exploited-risk-floor). + +## Painel de Insights de Prioridade + +Os usuários podem ter uma visão de nível executivo da Prioridade e do Risco em seu ambiente usando o Painel de Insights de Prioridade (Metrics > Priority Insights na barra lateral) + +![image](images/priority_dashboard.png) + +Esse painel pode ser filtrado para incluir Produtos específicos ou intervalos de datas. Como os demais painéis do Pro, este painel pode ser exportado do DefectDojo como PDF para gerar um relatório rapidamente. + +## Definindo Prioridade e Risco para Conformidade Regulatória + +Esta é uma lista não exaustiva de padrões regulatórios que exigem especificamente métodos de priorização de vulnerabilidades: + +* A conformidade com a [SOX (Sarbanes-Oxley Act](https://www.sarbanes-oxley-act.com/)) exige priorização baseada em receita para sistemas que impactam dados financeiros. No DefectDojo, a receita de um sistema pode ser inserida no nível do Produto. +* A conformidade com [PCI DSS](https://www.pcisecuritystandards.org/standards/pci-dss/) exige priorização baseada em classificações de risco e criticidade para ambientes de dados de titulares de cartão. A Criticidade de Negócio e o Público Externo podem ser definidos no nível do Produto, enquanto a sincronização de EPSS no nível de Achado do DefectDojo apoia a abordagem baseada em risco do PCI. +* A [NIST SP 800-40](https://csrc.nist.gov/pubs/sp/800/40/r4/final) é um guia de manutenção preventiva que exige especificamente a priorização de vulnerabilidades com base em impacto de negócio, criticidade do produto e fatores de acessibilidade pela internet. Todos esses fatores podem ser definidos no nível de Produto do DefectDojo. +* A conformidade com o Controle A.12.6.1 da [ISO 27001/27002](https://www.iso.org/standard/27001) exige a gestão de vulnerabilidades técnicas com Prioridade baseada em avaliação de risco. +* O [Artigo 32 do GDPR](https://gdpr-info.eu/art-32-gdpr/) exige medidas de segurança baseadas em risco - os registros de usuários e os sinalizadores de público externo no nível do Produto podem ajudar a priorizar sistemas da sua organização que processam dados pessoais. +* A conformidade com [FISMA/FedRAMP](https://help.fedramp.gov/hc/en-us) exige monitoramento contínuo e remediação de vulnerabilidades baseada em risco. + +Os cálculos de Prioridade e Risco do DefectDojo Pro podem ser ajustados, permitindo adaptar o DefectDojo Pro aos padrões internos da sua organização para Prioridade e Risco de Achados. + +## Mecanismos de Priorização + +Assim como as configurações de SLA, os Mecanismos de Priorização permitem definir as regras que determinam como a Prioridade e o Risco são calculados. + +![image](images/priority_default.png) + +O DefectDojo vem com um Mecanismo de Priorização integrado, aplicado a todos os Produtos. No entanto, você pode editar esse Mecanismo de Priorização para alterar o peso dos multiplicadores de **Achado** e **Produto**, o que ajustará como a Prioridade e o Risco dos Achados são atribuídos. + +### Multiplicadores de Achado + +Oito fatores contextuais impactam a pontuação de Prioridade de um Achado. Três deles são específicos do Achado, e os outros cinco são atribuídos com base no Produto ao qual o Achado pertence. + +Você pode ajustar seu Mecanismo de Priorização controlando como esses fatores são aplicados ao cálculo final. + +![image](images/priority_sliders.png) + +Selecione um fator clicando no botão; o controle deslizante permite controlar a porcentagem com que um determinado fator é aplicado. Conforme você ajusta o controle deslizante, verá os limiares de Risco mudarem como resultado. + +#### Multiplicadores no Nível do Achado + +* **Severidade** - o nível de Severidade de um Achado +* **Explorabilidade** - o KEV e/ou a pontuação EPSS de um Achado +* **Endpoints** - a quantidade de Endpoints associados a um Achado + +#### Multiplicadores no Nível do Produto + +* **Criticidade de Negócio** - a Criticidade de Negócio do Produto relacionado (Nenhuma, Muito Baixa, Baixa, Média, Alta ou Muito Alta) +* **Registros de Usuários** - a contagem de Registros de Usuários do Produto relacionado +* **Receita** - a receita do Produto relacionado, em relação à receita total do Tipo de Produto +* **Público Externo** - se o Produto relacionado tem ou não um público externo +* **Acessível pela Internet** - se o Produto relacionado é ou não acessível pela internet + +### Limiares de Risco + +Com base no ajuste do Mecanismo de Priorização, o DefectDojo recomendará automaticamente Limiares de Risco. No entanto, esses limiares também podem ser ajustados e definidos com os valores que você considerar apropriados. + +![image](images/risk_threshold.png) + +## Criando Novos Mecanismos de Priorização + +Você pode usar vários Mecanismos de Priorização, cada um podendo ser atribuído a Produtos diferentes. + +![image](images/priority_engine_new.png) + +Criar um novo Mecanismo de Priorização abrirá o formulário do Mecanismo de Priorização. Depois que esse formulário for enviado, um novo Mecanismo de Priorização será adicionado à tabela. + +## Atribuindo Mecanismos de Priorização a Produtos + +Cada Produto pode ter um Mecanismo de Priorização em uso, definido no formulário **Editar Produto** de um determinado Produto. + +![image](images/priority_chooseengine.png) + +Observe que, quando o Mecanismo de Priorização de um Produto é alterado, ou quando um Mecanismo de Priorização é atualizado, o Mecanismo de Priorização do Produto ou o próprio Mecanismo de Priorização ficará "Bloqueado" até que o cálculo de priorização seja concluído. + +Cada Produto no DefectDojo pode ter sua própria configuração de Acordo de Nível de Serviço (SLA), que representa os dias que sua organização tem para remediar ou, de alguma forma, gerenciar um Achado. + +O SLA pode ser definido com base na **[Severidade do Achado](/asset_modelling/os_hierarchy/product_hierarchy/#findings)** ou no **[Risco do Achado](/asset_modelling/pro_hierarchy/priority_sla/)** (no DefectDojo Pro). + +![image](images/sla_multiple.png) + +Os SLAs aplicam uma contagem regressiva de dias a um Achado com base no dia em que o Achado foi criado no DefectDojo. Se um Achado não for Fechado dentro da contagem regressiva, ele será rotulado como em violação de SLA. + +## Trabalhando com SLAs + +Você pode usar os SLAs como uma forma de representar as políticas de remediação da sua organização. Também pode usá-los para priorizar os Achados mais críticos e ativos há mais tempo na sua instância do DefectDojo. + +* Você pode ordenar ou filtrar tabelas de Achados por dias de SLA. +* As violações de SLA podem ser configuradas para disparar [Notificações](/admin/notifications/about_notifications/) para os usuários do DefectDojo atribuídos ao Produto relacionado. +* No **DefectDojo Pro**, o desempenho do SLA também é acompanhado nos Painéis de Métricas de [Insights Executivos e Remediação](/metrics_reports/pro_metrics/pro__overview/). +* A conformidade com o SLA também pode ser exibida em um [painel personalizado](/metrics_reports/dashboards/custom-dashboards/) no **DefectDojo Pro** - por exemplo, com um widget de SLA Burndown ou de Contagem filtrada. + +### Status Mitigado Dentro do SLA + +Se um Achado for Mitigado com sucesso até o prazo do SLA, o Achado registrará uma marca de verificação verde ✅ na coluna Mitigado Dentro do SLA. + +![image](images/sla_mitigated_within.png) + +Se um Achado foi Mitigado, mas não antes da violação do SLA, o Achado registrará um X vermelho ❌ na coluna Mitigado Dentro do SLA. + +### Violação de SLAs + +Quando o SLA de um determinado Achado é violado (o Achado não é Fechado dentro do prazo do SLA), a marca de verificação verde ✅ muda para um X vermelho ❌. O SLA continuará sendo acompanhado com um número negativo, representando por quantos dias o SLA foi violado. + +![image](images/sla_breached.png) + +## Gerenciando Configurações de SLA (Pro) + +No DefectDojo Pro, uma ou mais Configurações de SLA são gerenciadas na seção **Configuration > Service Level Agreements** da barra lateral. Você pode criar um **Novo Acordo de Nível de Serviço** ou trabalhar com configurações de SLA existentes na página **Todos os Acordos de Nível de Serviço**. + +![image](images/pro_sla_risk.png) + +As Configurações de SLA só podem ser editadas por Superusuários ou por um usuário com a [Permissão de Configuração](/admin/user_management/user_permission_chart/#configuration-permission-chart) correspondente. + +### Configurando o SLA + +As configurações de SLA contêm os dias atribuídos a cada valor de **Severidade** ou **Risco** do DefectDojo. + +![image](images/pro_new_sla.png) + +Cada Acordo de Nível de Serviço pode ter um nome exclusivo, além de uma descrição opcional. + +**Reiniciar SLA na Reativação do Achado**: se habilitada, essa opção reiniciará o SLA do zero quando um Achado for Reaberto. Caso contrário, o SLA será baseado na data em que o Achado foi criado. + +Ao editar um SLA, você pode escolher se esse SLA usará **Severidade** ou **Risco** como referência para atribuir os Dias para Remediação. Isso é feito selecionando a opção correspondente na seção **Tipo de Configuração de Nível de Serviço** do formulário. + +A partir daí, você pode definir o número de dias permitido para cada nível de **Severidade** ou **Risco**. Você também pode aplicar os SLAs seletivamente; desmarcando a opção **Enforce ___ Finding Days**, você pode ignorar o cálculo de SLA para esses níveis de Severidade ou Risco. + +## Aplicar uma Configuração de SLA a um Produto (Pro) + +Produtos recém-criados no DefectDojo sempre aplicarão a **Configuração de SLA Padrão**, que pode ser definida com valores diferentes, se desejado. + +Se você tiver configurações de SLA, poderá escolher qual delas será aplicada ao seu Produto no formulário **Editar Produto**. + +![image](images/pro_sla_product.png) + +### Recálculo de SLA + +Depois que um novo SLA for selecionado para um Produto, todos os SLAs dos Achados associados precisarão ser recalculados pelo DefectDojo. Enquanto esse processo estiver em execução, o SLA de um Produto não poderá ser alterado. + +## Notas sobre SLAs + +* Os SLAs podem, opcionalmente, ser reiniciados quando um Achado com [Risco aceito](/triage_findings/findings_workflows/pro__risk_acceptance/) é reativado. Isso é definido ao criar a Aceitação de risco, configurando o campo **Reiniciar SLA Expirado**. +* Reimportar um Achado não reinicia o SLA - os SLAs são sempre calculados a partir do momento em que um Achado foi detectado pela primeira vez, a menos que a opção **Reiniciar SLA na Reativação do Achado** esteja habilitada. +* A expiração da Aceitação de risco ou a reativação de um Achado Fechado são as únicas formas de redefinir ou recalcular um SLA de um Achado depois de criado (sem alterar a configuração de SLA do Produto). diff --git a/docs/content/asset_modelling/PRO_hierarchy/priority_sla.zh-hans.md b/docs/content/asset_modelling/PRO_hierarchy/priority_sla.zh-hans.md new file mode 100644 index 0000000000..bdc887da65 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/priority_sla.zh-hans.md @@ -0,0 +1,236 @@ +--- +title: 分配优先级、风险和 SLA +description: DefectDojo 如何对您的发现项进行排名 +weight: 1 +audience: pro +aliases: +- /zh-hans/en/working_with_findings/finding_priority +- /zh-hans/en/working_with_findings/priority_adjustments +--- + +![image](images/pro_finding_priority.png) + +有效的风险优先漏洞管理需要一种同时考虑业务背景和技术可利用性的方法。借助 DefectDojo Pro 的优先级与风险功能,用户可以自动将发现项归入有意义的上下文中,确保优先处理高影响的漏洞。 + +**优先级**是应用于您 DefectDojo 实例中所有发现项的一个计算数值排名。它能帮助您快速在上下文中理解漏洞,尤其是在需要监管大量发现项和/或产品安全需求的大型组织中。 + +**风险**是一个 4 级排名体系,在更大程度上考虑了发现项的可利用性。它旨在成为优先级的一个精细度较低、更偏"高管层面"的版本。 + +![image](images/pro_risk_example.png) + +优先级和风险值可以与其他过滤器结合使用,在任何上下文中比较发现项,例如: + +* 在单个产品、测试活动或测试内 +* 在 DefectDojo 所有产品的全局范围内 +* 在几个特定产品之间 + +应用发现项优先级和风险有助于您的团队响应组织中最相关的漏洞,同时也提供了一个框架,帮助您符合监管标准的合规要求。 + +详细了解 DefectDojo, Inc. 2025 年 5 月的答疑时间中关于优先级和风险的内容: + + + + +## 优先级和风险如何计算 +优先级的取值范围是 0 到 1150。数值越高,该发现项进行分类处理或修复的紧迫性就越高。 + +与严重程度类似,风险的评分从低 -> 中 -> 需要处理 -> 紧急。**风险**会综合考虑优先级相关字段,因此其结果可能与工具报告的严重程度有所不同。 + +![image](images/priority-overview.png) + +## 优先级字段:产品级别 + +DefectDojo 中的每个产品都拥有用于跟踪业务关键性和风险因素的元数据。这些元数据用于帮助计算与之关联的发现项的优先级和风险。 + +所有这些元数据字段都可以在给定产品的**编辑产品**表单中进行设置。 + +![image](images/priority_edit_product.png) + +* **关键性**可以设置为无、极低、低、中、高或极高中的任意一个值。关键性是一个主观字段,因此在设置该字段时,请考虑该产品与您组织中其他产品相比的情况。 +* **用户记录数**是对数据库(或可访问该数据库的系统)中用户记录数量的数值估算。 +* **营收**是对该产品年营收的数值估算。为了计算优先级,DefectDojo 会将该产品的营收与其所属产品类型下所有产品的营收总和进行比较,从而计算出一个百分比。 + +DefectDojo 中无法设置货币类型,因此请确保您所有的营收估算都使用相同的货币单位。("50000" 既可以表示 50,000 美元,也可以表示 50,000 日元——具体是哪种货币单位并不重要,只要您所有产品的营收都以相同的货币计算即可)。 +* **外部受众**是一个真/假值——如果该产品可以被外部受众访问,请将其设置为真。例如客户、用户,或您组织之外的任何人。 +* **可通过互联网访问**是一个真/假值。如果该产品可以连接到开放互联网,您应将此值设置为真。 + +优先级是一种"相对"计算,旨在比较您 DefectDojo 实例中不同的产品。这些过滤条件最终应如何设置,取决于您的组织自行决定。这些数值应尽可能准确,但主要目标是突出您的关键产品,以便您能够根据组织的策略对漏洞进行优先级排序,因此这些字段并不一定需要设置得完美无缺。 + +## 优先级字段:发现项级别 + +产品中的发现项可以拥有额外的元数据,从而进一步调整该发现项的优先级和风险等级: + +* 该发现项是否具有**EPSS 评分**——对于 Pro 用户,该评分会自动添加到发现项中并保持最新。**EPSS 评分**是参与优先级评分计算的字段——**EPSS 百分位**会记录在发现项上供参考,但不会直接参与计算。 +* 该产品中受此发现项影响的端点数量 +* 该发现项是否处于审核中 +* 该发现项是否位于 KEV(已知被利用漏洞)数据库中,DefectDojo 会定期检查这一点 +* 工具报告的该发现项严重程度(信息、低、中、高、严重) + +#### EPSS 评分与 EPSS 百分位 + +两个在可见因素(严重程度、业务关键性、可通过互联网访问、是否存在利用方式)上看起来完全相同的发现项,如果它们的**EPSS 评分**不同,最终仍可能得到不同的优先级评分。这是预期行为:EPSS 评分是参与计算的一个上下文输入项。 + +EPSS 百分位会显示在发现项上以提供上下文信息,但它不会被优先级评分计算所使用。如果您需要比较两个发现项以理解它们优先级评分之间的差异,请查看 EPSS 评分数值,而不是百分位数值。 + +EPSS 评分(以及其他因素)在优先级评分计算中所占的具体权重是有意不公开的。如果您需要影响 EPSS 评分在您的环境中对评分的影响程度,请调整[优先级引擎](#prioritization-engines)中的**可利用性**滑块。 + + +## 发现项风险计算 + +![image](images/risk_table.png) + +发现项表格中的风险列是快速对发现项进行优先级排序的另一种方式。风险是基于发现项的优先级等级计算的,但在更大程度上也考虑了发现项的可利用性。它旨在成为优先级的一个精细度较低、更偏"高管层面"的版本。 + +可分配的四个风险等级为: + +![image](images/pro_risk_levels.png) + +在风险计算中,发现项的 EPSS/可利用性所占的权重要大得多。因此,一个发现项可能同时具有高优先级和低风险值。 + +目前风险计算本身无法直接调整。不过,如果启用了[威胁情报](/asset_modelling/pro_hierarchy/threat_intelligence/),**主动利用风险下限**功能可以让您控制最重要场景下的结果:一个被确认在野外被利用的发现项,会被提升至至少您所选择的风险区间,而不会因为其基础严重程度为低而被留在较低的区间中。该功能出厂时设置为**需要处理**,每个优先级引擎都可以将其提高、降低,或清除以关闭该下限。参见[主动利用风险下限](/asset_modelling/pro_hierarchy/threat_intelligence/#the-actively-exploited-risk-floor)。 + +## 优先级洞察仪表板 + +用户可以使用优先级洞察仪表板(侧边栏中的指标 > 优先级洞察),从高管层面查看其环境中的优先级和风险情况 + +![image](images/priority_dashboard.png) + +该仪表板可以通过过滤器筛选特定的产品或日期范围。与其他 Pro 仪表板一样,该仪表板也可以从 DefectDojo 导出为 PDF,以便快速生成报告。 + +## 为合规监管设置优先级与风险 + +以下是一份非穷尽的清单,列出了明确要求采用漏洞优先级排序方法的监管标准: + +* [SOX (Sarbanes-Oxley Act](https://www.sarbanes-oxley-act.com/)) 合规要求对影响财务数据的系统采用基于营收的优先级排序。在 DefectDojo 中,系统的营收可以在产品级别录入。 +* [PCI DSS](https://www.pcisecuritystandards.org/standards/pci-dss/) 合规要求基于风险评级以及对持卡人数据环境的关键性进行优先级排序。业务关键性和外部受众可以在产品级别设置,而 DefectDojo 的发现项级 EPSS 同步则支持 PCI 基于风险的方法。 +* [NIST SP 800-40](https://csrc.nist.gov/pubs/sp/800/40/r4/final) 是一份预防性维护指南,其中明确要求基于业务影响、产品关键性和互联网可访问性等因素对漏洞进行优先级排序。所有这些都可以在 DefectDojo 的产品级别设置。 +* [ISO 27001/27002](https://www.iso.org/standard/27001) 控制项 A.12.6.1 合规要求基于风险评估的优先级来管理技术漏洞。 +* [GDPR Article 32](https://gdpr-info.eu/art-32-gdpr/) 要求采取基于风险的安全措施——产品级别的用户记录数和外部受众标记,可以帮助您对组织中处理个人数据的系统进行优先级排序。 +* [FISMA/FedRAMP](https://help.fedramp.gov/hc/en-us) 合规要求进行持续监控以及基于风险的漏洞修复。 + +DefectDojo Pro 的优先级和风险计算是可调整的,让您能够根据组织内部对发现项优先级和风险的标准来定制 DefectDojo Pro。 + +## 优先级引擎 + +与 SLA 配置类似,优先级引擎允许您设置管理优先级和风险计算方式的规则。 + +![image](images/priority_default.png) + +DefectDojo 内置了一个优先级引擎,该引擎适用于所有产品。不过,您可以编辑该优先级引擎,更改**发现项**和**产品**乘数的权重,从而调整发现项优先级和风险的分配方式。 + +### 发现项乘数 + +有八个上下文因素会影响发现项的优先级评分。其中三个是发现项特有的,另外五个则根据持有该发现项的产品来分配。 + +您可以通过调整这些因素在最终计算中的应用方式来微调您的优先级引擎。 + +![image](images/priority_sliders.png) + +点击相应按钮以选中某个因素,调整该滑块可以控制该因素所应用的百分比。当您调整滑块时,您会看到风险阈值随之发生变化。 + +#### 发现项级别乘数 + +* **严重程度** - 发现项的严重程度等级 +* **可利用性** - 发现项的 KEV 和/或 EPSS 评分 +* **端点** - 与发现项关联的端点数量 + +#### 产品级别乘数 + +* **业务关键性** - 相关产品的业务关键性(无、极低、低、中、高或极高) +* **用户记录数** - 相关产品的用户记录数量 +* **营收** - 相关产品的营收,相对于其所属产品类型总营收的比例 +* **外部受众** - 相关产品是否拥有外部受众 +* **可通过互联网访问** - 相关产品是否可通过互联网访问 + +### 风险阈值 + +根据优先级引擎的调整情况,DefectDojo 会自动推荐风险阈值。不过,这些阈值同样可以调整,您可以将其设置为您认为合适的任何数值。 + +![image](images/risk_threshold.png) + +## 创建新的优先级引擎 + +您可以使用多个优先级引擎,每个引擎都可以分配给不同的产品。 + +![image](images/priority_engine_new.png) + +创建新的优先级引擎会打开优先级引擎表单。提交该表单后,新的优先级引擎将被添加到表格中。 + +## 将优先级引擎分配给产品 + +每个产品都可以通过给定产品的**编辑产品**表单,设置当前正在使用的优先级引擎。 + +![image](images/priority_chooseengine.png) + +请注意,当某个产品的优先级引擎被更改,或某个优先级引擎本身被更新时,该产品的优先级引擎或该优先级引擎本身将被"锁定",直到优先级计算完成为止。 + +DefectDojo 中的每个产品都可以拥有自己的服务级别协议(SLA)配置,该配置表示您的组织修复或以其他方式管理某个发现项所拥有的天数。 + +SLA 可以基于**[发现项严重程度](/asset_modelling/os_hierarchy/product_hierarchy/#findings)**或**[发现项风险](/asset_modelling/pro_hierarchy/priority_sla/)**(在 DefectDojo Pro 中)进行设置。 + +![image](images/sla_multiple.png) + +SLA 会根据发现项在 DefectDojo 中创建的日期,为该发现项设置一个天数倒计时。如果发现项未能在倒计时内被关闭,该发现项将被标记为违反 SLA。 + +## 使用 SLA + +您可以使用 SLA 来体现您组织的修复策略。您也可以使用 SLA 来对您 DefectDojo 实例中活跃时间最长、最关键的发现项进行优先级排序。 + +* 您可以按 SLA 天数对发现项表格进行排序或过滤。 +* SLA 违规可以配置为向分配到相关产品的 DefectDojo 用户触发[通知](/admin/notifications/about_notifications/)。 +* 在 **DefectDojo Pro** 中,SLA 表现也会在[高管洞察与修复](/metrics_reports/pro_metrics/pro__overview/)指标仪表板中进行跟踪。 +* 在 **DefectDojo Pro** 中,SLA 合规情况也可以呈现在自定义[仪表板](/metrics_reports/dashboards/custom-dashboards/)上——例如使用 SLA 燃尽图或经过过滤的计数小组件。 + +### "在 SLA 内已缓解"状态 + +如果某个发现项在 SLA 截止日期之前成功被缓解,该发现项将在"在 SLA 内已缓解"列中记录一个 ✅ 绿色对勾。 + +![image](images/sla_mitigated_within.png) + +如果某个发现项被缓解了,但并非在 SLA 被违反之前完成,该发现项将在"在 SLA 内已缓解"列中记录一个 ❌ 红色叉号。 + +### SLA 违约 + +当某个发现项的 SLA 被违反时(即该发现项未能在 SLA 时间范围内被关闭),✅ 绿色对勾将切换为 ❌ 红色叉号。此后 SLA 将继续以负数进行跟踪,以表示该 SLA 已被违反的天数。 + +![image](images/sla_breached.png) + +## 管理 SLA 配置(Pro) + +在 DefectDojo Pro 中,一个或多个 SLA 配置可以在侧边栏的**配置 > 服务级别协议**部分进行管理。您可以从**所有服务级别协议**页面创建**新的服务级别协议**,或对现有的 SLA 配置进行操作。 + +![image](images/pro_sla_risk.png) + +SLA 配置只能由超级用户,或拥有相应[配置权限](/admin/user_management/user_permission_chart/#configuration-permission-chart)的用户进行编辑。 + +### 配置 SLA + +SLA 配置包含分配给 DefectDojo 每个**严重程度**或**风险**值的天数。 + +![image](images/pro_new_sla.png) + +每个服务级别协议都可以拥有一个唯一的名称,以及一个可选的描述。 + +**发现项重新激活时重启 SLA**:如果启用此选项,当发现项被重新打开时,SLA 将重新开始计时。否则,SLA 将基于发现项的创建时间计算。 + +在编辑 SLA 时,您可以选择该 SLA 使用**严重程度**还是**风险**作为分配修复天数的基准。这可以通过在表单的**服务级别配置类型**部分中选择相应选项来完成。 + +在这里,您可以为每个**严重程度**或**风险**等级设置所允许的天数。您还可以有选择地强制执行 SLA;通过取消勾选**强制执行 ___ 发现项天数**,您可以忽略对相应严重程度或风险等级的 SLA 计算。 + +## 将 SLA 配置应用到产品(Pro) + +DefectDojo 中新创建的产品将始终应用**默认 SLA 配置**,如果您愿意,也可以将其设置为不同的值。 + +如果您已有多个 SLA 配置,可以在**编辑产品**表单中选择将其中哪一个应用到您的产品。 + +![image](images/pro_sla_product.png) + +### SLA 重新计算 + +一旦为某个产品选择了新的 SLA,DefectDojo 就需要重新计算所有关联发现项的 SLA。在此过程运行期间,该产品的 SLA 无法被更改。 + +## 关于 SLA 的说明 + +* 当一个[风险已接受](/triage_findings/findings_workflows/pro__risk_acceptance/)的发现项重新激活时,可以选择性地重启其 SLA。这一点是在创建风险接受时,通过设置**过期后重启 SLA**字段来完成的。 +* 重新导入某个发现项不会重启其 SLA——除非启用了**发现项重新激活时重启 SLA**,否则 SLA 始终从发现项首次被检测到的时间开始计算。 +* 在不更改产品 SLA 配置的前提下,风险接受过期或已关闭发现项的重新激活,是重置或重新计算某个发现项 SLA 的仅有的两种方式(该 SLA 一旦创建)。 diff --git a/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.it.md b/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.it.md new file mode 100644 index 0000000000..f21f823284 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.it.md @@ -0,0 +1,32 @@ +--- +title: Grado di Salute del Prodotto +description: Come DefectDojo calcola il Grado di Salute di un Prodotto +aliases: +- /it/en/working_with_findings/organizing_engagements_tests/product_health_grade +--- + +DefectDojo può calcolare un grado per i tuoi Prodotti in base alla quantità di Riscontri contenuti. I gradi vanno da A \- F. + +Nota che solo i Riscontri Attivi \& Verificati contribuiscono al Grado di un Prodotto \- i Riscontri non verificati non avranno alcun impatto. + +## Calcolo del Grado del Prodotto + +Ogni Grado del Prodotto parte da 100 (in assenza di Riscontri). + +Il calcolo del grado inizia osservando il livello di **Gravità** più alto di un Riscontro in un Prodotto, e riducendo la Salute del Prodotto a un livello base. + +| **Livello di Gravità più alto di un Riscontro** | **Grado massimo** | +| --- | --- | +| **Critica** | **40** | +| **Alta** | **60** | +| **Media** | **80** | +| **Bassa** | **95** | + +Ulteriori punti vengono poi sottratti dal Grado per ogni Riscontro aggiuntivo: + +| **Livello di Gravità di un Riscontro aggiuntivo** | **Grado ridotto di** | +| --- | --- | +| **Critica** | **5** | +| **Alta** | **3** | +| **Media** | **2** | +| **Bassa** | **1** | diff --git a/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.pt-br.md b/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.pt-br.md new file mode 100644 index 0000000000..cb77936ed8 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.pt-br.md @@ -0,0 +1,32 @@ +--- +title: Nota de Integridade do Produto +description: Como o DefectDojo calcula a Nota de Integridade do Produto +aliases: +- /pt-br/en/working_with_findings/organizing_engagements_tests/product_health_grade +--- + +O DefectDojo pode calcular uma nota para seus Produtos com base na quantidade de Achados neles contidos. As notas variam de A a F. + +Observe que apenas Achados Ativos e Verificados contribuem para a Nota do Produto - Achados não verificados não têm impacto. + +## Cálculo da Nota do Produto + +Toda Nota de Produto começa em 100 (sem Achados). + +O cálculo da nota começa observando o nível de **Severidade** mais alto de um Achado em um Produto, reduzindo a Integridade do Produto a um nível base. + +| **Nível de Severidade Mais Alto de um Achado** | **Nota Máxima** | +| --- | --- | +| **Crítica** | **40** | +| **Alto** | **60** | +| **Médio** | **80** | +| **Baixo** | **95** | + +Em seguida, mais pontos são deduzidos da Nota para cada Achado adicional: + +| **Nível de Severidade de um Achado adicional** | **Redução na Nota** | +| --- | --- | +| **Crítica** | **5** | +| **Alto** | **3** | +| **Médio** | **2** | +| **Baixo** | **1** | diff --git a/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.zh-hans.md b/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.zh-hans.md new file mode 100644 index 0000000000..df7cb581f7 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/product_health_grade.zh-hans.md @@ -0,0 +1,32 @@ +--- +title: 产品健康评级 +description: DefectDojo 如何计算产品健康评级 +aliases: +- /zh-hans/en/working_with_findings/organizing_engagements_tests/product_health_grade +--- + +DefectDojo 可以根据产品中包含的发现项数量为您的产品计算评级。评级从 A 到 F 排列。 + +请注意,只有活动且已验证的发现项才会计入产品评级——未验证的发现项不会产生影响。 + +## 产品评级计算 + +每个产品评级的起始分数为 100(在没有发现项的情况下)。 + +评级计算首先查看产品中发现项的最高严重程度,并将产品健康度降低至一个基准水平。 + +| **发现项的最高严重程度** | **最高评级** | +| --- | --- | +| **严重** | **40** | +| **高** | **60** | +| **中** | **80** | +| **低** | **95** | + +随后,每增加一个发现项都会从评级中扣除相应的分数: + +| **额外发现项的严重程度** | **扣除评级** | +| --- | --- | +| **严重** | **5** | +| **高** | **3** | +| **中** | **2** | +| **低** | **1** | diff --git a/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.it.md b/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.it.md new file mode 100644 index 0000000000..4a4998fb06 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.it.md @@ -0,0 +1,133 @@ +--- +title: Threat Intelligence +description: Evidenze di exploit e minacce come input di primo livello per Priorità + e Rischio +weight: 2 +audience: pro +--- + +DefectDojo Pro arricchisce i tuoi riscontri con **Threat Intelligence dedicata** — disponibilità di +exploit, sfruttamento noto e attività di threat actor — e la integra nel calcolo di Priorità +e Rischio. Questo va ben oltre EPSS e il flag CISA KEV. + +## Cosa ottieni + +Ogni riscontro con un CVE viene confrontato, ogni notte, con un feed di intelligence curato costruito +a partire da CISA KEV, Metasploit, Exploit-DB, template Nuclei e monitoraggio pubblico dei +proof-of-concept. Quando è presente un’evidenza di exploit, il riscontro mostra una scheda **Threat Intelligence**: + +* un badge di **maturità dell’exploit** — *Nessuna → PoC → Weaponized → Attivo in the wild* +* un **punteggio di minaccia** (0–100) +* **chip di evidenza che rimandano alla fonte** — la voce KEV (con la relativa data di inserimento), + l’uso in ransomware, un modulo Metasploit, una voce Exploit-DB, un template Nuclei e + repository pubblici di proof-of-concept +* una riga in linguaggio semplice che spiega **perché** la priorità del riscontro è aumentata + +Oltre alla scheda, l’intelligence è una superficie di lavoro in tutta l’app: + +* una **colonna Maturità dell’Exploit** nell’elenco dei riscontri — ordinabile e filtrabile + (ad esempio, “solo Weaponized o Attivo”) +* un riquadro **“Urgente e Attivamente Sfruttato”** nella dashboard Priority Layout, che conta i + riscontri a rischio Urgente attivi con sfruttamento in the wild — cliccandoci sopra si apre l’elenco + esatto dei riscontri filtrati +* un **evento di notifica** (`threat_intel_alert`) quando il CVE di un riscontro esistente acquisisce nuova + evidenza di exploit, ad esempio entrando nel CISA KEV o ottenendo un modulo Metasploit. Solo + aggiornamenti al rialzo — un’evidenza che invecchia silenziosamente non genera mai una notifica. + +## Come cambia il punteggio + +Il motore di Priorità combinava già gravità, contesto di business e un “punteggio esterno” +costruito da EPSS + KEV. La Threat Intelligence generalizza questo punteggio esterno: ogni tipo di +evidenza di exploit agisce come una soglia minima sulla scala EPSS. + +| Evidenza | Soglia minima di Priorità (equivalente EPSS) | +|---|---| +| Sfruttamento attivo + ransomware/attore nominato | 45% | +| Nel CISA KEV **e** utilizzato in ransomware | 30% | +| Nel KEV o sfruttato in the wild | 20% | +| Exploit pubblico weaponized (Metasploit / Exploit-DB) | 15% | +| Esiste un template di rilevamento Nuclei | 12% | +| Solo proof-of-concept pubblico | 8% | +| Nessuna evidenza di exploit | nessuna modifica | + +Il punteggio esterno del riscontro è il **maggiore** tra il suo valore derivato da EPSS e la +soglia minima di evidenza più alta indicata sopra — quindi l’intelligence può solo *aumentare* un +punteggio, mai abbassarlo, e un riscontro il cui EPSS supera già la soglia non viene influenzato. Il familiare +**scalare del punteggio esterno** per tipo di prodotto, nelle impostazioni del tuo Motore di Prioritizzazione, si applica a questo contributo +esattamente come si è sempre applicato a EPSS/KEV. + +### La soglia minima di Rischio per elementi attivamente sfruttati + +La tabella sopra aumenta la **Priorità**, ma in proporzione alla gravità di base di un riscontro. Questo ha +una conseguenza che vale la pena affermare chiaramente: un riscontro di gravità Bassa che porta un CVE che +viene sfruttato in the wild riceve solo un piccolo incremento assoluto, e potrebbe comunque restare in una fascia +di **Rischio** bassa. La maggior parte dei team considera questo un errore — “attivamente sfruttato” non +dovrebbe mai essere classificato come Basso. + +Esiste quindi una seconda regola, categorica. Quando la Threat Intelligence segnala uno +**sfruttamento attivo in the wild**, la Priorità del riscontro viene innalzata almeno al livello di una +fascia di Rischio configurata, indipendentemente da quanto prodotto dal solo calcolo ponderato. Viene fornita +impostata su **Richiede intervento**; ogni tipo di prodotto può alzarla a Urgente, abbassarla, o azzerarla per +disattivare la soglia, nelle impostazioni del Motore di Prioritizzazione sotto *Soglia +minima di Rischio per elementi attivamente sfruttati*. + +La soglia agisce solo in aumento — non abbassa mai un riscontro, e un riscontro che ottiene già un +punteggio più alto per conto proprio resta invariato. Poiché si applica alla Priorità, la fascia di Rischio e il +punteggio di Rischio ne conseguono automaticamente, quindi ogni elenco, filtro, grafico e calcolo SLA +vede lo stesso numero coerente. + +## Riscontri senza CVE + +La Threat Intelligence viene abbinata tramite CVE. Molti riscontri — la maggior parte dei risultati SAST, +secret, configurazioni errate, regole personalizzate — non hanno un CVE, e per essi non esiste da nessuna +parte una threat intelligence a livello di istanza di vulnerabilità (questo vale per qualsiasi fornitore, non solo per DefectDojo). +Questi riscontri: + +* mantengono **esattamente** la loro Priorità e il loro Rischio attuali — la funzionalità non abbassa mai un + punteggio +* continuano comunque a essere prioritizzati da tutti gli altri input del motore (gravità, criticità di business, + esposizione, e così via) +* mostrano “Nessuna threat intelligence disponibile — questo riscontro non ha un CVE con cui effettuare il confronto” sulla + scheda, distinto da un riscontro con CVE che semplicemente non ha ancora un exploit noto + +Una conseguenza onesta: in una coda mista, man mano che i riscontri con CVE acquisiscono evidenza di exploit, +i riscontri senza CVE scendono in classifica *relativa* anche se il loro punteggio resta invariato. + +## Fiducia e stabilità del punteggio + +* **Intelligence firmata.** Ogni bundle notturno è firmato crittograficamente da DefectDojo; + la tua istanza rifiuta dati manomessi o non firmati. Le istanze air-gapped importano lo stesso + bundle firmato con un passaggio di verifica offline. +* **Nessuna oscillazione del punteggio.** Gli aggiornamenti di evidenza vengono applicati la notte in cui + compaiono. Se una fonte *perde* un’evidenza, i punteggi restano stabili per una finestra di + stabilità (14 giorni per impostazione predefinita) — un intoppo del feed non fa mai oscillare la tua coda, e + le vere de-escalation si assestano silenziosamente al termine della finestra. +* **Supporto air-gapped.** Il bundle giornaliero (inclusi i dati EPSS) può essere trasferito e + importato offline, in modo che le istanze isolate ricevano lo stesso arricchimento. + +## Distribuzioni self-hosted + +Le istanze DefectDojo Cloud non richiedono alcuna configurazione. Le istanze self-hosted hanno tre opzioni: + +* **Connessa (predefinita).** L’istanza scarica ogni notte il bundle firmato da + `intel.defectdojo.com` via HTTPS. Questa è una destinazione che nessun’altra funzionalità di DefectDojo + utilizza, quindi di solito deve essere consentita esplicitamente: apri la porta 443 in uscita verso quell’host, e su + Kubernetes aggiungila alla tua policy di rete in uscita (egress). Nota che il recupero viene eseguito sul **worker + Celery**, non sul pod web, quindi anche le impostazioni proxy devono raggiungere quel workload. +* **Mirror interno.** Punta `DD_THREAT_INTEL_BUNDLE_URL` (e gli URL corrispondenti di digest e + firma) verso una posizione all’interno della tua rete che sincronizzi tu stesso. La verifica della firma + si applica comunque, quindi un mirror non può alterare i dati. +* **Air-gapped.** Trasferisci il bundle e la sua firma manualmente e importali con + `manage.py load_threat_intel_bundle --file `. La firma viene verificata all’importazione. + +Se l’istanza non riesce a raggiungere il feed, la funzionalità fallisce in modo controllato: l’esecuzione +viene registrata come fallita e i tuoi punteggi ed evidenze esistenti restano esattamente come erano. Nulla si +degrada tranne la freschezza dell’intelligence. + +## Abilitarla + +La funzionalità viene fornita disattivata per impostazione predefinita. Gli amministratori possono abilitarla +direttamente, oppure eseguirla prima in **modalità shadow** — che calcola i punteggi ipotetici senza +modificare nulla in produzione e produce un report di scostamento che mostra esattamente quali riscontri +si sposterebbero — prima di attivarla. Contatta il supporto o consulta il runbook operativo per il rollout +consigliato su istanze di grandi dimensioni. diff --git a/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.pt-br.md b/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.pt-br.md new file mode 100644 index 0000000000..cda2902427 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.pt-br.md @@ -0,0 +1,128 @@ +--- +title: Inteligência de Ameaças +description: Evidências de exploração e ameaças como entrada de primeira classe para + Prioridade e Risco +weight: 2 +audience: pro +--- + +O DefectDojo Pro enriquece seus achados com **inteligência de ameaças dedicada** — disponibilidade de exploit, exploração conhecida e atividade de agentes de ameaça — e leva isso em conta na Prioridade e no Risco. Isso vai muito além do EPSS e do sinalizador KEV da CISA. + +## O que você obtém + +Todo achado com um CVE é comparado, todas as noites, com um feed de inteligência selecionado, construído a partir do CISA KEV, Metasploit, Exploit-DB, templates do Nuclei e rastreamento de provas de conceito públicas. Quando há evidência de exploração, o achado exibe um card de **Inteligência de Ameaças**: + +* um selo de **maturidade de exploração** — *Nenhum → PoC → Armado → Ativo em ambiente real* +* uma **pontuação de ameaça** (0–100) +* **chips de evidência que linkam para o comprovante** — a entrada no KEV (com sua data de listagem), + uso em ransomware, um módulo do Metasploit, uma entrada no Exploit-DB, um template do Nuclei e + repositórios públicos de prova de conceito +* uma linha em linguagem simples explicando **por que** a prioridade do achado aumentou + +Além do card, essa inteligência é uma camada funcional em todo o aplicativo: + +* uma **coluna Maturidade de Exploração** na lista de achados — ordenável e filtrável + (por exemplo, "somente Armado ou Ativo") +* um bloco **"Urgente e Ativamente Explorado"** no painel de Layout de Prioridade, contabilizando + achados ativos de risco Urgente com exploração em ambiente real — ao clicar, abre a + lista exata de achados filtrados +* um **evento de notificação** (`threat_intel_alert`) quando o CVE de um achado existente ganha nova + evidência de exploração, como entrar no CISA KEV ou ganhar um módulo do Metasploit. Apenas atualizações + para cima — evidências que silenciosamente perdem validade nunca geram notificação. + +## Como isso muda a pontuação + +O mecanismo de Prioridade já combinava severidade, contexto de negócio e uma "pontuação externa" +construída a partir de EPSS + KEV. A inteligência de ameaças generaliza essa pontuação externa: cada tipo +de evidência de exploração atua como um piso na escala do EPSS. + +| Evidência | Piso de Prioridade (equivalente a EPSS) | +|---|---| +| Exploração ativa + ransomware/agente nomeado | 45% | +| No CISA KEV **e** usado em ransomware | 30% | +| No KEV ou explorado em ambiente real | 20% | +| Exploit público armado (Metasploit / Exploit-DB) | 15% | +| Existe template de detecção do Nuclei | 12% | +| Apenas prova de conceito pública | 8% | +| Sem evidência de exploração | sem alteração | + +A pontuação externa do achado é o **maior** valor entre o derivado do EPSS e o piso de evidência mais alto +acima — portanto, a inteligência só *aumenta* uma pontuação, nunca a reduz, e um achado cujo EPSS já +exceda o piso não é afetado. O já conhecido **escalar de pontuação externa** por tipo de produto, nas +configurações do seu Mecanismo de Priorização, dimensiona essa contribuição exatamente como sempre +dimensionou o EPSS/KEV. + +### O piso de Risco de exploração ativa + +A tabela acima aumenta a **Prioridade**, mas proporcionalmente à severidade base de um achado. Isso tem +uma consequência que vale a pena declarar claramente: um achado de severidade Baixa com um CVE que está +sendo explorado em ambiente real recebe apenas um pequeno aumento absoluto, e ainda pode permanecer em +uma faixa de **Risco** baixa. A maioria das equipes considera isso errado — "ativamente explorado" nunca +deveria ser classificado como Baixo. + +Por isso, existe uma segunda regra, categórica. Quando a inteligência de ameaças reporta **exploração +ativa em ambiente real**, a Prioridade do achado é elevada a, no mínimo, o nível de uma faixa de Risco +configurada, independentemente do que o cálculo ponderado sozinho produziria. Por padrão, vem definido +como **Requer Ação**; cada tipo de produto pode elevá-lo para Urgente, reduzi-lo ou desativá-lo, nas +configurações do Mecanismo de Priorização, em *Piso de Risco de Exploração Ativa*. + +O piso só eleva — nunca move um achado para baixo, e um achado que já pontua mais alto por conta própria +permanece inalterado. Como isso se aplica à Prioridade, a faixa de Risco e a pontuação de Risco decorrem +automaticamente dela, de modo que toda lista, filtro, gráfico e cálculo de SLA enxergam o mesmo número +consistente. + +## Achados sem CVE + +A inteligência de ameaças é correlacionada por CVE. Muitos achados — a maioria dos resultados de SAST, +segredos, configurações incorretas, regras personalizadas — não têm CVE, e não existe inteligência de +ameaças por instância de vulnerabilidade para eles em lugar nenhum (isso vale para todos os fornecedores, +não só o DefectDojo). Esses achados: + +* mantêm sua Prioridade e Risco atuais **exatos** — o recurso nunca reduz uma pontuação +* ainda são priorizados por todas as outras entradas do mecanismo (severidade, criticidade de negócio, + exposição, e assim por diante) +* exibem "Nenhuma inteligência de ameaças disponível — este achado não tem CVE para correlacionar" no + card, diferente de um achado com CVE que simplesmente ainda não tem exploit conhecido + +Uma consequência honesta: em uma fila mista, à medida que achados com CVE ganham evidência de exploração, +os achados sem CVE caem em classificação *relativa*, mesmo que sua pontuação permaneça inalterada. + +## Confiança e estabilidade da pontuação + +* **Inteligência assinada.** Todo pacote noturno é assinado criptograficamente pelo DefectDojo; sua + instância recusa dados adulterados ou não assinados. Instâncias air-gapped importam o mesmo pacote + assinado com uma etapa de verificação offline. +* **Sem oscilação de pontuação.** As atualizações de evidência são aplicadas na mesma noite em que + surgem. Se uma fonte *perde* uma evidência, as pontuações permanecem estáveis por uma janela de + estabilidade (14 dias por padrão) — uma falha pontual no feed nunca desestabiliza sua fila, e + desescaladas genuínas se acomodam silenciosamente após a janela. +* **Suporte a air-gapped.** O pacote diário (incluindo dados de EPSS) pode ser transferido e importado + offline, para que instâncias isoladas recebam o mesmo enriquecimento. + +## Implantações self-hosted + +Instâncias do DefectDojo Cloud não precisam de nenhuma configuração. Instâncias self-hosted têm três +opções: + +* **Conectado (padrão).** A instância busca o pacote assinado todas as noites em `intel.defectdojo.com` + via HTTPS. Esse é um destino que nenhum outro recurso do DefectDojo utiliza, então geralmente precisa + ser liberado explicitamente: abra a porta 443 de saída para esse host e, no Kubernetes, adicione-o à + sua política de rede de egress. Observe que a busca é executada no **worker do Celery**, não no pod + web, então as configurações de proxy também precisam alcançar essa carga de trabalho. +* **Espelho interno.** Aponte `DD_THREAT_INTEL_BUNDLE_URL` (e as URLs correspondentes de digest e + assinatura) para um local dentro da sua rede que você mesmo sincroniza. A verificação de assinatura + continua se aplicando, então um espelho não pode alterar os dados. +* **Air-gapped.** Transfira o pacote e sua assinatura manualmente e importe-os com + `manage.py load_threat_intel_bundle --file `. A assinatura é verificada na importação. + +Se a instância não conseguir acessar o feed, o recurso falha de forma segura (fail closed): a execução é +registrada como falha, e suas pontuações e evidências existentes permanecem exatamente como estavam. Nada +se degrada, exceto a atualidade da inteligência. + +## Habilitando o recurso + +O recurso vem desativado por padrão. Os administradores podem habilitá-lo diretamente ou, primeiro, +executá-lo em **modo shadow** — que calcula as pontuações que seriam aplicadas sem alterar nada em +produção e produz um relatório de divergência mostrando exatamente quais achados mudariam — antes de +ativá-lo de fato. Entre em contato com o suporte ou consulte o runbook de operações para a implantação +recomendada em instâncias grandes. diff --git a/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.zh-hans.md b/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.zh-hans.md new file mode 100644 index 0000000000..94c801df36 --- /dev/null +++ b/docs/content/asset_modelling/PRO_hierarchy/threat_intelligence.zh-hans.md @@ -0,0 +1,77 @@ +--- +title: 威胁情报 +description: 将利用证据和威胁证据作为优先级与风险计算的一等输入 +weight: 2 +audience: pro +--- + +DefectDojo Pro 通过**专用威胁情报**——利用可用性、已知利用情况以及威胁行为者活动——来丰富您的发现项,并将其纳入优先级与风险的计算中。这远远超出了 EPSS 和 CISA KEV 标记所能提供的信息。 + +## 您将获得什么 + +每个带有 CVE 的发现项都会在每晚与一个精心整理的情报源进行匹配,该情报源整合自 CISA KEV、Metasploit、Exploit-DB、Nuclei 模板以及公开的概念验证(PoC)跟踪数据。当存在利用证据时,该发现项会显示一张**威胁情报**卡片: + +* 一个**利用成熟度**徽章——*无 → PoC → 武器化 → 野外活跃利用* +* 一个**威胁评分**(0-100) +* **可链接到原始凭证的证据标签**——KEV 条目(附带其登记日期)、用于勒索软件、Metasploit 模块、Exploit-DB 条目、Nuclei 模板,以及公开的概念验证代码仓库 +* 一行通俗易懂的说明,解释该发现项的优先级为**何**上升 + +除了该卡片之外,这些情报还会作用于整个应用程序的多个界面: + +* 发现项列表中的**利用成熟度列**——可排序和筛选(例如,"仅显示武器化或活跃利用") +* 优先级布局仪表板上的**"紧急且正在被主动利用"**图块,统计存在野外利用行为的活动紧急风险发现项——点击即可打开对应的已筛选发现项列表 +* 当现有发现项的 CVE 获得新的利用证据时(例如被列入 CISA KEV 或获得 Metasploit 模块),会触发一个**通知事件**(`threat_intel_alert`)。仅在证据升级时触发——证据悄然过期时不会发出通知。 + +## 这如何改变评分方式 + +优先级引擎此前已经综合了严重程度、业务背景以及由 EPSS + KEV 构成的"外部评分"。威胁情报对这一外部评分进行了泛化:每一种利用证据都会在 EPSS 量表上充当一个下限值。 + +| Evidence | Priority floor (EPSS-equivalent) | +|---|---| +| 主动利用 + 勒索软件/已命名威胁行为者 | 45% | +| 位于 CISA KEV **且**用于勒索软件 | 30% | +| 位于 KEV 或在野外被利用 | 20% | +| 武器化的公开利用工具(Metasploit / Exploit-DB) | 15% | +| 存在 Nuclei 检测模板 | 12% | +| 仅存在公开概念验证 | 8% | +| 无利用证据 | 无变化 | + +发现项的外部评分取其 EPSS 推导值与上述最高证据下限中的**较大者**——因此威胁情报只会*提高*评分,绝不会降低评分,而 EPSS 已经超过下限的发现项则不受影响。优先级引擎设置中您熟悉的按产品类型划分的**外部评分系数**,会按照它一贯用于缩放 EPSS/KEV 的方式,同样缩放这一贡献。 + +### 主动利用风险下限 + +上表提高的是**优先级**,但提高幅度与发现项的基础严重程度成比例。这会带来一个值得明确说明的后果:一个携带正在被野外利用的 CVE 的低严重程度发现项,只会获得较小的绝对提升幅度,仍可能落在较低的**风险**区间中。大多数团队认为这是不合理的——"正在被主动利用"绝不应该被归入"低"这一档。 + +因此还有第二条分类规则。当威胁情报报告存在**野外主动利用**时,无论加权计算本身得出的结果如何,该发现项的优先级都会被提升至至少达到您所配置的风险区间。该功能出厂时设置为**需要处理**;每种产品类型都可以在优先级引擎设置的*主动利用风险下限*中,将其提高至紧急、降低,或清除以关闭该下限功能。 + +该下限只会向上调整——它绝不会把发现项往下调,而对于本身评分已经更高的发现项也不会产生影响。由于它作用于优先级,风险区间和风险评分会随之自动派生,因此每一个列表、筛选器、图表和 SLA 计算所看到的都是同一个一致的数值。 + +## 没有 CVE 的发现项 + +威胁情报是按 CVE 进行匹配的。许多发现项——大多数 SAST 结果、密钥泄露、错误配置、自定义规则——都没有 CVE,而且目前任何地方都不存在针对这些漏洞实例的威胁情报(这一点适用于所有供应商,而不仅仅是 DefectDojo)。这些发现项: + +* 会保持其**当前**的优先级和风险**不变**——该功能绝不会降低评分 +* 仍会依据引擎的其他所有输入(严重程度、业务关键性、暴露程度等)进行优先级排序 +* 会在卡片上显示"暂无可用的威胁情报——该发现项没有可匹配的 CVE",这与"有 CVE 但目前尚无已知利用方式"的发现项有所区别 + +一个需要如实说明的后果是:在一个混合队列中,随着带有 CVE 的发现项不断获得利用证据,没有 CVE 的发现项即便自身评分未变,其*相对*排名也会随之下降。 + +## 信任与评分稳定性 + +* **已签名的情报。** 每份每晚更新的数据包都经过 DefectDojo 的加密签名;您的实例会拒绝任何被篡改或未签名的数据。物理隔离(air-gapped)实例通过离线验证步骤导入同一份已签名的数据包。 +* **评分不会反复波动。** 证据升级会在其出现的当晚生效。如果某个来源*撤销*了证据,评分会在一个稳定窗口期内(默认 14 天)保持不变——数据源的一次小故障不会让您的队列出现反复,而真正的降级会在窗口期结束后悄然生效。 +* **支持物理隔离环境。** 每日数据包(包括 EPSS 数据)可以离线传输和导入,因此隔离环境的实例也能获得相同的信息增强。 + +## 自托管部署 + +DefectDojo Cloud 实例无需任何配置。自托管实例有三种选择: + +* **已连接(默认)。** 实例每晚通过 HTTPS 从 `intel.defectdojo.com` 获取已签名的数据包。这是一个 DefectDojo 其他功能都不会用到的目标地址,因此通常需要显式放行:对该主机开放出站 443 端口,在 Kubernetes 上还需将其加入您的出站(egress)网络策略。请注意,该获取操作运行在 **Celery worker** 上,而不是 Web pod 上,因此代理设置也必须能够覆盖到该工作负载。 +* **内部镜像。** 将 `DD_THREAT_INTEL_BUNDLE_URL`(以及对应的摘要和签名 URL)指向您网络内部由您自行同步的位置。签名验证依然会执行,因此镜像无法篡改数据。 +* **物理隔离。** 手动传输数据包及其签名,并使用 `manage.py load_threat_intel_bundle --file ` 进行导入。签名会在导入时进行验证。 + +如果实例无法访问该情报源,该功能会采取失败关闭(fail closed)的方式:本次运行会被记录为失败,而您现有的评分和证据将保持原样不变。除了情报的新鲜度之外,不会有任何其他功能受到影响。 + +## 启用该功能 + +该功能默认处于关闭状态。管理员可以直接启用它,也可以先以**影子模式**运行——该模式会计算出可能产生的评分,但不会对任何线上数据进行实际更改,并会生成一份漂移报告,准确显示哪些发现项会发生变动——然后再正式启用。如需了解在大型实例上推荐的推广方式,请联系支持团队或参阅运维手册。 diff --git a/docs/content/asset_modelling/PRO_surveys/PRO__surveys.it.md b/docs/content/asset_modelling/PRO_surveys/PRO__surveys.it.md new file mode 100644 index 0000000000..412ae55a30 --- /dev/null +++ b/docs/content/asset_modelling/PRO_surveys/PRO__surveys.it.md @@ -0,0 +1,147 @@ +--- +title: Sondaggi +description: Comprendere i Sondaggi in DefectDojo Pro +audience: pro +weight: 2 +--- + +In DefectDojo, un modello di Sondaggio è un insieme riutilizzabile di Domande che serve a raccogliere informazioni da sviluppatori, team e stakeholder sia interni che esterni. Può essere utilizzato per raccogliere input prima dell'inizio dei lavori, garantire l'allineamento tra persone e team man mano che il lavoro procede, e consentire un'analisi retrospettiva una volta completato il lavoro. + +In DefectDojo, il sistema dei Sondaggi è composto da tre elementi: +- **Modelli di Sondaggio**, che raggruppano e ordinano le Domande. +- **Distribuzioni del Sondaggio**, ovvero le istanze attive che raccolgono le risposte. +- **Risposte**, ovvero le risposte inviate dagli Utenti. + +La creazione di un modello di Sondaggio non lo rende automaticamente disponibile per la raccolta di risposte. Per raccogliere risposte, un modello di Sondaggio deve essere distribuito. + +## Permessi + +La sezione Sondaggi nella barra laterale è visibile solo agli Utenti con stato di Superuser, e solo i Superuser possono creare modelli di Sondaggio, creare Domande e distribuire i Sondaggi. + +Gli Utenti privi dello stato di Superuser possono comunque rispondere ai Sondaggi condivisi con loro, ma non possono crearli né gestirli, né gestire le Domande associate. + +## Accesso a Sondaggi e Domande + +Gli Utenti con stato di Superuser possono accedere a Sondaggi e Domande dalla barra laterale facendo clic sull'opzione **Surveys**. Il sottomenu fornisce accesso a **Tutti i Sondaggi** e **Tutte le Domande**, oltre all'opzione per creare nuovi Sondaggi e Domande. + +![immagine](images/pq_ss1.png) + +### Accesso ai Sondaggi + +La vista Tutti i Sondaggi include una tabella contenente tutti i modelli di Sondaggio, con relativo ID, nome, descrizione e stato attivo. La tabella può essere filtrata utilizzando parole chiave e può essere riorganizzata facendo clic sull'intestazione di ciascuna colonna. + +### Accesso alle Domande + +La vista Tutte le Domande include una tabella di Domande che possono essere aggiunte a un Sondaggio. La tabella può essere filtrata utilizzando parole chiave e può essere riorganizzata facendo clic sull'intestazione di ciascuna colonna. + +## Gestione dei modelli di Sondaggio + +### Creazione di modelli di Sondaggio + +I modelli di Sondaggio possono essere creati facendo clic su **Nuovo Sondaggio** nella barra laterale, oppure facendo clic sul pulsante **Nuovo Sondaggio** nella parte superiore della vista Tutti i Sondaggi. + +![immagine](images/pq_ss2.png) + +Prima della creazione, al modello di Sondaggio devono essere assegnati un nome e una descrizione, oltre ad almeno una Domanda scelta dal menu a tendina. + +#### Aggiungere Domande a un modello di Sondaggio esistente + +Per aggiungere Domande a un modello di Sondaggio esistente, fai clic sull'icona a kebab ⋮ a sinistra del Sondaggio desiderato, fai clic su **Modifica Sondaggio**, seleziona dal menu a tendina eventuali nuove Domande da aggiungere al Sondaggio, quindi fai clic su **Invia**. + +Come buona pratica, si raccomanda vivamente di evitare di modificare o aggiungere Domande a un modello di Sondaggio mentre ha distribuzioni attive. L'aggiunta di nuove Domande non influirà sulle Risposte esistenti, ma tali Risposte saranno state inviate senza rispondere alle Domande appena aggiunte, il che potrebbe determinare dati incompleti. + +### Creazione di Domande + +Analogamente ai modelli di Sondaggio, le Domande possono essere create facendo clic su **Nuova Domanda** nella barra laterale, oppure facendo clic sul pulsante **Nuova Domanda** nella parte superiore della vista Tutte le Domande. + +#### Tipi di Domanda + +Quando si crea una nuova Domanda, questa può essere formattata come domanda testuale o come domanda a scelta multipla selezionando **Domanda testuale** o **Domanda a scelta multipla** nella parte superiore della vista Nuova Domanda. + +![immagine](images/pq_ss3.png) + +#### Ordine delle Domande + +Determina l'ordine di una Domanda assegnandole un numero d'ordine. Ad esempio, se una Domanda ha il valore 1 nel campo Ordine, quella Domanda apparirà sopra una Domanda con il valore 2 nel campo Ordine. + +#### Risposte opzionali + +Sia le domande testuali che le domande a scelta multipla possono essere contrassegnate come **Opzionale** facendo clic sulla casella di controllo corrispondente. + +#### Consentire risposte multiple + +È possibile aggiungere un numero illimitato di risposte potenziali a una domanda a scelta multipla. Selezionando la casella di controllo **Consenti selezioni multiple** è possibile selezionare più risposte (disponibile solo per le domande a scelta multipla). + +### Modifica delle Domande + +Per modificare una Domanda, vai alla vista Tutte le Domande, fai clic sull'icona a kebab ⋮ a sinistra della Domanda da modificare, fai clic su Modifica Domanda, apporta la modifica desiderata e finalizza la modifica facendo clic su Invia. Le Domande non possono essere eliminate. + +![immagine](images/pq_ss4.png) + +È importante evitare di modificare Domande che fanno parte di Questionari attivi o di aggiungere Domande a Questionari attivi. Farlo non influirà sulle risposte raccolte in precedenza, ma potrebbe determinare dati incompleti o inaffidabili. + +## Distribuzione dei Sondaggi + +Una volta creato con successo un modello di Sondaggio, distribuire un Sondaggio crea un'istanza attiva che accetta risposte. + +Per distribuire un Sondaggio, vai alla vista Tutti i Sondaggi, fai clic sull'icona a kebab ⋮ a sinistra del Sondaggio da distribuire, fai clic su **Apri Sondaggio**, imposta la data di scadenza e fai clic su Invia. + +Se desideri distribuire nuovamente lo stesso Sondaggio, segui la stessa procedura. Tutte le distribuzioni appariranno nella tabella Istanze Sondaggio aperte nella vista del Sondaggio, e possono essere distinte in base a ID, orario di creazione e data di scadenza. + +![immagine](images/pq_ss10.png) + +Un Sondaggio si chiuderà alla data scelta, allo stesso orario in cui è stato distribuito. Ad esempio, se distribuisci un Sondaggio alle 8:00 del 1° febbraio 2026 e programmi la chiusura per il 1° marzo 2026, il sondaggio si chiuderà alle 8:00 del mattino del 1° marzo 2026. + +Una volta aperto un Sondaggio, la sua data e ora di scadenza non possono essere modificate. Se è necessario un intervallo di tempo diverso, è necessario creare una nuova distribuzione. + +Una volta trascorsa una data di scadenza, non sarà più possibile inviare risposte a quella distribuzione del Sondaggio, ma la distribuzione continuerà a comparire nella tabella Istanze Sondaggio aperte nella vista di quel Sondaggio. + +#### Condivisione di un Sondaggio + +Una volta distribuito, un Sondaggio può essere condiviso con altri Utenti facendo clic sull'icona ↗ a sinistra del Sondaggio all'interno della tabella Istanze Sondaggio aperte nella vista del modello di Sondaggio. Questo mostrerà un link univoco per quella distribuzione, che può essere copiato e condiviso con i destinatari previsti. + +![immagine](images/pq_ss5.png) + +![immagine](images/pq_ss9.png) + +#### Chiusura di un Sondaggio + +Per chiudere un Sondaggio, fai clic sulla **X** rossa a sinistra del Sondaggio all'interno della tabella Istanze Sondaggio aperte nella vista del modello di Sondaggio. + +![immagine](images/pq_ss13.png) + +Come indicato nella successiva sezione Risposte, questo impedirà solo l'invio di ulteriori risposte. Le risposte inviate in precedenza rimarranno visibili nella tabella Risposte in fondo alla vista del modello di Sondaggio. + +## Rispondere ai Sondaggi + +Per rispondere a un Sondaggio, agli utenti non Superuser deve essere condiviso direttamente il link, seguendo le istruzioni riportate nella sezione [Condivisione di un Sondaggio](#sharing-a-survey) sopra. Anche i Superuser possono rispondere utilizzando lo stesso link. + +#### Abilitazione delle risposte anonime + +Per impostazione predefinita, i Sondaggi sono accessibili solo agli Utenti di DefectDojo. Per consentire a soggetti esterni di rispondere ai Sondaggi di DefectDojo, assicurati che l'opzione **Abilita risposte anonime ai Sondaggi** sia attivata nelle **Impostazioni di sistema**, disponibili in **Impostazioni > Sistema** nella barra laterale (all'interno del sottomenu **Impostazioni Pro** sulle istanze che utilizzano ancora il layout di menu precedente). + +![immagine](images/pq_ss6.png) + +Le risposte esterne appariranno come anonime, poiché non è presente alcun ID utente DefectDojo associato alla risposta. + +Se l'ambito di un Sondaggio include sia Utenti interni che esterni, specifica il nome dell'Engagement nella descrizione al momento della creazione, il che consentirà di filtrare i risultati. + +![immagine](images/pq_ss7.png) + +![immagine](images/pq_ss8.png) + +## Gestione delle Risposte + +Un singolo modello di Sondaggio può essere distribuito più volte contemporaneamente. Tutte le risposte alle diverse distribuzioni dello stesso modello di Sondaggio verranno visualizzate insieme nella tabella Risposte in fondo alla vista di quel Sondaggio. + +![immagine](images/pq_ss11.png) + +Anche dopo che una distribuzione di un Sondaggio è scaduta o è stata chiusa, le relative risposte rimangono visibili nella tabella Risposte in fondo alla vista del Sondaggio, a condizione che il modello di Sondaggio stesso non sia stato eliminato. Queste risposte sono permanenti e non possono essere rimosse. + +Come mostrato nell'immagine seguente, non ci sono attualmente distribuzioni di Sondaggi aperte, eppure le risposte delle distribuzioni precedenti sono ancora presenti nella tabella Risposte. + +![immagine](images/pq_ss12.png) + +### Eliminazione dei modelli di Sondaggio + +Per eliminare un modello di Sondaggio, vai alla vista Tutti i Sondaggi, fai clic sull'icona a kebab ⋮ a sinistra del Sondaggio scelto, quindi fai clic su **Elimina Sondaggio**. Questa operazione elimina definitivamente il modello di Sondaggio e tutte le distribuzioni e Risposte associate. Questa azione non può essere annullata. diff --git a/docs/content/asset_modelling/PRO_surveys/PRO__surveys.pt-br.md b/docs/content/asset_modelling/PRO_surveys/PRO__surveys.pt-br.md new file mode 100644 index 0000000000..5b885ddcea --- /dev/null +++ b/docs/content/asset_modelling/PRO_surveys/PRO__surveys.pt-br.md @@ -0,0 +1,147 @@ +--- +title: Pesquisas +description: Entendendo as Pesquisas no DefectDojo Pro +audience: pro +weight: 2 +--- + +No DefectDojo, um modelo de Pesquisa é um conjunto reutilizável de Perguntas que serve para coletar informações de desenvolvedores, equipes e partes interessadas internas e externas. Eles podem ser usados para reunir informações antes do início do trabalho, garantir alinhamento entre indivíduos e equipes à medida que o trabalho avança, e permitir uma análise retrospectiva após a conclusão do trabalho. + +No DefectDojo, um sistema de Pesquisas é composto por três componentes: +- **Modelos de Pesquisa**, que agrupam e ordenam as Perguntas. +- **Implantações de Pesquisa**, que são instâncias ativas que coletam respostas. +- **Respostas**, que são as respostas enviadas pelos Usuários. + +Criar um modelo de Pesquisa não o torna automaticamente disponível para respostas. Para coletar respostas, um modelo de Pesquisa precisa ser implantado. + +## Permissões + +A seção Surveys na barra lateral só é visível para Usuários com status de Superusuário, e somente Superusuários podem criar modelos de Pesquisa, criar Perguntas e implantar Pesquisas. + +Usuários sem status de Superusuário ainda podem responder a Pesquisas que sejam compartilhadas com eles, mas não podem criá-las ou gerenciá-las, nem às Perguntas associadas. + +## Acessando Pesquisas e Perguntas + +Usuários com status de Superusuário podem acessar Pesquisas e Perguntas na barra lateral clicando na opção **Surveys**. O submenu oferece acesso a **All Surveys** e **All Questions**, além da opção de criar novas Pesquisas e Perguntas. + +![image](images/pq_ss1.png) + +### Acessando Pesquisas + +A visualização All Surveys inclui uma tabela contendo todos os modelos de Pesquisa, incluindo seu ID, nome, descrição e status ativo. A tabela pode ser filtrada usando palavras-chave, e pode ser reorganizada clicando no cabeçalho de cada coluna. + +### Acessando Perguntas + +A visualização All Questions inclui uma tabela de Perguntas que podem ser adicionadas a uma Pesquisa. A tabela pode ser filtrada usando palavras-chave, e pode ser reorganizada clicando no cabeçalho de cada coluna. + +## Gerenciando Modelos de Pesquisa + +### Criar Modelos de Pesquisa + +Os modelos de Pesquisa podem ser criados clicando em **New Survey** na barra lateral, ou clicando no botão **New Survey** no topo da visualização All Surveys. + +![image](images/pq_ss2.png) + +O modelo de Pesquisa precisa receber um nome e uma descrição, e ter pelo menos uma Pergunta escolhida no menu suspenso antes de ser criado. + +#### Adicionar Perguntas a um Modelo de Pesquisa Já Existente + +Para adicionar Perguntas a um modelo de Pesquisa já existente, clique no ícone de kebab ⋮ à esquerda da Pesquisa desejada, clique em **Edit Survey**, selecione quaisquer novas Perguntas a serem adicionadas à Pesquisa no menu suspenso e, em seguida, clique em **Submit**. + +Como boa prática, recomenda-se fortemente evitar modificar ou adicionar Perguntas a um modelo de Pesquisa enquanto ele possui implantações ativas. Adicionar novas Perguntas não afetará as Respostas existentes, mas essas Respostas terão sido enviadas sem responder às Perguntas recém-adicionadas, o que pode resultar em dados incompletos. + +### Criar Perguntas + +Assim como os modelos de Pesquisa, as Perguntas podem ser criadas clicando em **New Question** na barra lateral, ou clicando no botão **New Question** no topo da visualização All Questions. + +#### Tipos de Pergunta + +Ao criar uma nova Pergunta, ela pode ser formatada como uma pergunta baseada em texto ou como uma pergunta de múltipla escolha, selecionando **Text Question** ou **Choice Question** no topo da visualização New Question. + +![image](images/pq_ss3.png) + +#### Ordem das Perguntas + +Determine a ordem de uma Pergunta atribuindo a ela um número de ordem. Por exemplo, se uma Pergunta tiver 1 no campo Order, essa Pergunta aparecerá acima de uma Pergunta com 2 no campo Order. + +#### Respostas Opcionais + +Tanto as perguntas baseadas em texto quanto as de múltipla escolha podem ser marcadas como **Optional** clicando na caixa de seleção correspondente. + +#### Permitindo Múltiplas Respostas + +Um número ilimitado de respostas possíveis pode ser adicionado a uma pergunta de múltipla escolha. Clicar na caixa de seleção **Allow Multiple Selections** permite que múltiplas respostas sejam selecionadas (disponível apenas para perguntas de múltipla escolha). + +### Editando Perguntas + +Para alterar uma Pergunta, navegue até a visualização All Questions, clique no ícone de kebab ⋮ à esquerda da Pergunta a ser alterada, clique em Edit Question, faça a alteração desejada e finalize a alteração clicando em Submit. As Perguntas não podem ser excluídas. + +![image](images/pq_ss4.png) + +É importante evitar editar Perguntas que fazem parte de Questionários ativos ou adicionar Perguntas a Questionários ativos. Fazer isso não afetará nenhuma resposta coletada anteriormente, mas pode resultar em dados incompletos ou não confiáveis. + +## Implantando Pesquisas + +Depois que um modelo de Pesquisa é criado com sucesso, implantar uma Pesquisa cria uma instância ativa que aceita respostas. + +Para implantar uma Pesquisa, navegue até a visualização All Surveys, clique no ícone de kebab ⋮ à esquerda da Pesquisa a ser implantada, clique em **Open Survey**, defina a data de expiração e clique em Submit. + +Se você quiser implantar a mesma Pesquisa novamente, siga o mesmo processo. Todas as implantações aparecerão na tabela Open Survey Instances na visualização da Pesquisa, e podem ser distinguidas por seu ID, horário de criação e data de expiração. + +![image](images/pq_ss10.png) + +Uma Pesquisa se encerrará na data escolhida, no mesmo horário em que foi implantada. Por exemplo, se você implantar uma Pesquisa às 8h00 do dia 1º de fevereiro de 2026 e agendar seu encerramento para 1º de março de 2026, a pesquisa se encerrará às 8h00 da manhã de 1º de março de 2026. + +Depois que uma Pesquisa é aberta, sua data e horário de expiração não podem ser alterados. Se um prazo diferente for necessário, uma nova implantação precisa ser criada. + +Depois que uma data de expiração passa, não será mais possível enviar respostas para aquela implantação da Pesquisa, mas a implantação continuará aparecendo na tabela Open Survey Instances na visualização daquela Pesquisa. + +#### Compartilhando uma Pesquisa + +Depois que uma Pesquisa é implantada, ela pode ser compartilhada com outros Usuários clicando no ícone ↗ à esquerda da Pesquisa na tabela Open Survey Instances na visualização do modelo de Pesquisa. Isso revelará um link exclusivo daquela implantação, que pode ser copiado e compartilhado com os destinatários pretendidos. + +![image](images/pq_ss5.png) + +![image](images/pq_ss9.png) + +#### Encerrando uma Pesquisa + +Para encerrar uma Pesquisa, clique no **X** vermelho à esquerda da Pesquisa na tabela Open Survey Instances na visualização do modelo de Pesquisa. + +![image](images/pq_ss13.png) + +Conforme observado na seção Responses mais adiante, isso apenas impedirá o envio de novas respostas. As Respostas enviadas anteriormente permanecerão visíveis na tabela Responses na parte inferior da visualização do modelo de Pesquisa. + +## Respondendo a Pesquisas + +Para responder a uma Pesquisa, os não Superusuários precisam ter o link compartilhado diretamente com eles, seguindo as instruções na seção [Compartilhando uma Pesquisa](#sharing-a-survey) acima. Os Superusuários também podem responder usando o mesmo link. + +#### Habilitando Respostas Anônimas + +Por padrão, as Pesquisas só são acessíveis a Usuários do DefectDojo. Para permitir que partes externas respondam a Pesquisas do DefectDojo, certifique-se de que a opção **Enable Anonymous Survey Responses** esteja ativada em **System Settings**, encontrada em **Settings > System** na barra lateral (dentro do submenu **Pro Settings** em instâncias que ainda utilizam o layout de menu anterior). + +![image](images/pq_ss6.png) + +As respostas externas aparecerão como anônimas porque não há um ID de usuário do DefectDojo associado à resposta. + +Se o escopo de uma Pesquisa incluir Usuários tanto internos quanto externos, especifique o nome do Engajamento na descrição no momento da criação, o que permitirá a filtragem dos resultados. + +![image](images/pq_ss7.png) + +![image](images/pq_ss8.png) + +## Gerenciando Respostas + +Um único modelo de Pesquisa pode ser implantado várias vezes simultaneamente. Todas as respostas de múltiplas implantações do mesmo modelo de Pesquisa serão exibidas juntas na tabela Responses na parte inferior da visualização daquela Pesquisa. + +![image](images/pq_ss11.png) + +Mesmo depois que uma implantação de Pesquisa expira ou é encerrada, suas respostas permanecem visíveis na tabela Responses na parte inferior da visualização da Pesquisa, desde que o modelo de Pesquisa em si não tenha sido excluído. Essas respostas são permanentes e não podem ser removidas. + +Como mostrado na imagem abaixo, não há atualmente nenhuma implantação de Pesquisa aberta, mas as respostas de implantações anteriores ainda estão presentes na tabela Responses. + +![image](images/pq_ss12.png) + +### Excluindo Modelos de Pesquisa + +Para excluir um Modelo de Pesquisa, navegue até a visualização All Surveys, clique no ícone de kebab ⋮ à esquerda da Pesquisa escolhida, e clique em **Delete Survey**. Isso exclui permanentemente o modelo de Pesquisa e todas as implantações e Respostas associadas. Esta ação não pode ser desfeita. diff --git a/docs/content/asset_modelling/PRO_surveys/PRO__surveys.zh-hans.md b/docs/content/asset_modelling/PRO_surveys/PRO__surveys.zh-hans.md new file mode 100644 index 0000000000..54d8a1971c --- /dev/null +++ b/docs/content/asset_modelling/PRO_surveys/PRO__surveys.zh-hans.md @@ -0,0 +1,147 @@ +--- +title: 问卷调查 +description: 了解 DefectDojo Pro 中的问卷调查 +audience: pro +weight: 2 +--- + +在 DefectDojo 中,问卷模板是一组可重复使用的问题集合,用于从开发人员、团队以及内部和外部利益相关方那里收集信息。它们可用于在工作开始前收集意见、确保各团队和个人在工作推进过程中保持一致,并在工作完成后进行复盘分析。 + +在 DefectDojo 中,问卷调查系统由三个部分组成: +- **问卷模板**,用于对问题进行分组和排序。 +- **问卷部署**,即用于收集回复的活动实例。 +- **回复**,即用户提交的答案。 + +创建问卷模板并不会自动使其可供填写回复。要收集回复,必须先部署该问卷模板。 + +## 权限 + +侧边栏中的“问卷调查”部分仅对具有超级用户身份的用户可见,只有超级用户才能创建问卷模板、创建问题以及部署问卷。 + +不具备超级用户身份的用户仍可以填写与他们共享的问卷,但无法创建或管理这些问卷及其相关问题。 + +## 访问问卷调查和问题 + +具有超级用户身份的用户可以通过点击侧边栏中的 **问卷调查(Surveys)** 选项来访问问卷调查和问题。子菜单提供了访问 **所有问卷(All Surveys)** 和 **所有问题(All Questions)** 的入口,以及创建新问卷和新问题的选项。 + +![图片](images/pq_ss1.png) + +### 访问问卷调查 + +“所有问卷”视图包含一个列出所有问卷模板的表格,包括其 ID、名称、描述和活动状态。该表格可以使用关键字进行筛选,也可以通过点击每列的表头进行重新排序。 + +### 访问问题 + +“所有问题”视图包含一个可添加到问卷中的问题表格。该表格可以使用关键字进行筛选,也可以通过点击每列的表头进行重新排序。 + +## 管理问卷模板 + +### 创建问卷模板 + +可以通过点击侧边栏中的 **新建问卷(New Survey)**,或点击“所有问卷”视图顶部的 **新建问卷** 按钮来创建问卷模板。 + +![图片](images/pq_ss2.png) + +在创建问卷模板之前,必须为其指定名称和描述,并从下拉菜单中至少选择一个问题。 + +#### 向已有问卷模板添加问题 + +要向已有的问卷模板添加问题,请点击所需问卷左侧的 ⋮ 三点图标,点击 **编辑问卷(Edit Survey)**,从下拉菜单中选择要添加到该问卷的新问题,然后点击 **提交(Submit)**。 + +作为最佳实践,强烈建议避免在问卷模板存在活动部署期间对其进行修改或添加问题。添加新问题不会影响现有的回复,但这些回复在提交时并未回答新添加的问题,这可能导致数据不完整。 + +### 创建问题 + +与问卷模板类似,可以通过点击侧边栏中的 **新建问题(New Question)**,或点击“所有问题”视图顶部的 **新建问题** 按钮来创建问题。 + +#### 问题类型 + +创建新问题时,可以通过在“新建问题”视图顶部选择 **文本问题(Text Question)** 或 **选择题(Choice Question)**,将其格式设置为文本类问题或多选类问题。 + +![图片](images/pq_ss3.png) + +#### 问题顺序 + +通过为问题指定一个顺序编号来确定其显示顺序。例如,如果某个问题的顺序字段为 1,该问题将显示在顺序字段为 2 的问题之上。 + +#### 可选回答 + +文本类问题和多选类问题都可以通过点击相应的复选框将其设置为 **可选(Optional)**。 + +#### 允许多个答案 + +可以为一个多选题添加数量不限的潜在回答选项。点击 **允许多选(Allow Multiple Selections)** 复选框可允许选择多个答案(仅适用于多选题)。 + +### 编辑问题 + +要更改某个问题,请导航到“所有问题”视图,点击要更改的问题左侧的 ⋮ 三点图标,点击“编辑问题”,进行所需的更改,然后点击“提交”以完成更改。问题无法被删除。 + +![图片](images/pq_ss4.png) + +务必避免编辑属于活动问卷的问题,或向活动问卷添加问题。这样做不会影响之前已收集的任何回复,但可能导致数据不完整或不可靠。 + +## 部署问卷调查 + +问卷模板成功创建后,部署问卷会创建一个可接受回复的活动实例。 + +要部署问卷,请导航到“所有问卷”视图,点击要部署的问卷左侧的 ⋮ 三点图标,点击 **打开问卷(Open Survey)**,设置到期日期,然后点击提交。 + +如果您希望再次部署同一份问卷,请重复相同的流程。所有部署实例都会显示在该问卷视图中的“已开放问卷实例”表格中,并可通过其 ID、创建时间和到期日期加以区分。 + +![图片](images/pq_ss10.png) + +问卷将在所选日期的部署时间关闭。例如,如果您在 2026 年 2 月 1 日上午 8:00 部署了一份问卷,并将其设置为在 2026 年 3 月 1 日关闭,那么该问卷将在 3 月 1 日上午 8:00 关闭。 + +问卷一旦开放,其到期日期和时间就无法更改。如果需要不同的时间范围,必须创建一个新的部署。 + +一旦到期日期已过,将无法再向该问卷部署实例提交回复,但该部署实例仍会显示在该问卷视图的“已开放问卷实例”表格中。 + +#### 分享调查问卷 + +问卷部署后,可以通过点击该问卷模板视图中“已开放问卷实例”表格内问卷左侧的 ↗ 图标,将其与其他用户共享。这将显示一个该部署专属的链接,可以复制并分享给预期的接收者。 + +![图片](images/pq_ss5.png) + +![图片](images/pq_ss9.png) + +#### 关闭问卷调查 + +要关闭一份问卷,请点击该问卷模板视图中“已开放问卷实例”表格内问卷左侧的红色 **X**。 + +![图片](images/pq_ss13.png) + +如后面“回复”部分所述,这只会阻止进一步提交回复。此前提交的回复仍会显示在该问卷模板视图底部的“回复”表格中。 + +## 填写问卷调查 + +要填写问卷,非超级用户必须获得按照上文[分享调查问卷](#sharing-a-survey)部分说明直接与其共享的链接。超级用户也可以使用相同的链接进行填写。 + +#### 启用匿名回复 + +默认情况下,问卷只能由 DefectDojo 用户访问。要允许外部人员填写 DefectDojo 问卷,请确保在侧边栏的 **设置 > 系统(Settings > System)**(在仍使用旧版菜单布局的实例上位于 **Pro 设置** 子菜单内)下的 **系统设置(System Settings)** 中,已启用 **允许匿名问卷回复(Enable Anonymous Survey Responses)** 选项。 + +![图片](images/pq_ss6.png) + +外部回复将显示为匿名,因为该回复没有关联任何 DefectDojo 用户 ID。 + +如果某份问卷的填写范围同时包含内部和外部用户,请在创建时于描述中注明测试活动名称,以便对结果进行筛选。 + +![图片](images/pq_ss7.png) + +![图片](images/pq_ss8.png) + +## 管理回复 + +同一份问卷模板可以同时部署多次。同一问卷模板多次部署所收到的所有回复,都会一并显示在该问卷视图底部的“回复”表格中。 + +![图片](images/pq_ss11.png) + +即使某个问卷部署已到期或已被关闭,只要该问卷模板本身未被删除,其回复仍会显示在该问卷视图底部的“回复”表格中。这些回复是永久性的,无法删除。 + +如下图所示,当前没有任何已开放的问卷部署,但先前部署的回复仍保留在“回复”表格中。 + +![图片](images/pq_ss12.png) + +### 删除问卷模板 + +要删除一个问卷模板,请导航到“所有问卷”视图,点击所选问卷左侧的 ⋮ 三点图标,然后点击 **删除问卷(Delete Survey)**。这将永久删除该问卷模板及其所有相关的部署和回复。此操作无法撤销。 diff --git a/docs/content/asset_modelling/PRO_surveys/_index.it.md b/docs/content/asset_modelling/PRO_surveys/_index.it.md new file mode 100644 index 0000000000..2ea16edd8f --- /dev/null +++ b/docs/content/asset_modelling/PRO_surveys/_index.it.md @@ -0,0 +1,9 @@ +--- +title: Sondaggi +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +audience: pro +--- diff --git a/docs/content/asset_modelling/PRO_surveys/_index.pt-br.md b/docs/content/asset_modelling/PRO_surveys/_index.pt-br.md new file mode 100644 index 0000000000..e4bdadb389 --- /dev/null +++ b/docs/content/asset_modelling/PRO_surveys/_index.pt-br.md @@ -0,0 +1,9 @@ +--- +title: Pesquisas +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +audience: pro +--- diff --git a/docs/content/asset_modelling/PRO_surveys/_index.zh-hans.md b/docs/content/asset_modelling/PRO_surveys/_index.zh-hans.md new file mode 100644 index 0000000000..4269fcae08 --- /dev/null +++ b/docs/content/asset_modelling/PRO_surveys/_index.zh-hans.md @@ -0,0 +1,9 @@ +--- +title: 问卷调查 +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +audience: pro +--- diff --git a/docs/content/asset_modelling/_index.it.md b/docs/content/asset_modelling/_index.it.md new file mode 100644 index 0000000000..47a1dd308d --- /dev/null +++ b/docs/content/asset_modelling/_index.it.md @@ -0,0 +1,10 @@ +--- +title: Organizza DefectDojo +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/_index.pt-br.md b/docs/content/asset_modelling/_index.pt-br.md new file mode 100644 index 0000000000..4b05b418e1 --- /dev/null +++ b/docs/content/asset_modelling/_index.pt-br.md @@ -0,0 +1,10 @@ +--- +title: Organizar o DefectDojo +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/_index.zh-hans.md b/docs/content/asset_modelling/_index.zh-hans.md new file mode 100644 index 0000000000..2f607f0380 --- /dev/null +++ b/docs/content/asset_modelling/_index.zh-hans.md @@ -0,0 +1,10 @@ +--- +title: 组织 DefectDojo +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 3 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/components/PRO__components.it.md b/docs/content/asset_modelling/components/PRO__components.it.md new file mode 100644 index 0000000000..f79b5d0c99 --- /dev/null +++ b/docs/content/asset_modelling/components/PRO__components.it.md @@ -0,0 +1,69 @@ +--- +title: Componenti +description: Monitoraggio delle librerie di terze parti e dei componenti software + in DefectDojo Pro +audience: pro +weight: 1 +--- + +In DefectDojo, i Componenti rappresentano librerie di terze parti, componenti software e moduli che potenzialmente presentano vulnerabilità. + + +## Viste dei Componenti + +DefectDojo Pro include una vista tabellare dedicata per i Componenti, disponibile nella barra laterale. Questa vista mostra i Riscontri attivi, i Riscontri duplicati e i Riscontri totali per ciascun Componente. Questi valori includono tutti gli Asset presenti sull'istanza DefectDojo. + +I Componenti di un singolo Asset sono visibili nella vista dell'Asset. + +## La tabella dei Componenti + +La tabella dei Componenti mostra le seguenti colonne: + +* **Componente** — il nome del componente, popolato a partire dai dati della scansione. +* **Versione** — la versione del componente, popolata a partire dai dati della scansione. +* **Riscontri attivi** — il numero di Riscontri attivi associati al componente. +* **Riscontri duplicati** — il numero di Riscontri duplicati associati al componente. +* **Riscontri totali** — il numero totale di Riscontri associati al componente. + +Facendo clic sul nome del Componente o sui valori di Riscontri attivi, Riscontri duplicati o Riscontri totali si apre un elenco filtrato dei Riscontri relativo al rispettivo campo. + +Nella tabella viene visualizzato un Componente **None**, che mostra tutti i Riscontri non associati ad alcun Componente. + +I Componenti importati rimangono nella tabella anche se tutti i Riscontri associati sono Mitigati. Quando vengono importati Riscontri per un Componente specifico, la tabella dei Componenti viene aggiornata per riflettere accuratamente i nuovi totali dei Riscontri. + + +### Esempio + +Un Componente importato da una scansione Dependency-Check eseguita su un'applicazione con una dipendenza `lodash` vulnerabile potrebbe apparire nella tabella come segue: + +| Componente | Versione | Riscontri attivi | Riscontri duplicati | Riscontri totali | +| --- | --- | --- | --- | --- | +| npm:lodash | 4.17.15 | 3 | 1 | 5 | + +Facendo clic su `npm:lodash` si apre l'elenco di tutti i Riscontri che fanno riferimento a questo Componente. Facendo clic su `3` si apre lo stesso elenco filtrato ai soli Riscontri attivi. + +## Aggiunta di Componenti + +I Componenti possono essere estratti da un'importazione di scansione oppure aggiunti modificando manualmente un Riscontro. Una volta che un Nome del Componente viene associato a un Riscontro, una voce corrispondente viene aggiunta automaticamente alla tabella dei Componenti. Se il Componente è già associato ad altri Riscontri in DefectDojo, i totali di Riscontri attivi, Riscontri duplicati e Riscontri totali vengono aggiornati di conseguenza. + +### Come vengono estratti i Componenti dai dati di scansione + +Quando una scansione viene importata, i parser popolano i campi **Nome del Componente** e **Versione del Componente** di ciascun Riscontro a partire dall'output della scansione. La tabella dei Componenti viene quindi costruita a partire da questi valori. Il livello di dettaglio e la convenzione di denominazione dipendono dallo strumento che ha prodotto la scansione: + +* **Gli strumenti di Software Composition Analysis (SCA)** in genere riportano un nome di pacchetto e una versione esatta. Ad esempio, OWASP Dependency-Check deriva il Componente dal [Package URL](https://github.com/package-url/purl-spec) presente nel proprio identificativo — un purl `pkg:npm/lodash@4.17.15` diventa `Component Name: npm:lodash`, `Component Version: 4.17.15`. +* **Gli scanner di container e pacchetti del sistema operativo** come Trivy, Anchore Grype e Anchore Engine riportano il pacchetto del sistema operativo o del linguaggio interessato — ad esempio, `Component Name: curl`, `Component Version: 7.68.0`. +* **Gli scanner di dipendenze specifici per linguaggio** come npm Audit, pip-audit, bundler-audit, Retire.js, Govulncheck e OSV-Scanner popolano il pacchetto e la versione responsabili a partire dai rispettivi manifest dell'ecosistema. + +Gli scanner incentrati su configurazione, infrastruttura o logica del codice sorgente (come gli strumenti SAST e IaC) generalmente non popolano i campi del Componente, e i relativi Riscontri compaiono sotto il Componente **None**. + +Per aggiungere o modificare un Componente manualmente, modifica il Riscontro e imposta direttamente i campi **Nome del Componente** e **Versione del Componente**. La tabella dei Componenti si aggiorna non appena il Riscontro viene salvato. + +## Aggiornamento dei Componenti + +Per aggiornare il Nome o la Versione di un Componente, è necessario aggiornare il campo Nome del Componente o Versione del Componente su tutti i Riscontri associati al Componente. + +## Rimozione dei Componenti + +Per rimuovere un Componente dalla tabella dei Componenti, è necessario aggiornare tutti i Riscontri associati al Componente rimuovendo i campi Nome del Componente e Versione del Componente. I Componenti vengono rimossi anche se tutti i Riscontri associati vengono eliminati. + +Se tutti i Riscontri di un Componente sono Mitigati, il Componente rimane nella tabella ma il suo valore di Riscontri attivi viene impostato a 0. diff --git a/docs/content/asset_modelling/components/PRO__components.pt-br.md b/docs/content/asset_modelling/components/PRO__components.pt-br.md new file mode 100644 index 0000000000..a32b763855 --- /dev/null +++ b/docs/content/asset_modelling/components/PRO__components.pt-br.md @@ -0,0 +1,69 @@ +--- +title: Componentes +description: Rastreamento de bibliotecas de terceiros e componentes de software no + DefectDojo Pro +audience: pro +weight: 1 +--- + +No DefectDojo, os Componentes representam bibliotecas de terceiros, componentes de software e módulos que potencialmente possuem vulnerabilidades. + + +## Visualizações de Componentes + +O DefectDojo Pro inclui uma visualização de tabela dedicada para Componentes, que pode ser encontrada na barra lateral. Essa visualização mostra os Achados Ativos, os Achados Duplicados e o Total de Achados para cada Componente. Esses números incluem todos os Ativos na instância do DefectDojo. + +Os Componentes de um Ativo individual podem ser vistos na visualização do Ativo. + +## A Tabela de Componentes + +A Tabela de Componentes exibe as seguintes colunas: + +* **Componente** — o nome do componente, preenchido a partir dos dados do scan. +* **Versão** — a versão do componente, preenchida a partir dos dados do scan. +* **Achados Ativos** — contagem de Achados Ativos associados ao componente. +* **Achados Duplicados** — contagem de Achados Duplicados associados ao componente. +* **Total de Achados** — contagem total de todos os Achados associados ao componente. + +Clicar no Nome do Componente ou nos valores de Achados Ativos, Achados Duplicados ou Total de Achados abre uma lista filtrada de Achados para o respectivo campo. + +Um Componente **Nenhum** é exibido na tabela, mostrando todos os Achados que não estão associados a nenhum Componente. + +Os Componentes importados permanecem na tabela mesmo que todos os seus Achados associados estejam Mitigados. Quando Achados são importados para um Componente específico, a Tabela de Componentes é atualizada para refletir corretamente os novos totais de Achados. + + +### Exemplo + +Um Componente importado de um scan do Dependency-Check em uma aplicação com uma dependência vulnerável do `lodash` pode aparecer na tabela como: + +| Componente | Versão | Achados Ativos | Achados Duplicados | Total de Achados | +| --- | --- | --- | --- | --- | +| npm:lodash | 4.17.15 | 3 | 1 | 5 | + +Clicar em `npm:lodash` abre a lista de todos os Achados que referenciam esse Componente. Clicar em `3` abre a mesma lista filtrada apenas para Achados Ativos. + +## Adicionando Componentes + +Os Componentes podem ser extraídos de uma importação de scan ou por meio da edição manual de um Achado. Assim que um Nome de Componente é associado a um Achado, uma entrada correspondente é adicionada automaticamente à Tabela de Componentes. Se o Componente já estiver associado a outros Achados no DefectDojo, os totais de Achados Ativos, Achados Duplicados e Total de Achados são atualizados de acordo. + +### Como os Componentes são Extraídos dos Dados do Scan + +Quando um scan é importado, os parsers preenchem os campos **Component Name** e **Component Version** de cada Achado a partir da saída do scan. A Tabela de Componentes é então construída a partir desses valores. O nível de detalhe e a convenção de nomenclatura dependem da ferramenta que gerou o scan: + +* **Ferramentas de Software Composition Analysis (SCA)** normalmente informam um nome de pacote e uma versão exata. Por exemplo, o OWASP Dependency-Check deriva o Componente a partir da [Package URL](https://github.com/package-url/purl-spec) em seu identificador — um purl `pkg:npm/lodash@4.17.15` se torna `Component Name: npm:lodash`, `Component Version: 4.17.15`. +* **Scanners de contêiner e de pacotes do SO** como Trivy, Anchore Grype e Anchore Engine informam o pacote do SO ou da linguagem afetado — por exemplo, `Component Name: curl`, `Component Version: 7.68.0`. +* **Scanners de dependências específicos de linguagem** como npm Audit, pip-audit, bundler-audit, Retire.js, Govulncheck e OSV-Scanner preenchem o pacote e a versão problemáticos a partir dos respectivos manifestos do ecossistema. + +Scanners focados em configuração, infraestrutura ou lógica de código-fonte (como ferramentas SAST e IaC) geralmente não preenchem os campos de Componente, e seus Achados aparecem sob o Componente **Nenhum**. + +Para adicionar ou alterar um Componente manualmente, edite o Achado e defina os campos **Component Name** e **Component Version** diretamente. A Tabela de Componentes é atualizada assim que o Achado é salvo. + +## Atualizando Componentes + +Para atualizar um Nome ou Versão de Componente, todos os Achados associados ao Componente devem ter seu campo Component Name ou Component Version atualizado. + +## Removendo Componentes + +Para remover um Componente da Tabela de Componentes, todos os Achados associados ao Componente devem ser atualizados para remover seus campos Component Name e Component Version. Os Componentes também são removidos se todos os seus Achados associados forem excluídos. + +Se todos os Achados de um Componente estiverem Mitigados, o Componente permanece na tabela, mas seu valor de Achados Ativos é definido como 0. diff --git a/docs/content/asset_modelling/components/PRO__components.zh-hans.md b/docs/content/asset_modelling/components/PRO__components.zh-hans.md new file mode 100644 index 0000000000..a1cf58f005 --- /dev/null +++ b/docs/content/asset_modelling/components/PRO__components.zh-hans.md @@ -0,0 +1,68 @@ +--- +title: 组件 +description: 在 DefectDojo Pro 中跟踪第三方库和软件组件 +audience: pro +weight: 1 +--- + +在 DefectDojo 中,组件代表可能存在漏洞的第三方库、软件组件和模块。 + + +## 组件视图 + +DefectDojo Pro 在侧边栏中提供了专门的组件表格视图。该视图显示每个组件的活动发现项、重复发现项和发现项总数。这些数字涵盖 DefectDojo 实例上的所有资产。 + +单个资产的组件可以在资产视图中查看。 + +## 组件表 + +组件表显示以下列: + +* **组件(Component)** — 组件的名称,从扫描数据中填充。 +* **版本(Version)** — 组件版本,从扫描数据中填充。 +* **活动发现项(Active Findings)** — 与该组件关联的活动发现项数量。 +* **重复发现项(Duplicate Findings)** — 与该组件关联的重复发现项数量。 +* **发现项总数(Total Findings)** — 与该组件关联的所有发现项总数。 + +点击组件名称,或点击活动发现项、重复发现项、发现项总数对应的数值,将打开该字段相应的已筛选发现项列表。 + +表格中会显示一个 **None** 组件,其中列出所有未关联任何组件的发现项。 + +即使某个组件关联的所有发现项都已被缓解,已导入的组件仍会保留在表格中。当为某个特定组件导入发现项时,组件表会更新以准确反映新的发现项总数。 + + +### 示例 + +从针对存在漏洞的 `lodash` 依赖项的应用执行的 Dependency-Check 扫描中导入的组件,可能会在表格中显示为: + +| Component | Version | Active Findings | Duplicate Findings | Total Findings | +| --- | --- | --- | --- | --- | +| npm:lodash | 4.17.15 | 3 | 1 | 5 | + +点击 `npm:lodash` 会打开所有引用该组件的发现项列表。点击 `3` 会打开经筛选、仅显示活动发现项的相同列表。 + +## 添加组件 + +组件可以通过扫描导入进行解析,也可以通过手动编辑发现项来添加。一旦某个组件名称与某个发现项关联,组件表中就会自动添加相应的条目。如果该组件已经与 DefectDojo 中的其他发现项关联,活动发现项、重复发现项和发现项总数的统计数字将相应更新。 + +### 组件如何从扫描数据中解析 + +导入扫描时,解析器会根据扫描输出为每个发现项填充 **组件名称(Component Name)** 和 **组件版本(Component Version)** 字段。组件表随后根据这些值构建。详细程度和命名规范取决于生成扫描的工具: + +* **软件成分分析(SCA)工具** 通常报告软件包名称和确切版本。例如,OWASP Dependency-Check 会从其标识符中的 [Package URL](https://github.com/package-url/purl-spec) 派生组件信息——一个 `pkg:npm/lodash@4.17.15` 的 purl 会转换为 `Component Name: npm:lodash`、`Component Version: 4.17.15`。 +* **容器和操作系统软件包扫描器**,例如 Trivy、Anchore Grype 和 Anchore Engine,会报告受影响的操作系统或语言软件包——例如,`Component Name: curl`、`Component Version: 7.68.0`。 +* **特定语言的依赖项扫描器**,例如 npm Audit、pip-audit、bundler-audit、Retire.js、Govulncheck 和 OSV-Scanner,会根据各自生态系统的清单文件填充违规软件包及其版本。 + +专注于配置、基础设施或源代码逻辑的扫描器(例如 SAST 和 IaC 工具)通常不会填充组件字段,其发现项将显示在 **None** 组件下。 + +要手动添加或更改组件,请编辑发现项并直接设置 **组件名称** 和 **组件版本** 字段。保存发现项后,组件表会立即更新。 + +## 更新组件 + +要更新组件名称或版本,必须更新与该组件关联的所有发现项的组件名称或组件版本字段。 + +## 移除组件 + +要从组件表中移除某个组件,必须更新与该组件关联的所有发现项,移除其组件名称和组件版本字段。如果某个组件关联的所有发现项都被删除,该组件也会被移除。 + +如果某个组件的所有发现项都已被缓解,该组件仍会保留在表格中,但其活动发现项数值将变为 0。 diff --git a/docs/content/asset_modelling/components/_index.it.md b/docs/content/asset_modelling/components/_index.it.md new file mode 100644 index 0000000000..608a21a584 --- /dev/null +++ b/docs/content/asset_modelling/components/_index.it.md @@ -0,0 +1,10 @@ +--- +title: Componenti ed Endpoint +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 4 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/components/_index.pt-br.md b/docs/content/asset_modelling/components/_index.pt-br.md new file mode 100644 index 0000000000..930a2f3355 --- /dev/null +++ b/docs/content/asset_modelling/components/_index.pt-br.md @@ -0,0 +1,10 @@ +--- +title: Componentes e Endpoints +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 4 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/components/_index.zh-hans.md b/docs/content/asset_modelling/components/_index.zh-hans.md new file mode 100644 index 0000000000..cc04525883 --- /dev/null +++ b/docs/content/asset_modelling/components/_index.zh-hans.md @@ -0,0 +1,10 @@ +--- +title: 组件与端点 +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 4 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/components/services.it.md b/docs/content/asset_modelling/components/services.it.md new file mode 100644 index 0000000000..7b7c4b5737 --- /dev/null +++ b/docs/content/asset_modelling/components/services.it.md @@ -0,0 +1,39 @@ +--- +title: Servizi +description: Monitoraggio dei Microservizi +weight: 1 +--- + +## Cos'è un Servizio? + +I Servizi (abbreviazione di Microservizi) sono una funzionalità opzionale all'interno degli Asset che fornisce un contesto aggiuntivo su dove hanno origine i Riscontri all'interno di un Asset. Aiutano a isolare i Riscontri a un particolare componente di un Asset, anziché all'intero Asset nel suo complesso, offrendo chiarezza e precisione di reporting in ambienti con architetture complesse. + +I Servizi sono utili quando è necessario segmentare ulteriormente i risultati provenienti da un Test, oppure se si prevede di avere più istanze dello stesso Riscontro all'interno di una pipeline di Reimportazione che non si desidera deduplicare. Alcuni strumenti di scansione potrebbero creare Riscontri separati per ciascuna posizione di file e, se si preferisce mantenere queste istanze di un Riscontro come Riscontri separati, i servizi possono essere un modo utile per etichettare queste diverse posizioni. + +## Servizi in Pro + +I Servizi sono disponibili nella versione Pro, ma sono in gran parte superati dalla possibilità di stabilire relazioni padre-figlio tra gli Asset. I Servizi ottengono lo stesso risultato e possono comunque essere utili quando ristrutturare gli Asset non è fattibile, oppure quando è necessario un ambito di deduplicazione a livello di scansione senza alterare la gerarchia degli Asset, ma eliminano il contesto. Ad esempio, la criticità di business, il fatturato e il personale possono essere attribuiti agli Asset ma non ai Servizi. Per questo motivo, i Servizi sono utili principalmente nel contesto di DefectDojo OS. + +## Come specifico un Servizio? + +L'opzione per specificare un Servizio è disponibile nei moduli di importazione o reimportazione della scansione, all'interno del menu a tendina dei Campi opzionali. Da quel momento, la deduplicazione viene applicata ai Test che condividono lo stesso valore di Servizio. + +È importante notare che i Servizi distinguono tra maiuscole e minuscole. Se il Servizio dell'importazione iniziale è stato identificato come “Service 1” (S maiuscola) e si reimporta una scansione che ha risolto tutti i problemi precedenti ma si identifica il Servizio come “service 1” (s minuscola), la deduplicazione non verrà applicata al Servizio previsto. + +## Come funzionano i Servizi? + +I Servizi funzionano consentendo di specificare a quali Test precedenti si applicheranno le regole di deduplicazione al momento della Reimportazione. + +Se, ad esempio, si importa una scansione e si imposta il Servizio come “Service 1,” per poi reimportare una seconda scansione impostando il Servizio come “Service 2,” la deduplicazione non verrà applicata tra queste due scansioni perché il Servizio è diverso. + +Eventuali reimportazioni successive dedupleranno i risultati precedenti della prima scansione solo se il Servizio è stato impostato come “Service 1,” e dedupleranno i risultati precedenti della seconda scansione solo se il Servizio è stato impostato come “Service 2.” In sostanza, se il Servizio è diverso tra due versioni di una scansione reimportata, queste verranno trattate come Riscontri diversi, anche se le scansioni stesse sono identiche. + +In questo esempio, se, al momento della reimportazione, il Servizio non viene impostato né come Service 1 né come Service 2, e viene invece lasciato vuoto, la deduplicazione non verrà applicata né alla prima né alla seconda scansione, e verranno chiusi solo i Riscontri privi di Servizio. + +## Come dovrebbero essere utilizzati i Servizi? + +In pratica, i Servizi sono più utili quando: + +* Un singolo Asset contiene più componenti distribuiti in modo indipendente. +* Team diversi possiedono parti diverse dello stesso Asset. +* I test di sicurezza vengono eseguiti su singoli servizi (ad esempio, la scansione di una API o di un microservizio specifico). diff --git a/docs/content/asset_modelling/components/services.pt-br.md b/docs/content/asset_modelling/components/services.pt-br.md new file mode 100644 index 0000000000..6ea5111aba --- /dev/null +++ b/docs/content/asset_modelling/components/services.pt-br.md @@ -0,0 +1,39 @@ +--- +title: Serviços +description: Rastreamento de Microsserviços +weight: 1 +--- + +## O que é um Serviço? + +Serviços (abreviação de Microsserviços) são um recurso opcional dentro dos Ativos que fornece contexto adicional sobre onde os Achados se originam dentro de um Ativo. Eles ajudam a isolar Achados a um componente específico de um Ativo, em vez do Ativo inteiro, proporcionando clareza e precisão nos relatórios em ambientes com arquiteturas complexas. + +Os Serviços são úteis quando você precisa segmentar ainda mais os resultados provenientes de um Teste, ou se você espera ter múltiplas instâncias do mesmo Achado dentro de um pipeline de Reimportação que você não deseja deduplicar. Algumas ferramentas de scan podem criar Achados separados para cada localização de arquivo, e se você preferir manter essas instâncias de um Achado como Achados separados, os serviços podem ser uma forma útil de rotular essas diferentes localizações. + +## Serviços no Pro + +Os Serviços estão disponíveis na versão Pro, mas são amplamente substituídos pela capacidade de estabelecer relações pai-filho entre Ativos. Os Serviços alcançam o mesmo resultado e ainda podem ser úteis quando reestruturar os Ativos não é viável ou quando é necessário um escopo de deduplicação em nível de scan sem alterar a hierarquia de Ativos, mas eles removem contexto. Por exemplo, criticidade de negócio, receita e pessoal podem ser atribuídos a Ativos, mas não a Serviços. Dessa forma, os Serviços são úteis principalmente no contexto do DefectDojo OS. + +## Como especifico um Serviço? + +A opção para especificar um Serviço está disponível nos formulários de Import Scan ou Reimport, dentro do menu suspenso de Campos Opcionais. A partir daí, a deduplicação fica restrita aos Testes que compartilham o mesmo valor de Serviço. + +É importante destacar que os Serviços diferenciam maiúsculas de minúsculas. Se o Serviço da importação inicial foi identificado como “Service 1” (S maiúsculo) e você reimportar um scan que resolveu todos os problemas anteriores, mas identificar o Serviço como “service 1” (s minúsculo), a deduplicação não será aplicada ao Serviço pretendido. + +## Como os Serviços funcionam? + +Os Serviços funcionam permitindo que você especifique a quais Testes anteriores as regras de deduplicação serão aplicadas na Reimportação. + +Se, por exemplo, você importar um scan e definir o Serviço como “Service 1,” e depois reimportar um segundo scan e definir o Serviço como “Service 2,” a deduplicação não será aplicada entre esses dois scans porque o Serviço é diferente. + +Quaisquer reimportações subsequentes só deduplicarão os resultados anteriores do primeiro scan se o Serviço tiver sido definido como “Service 1,” e só deduplicarão os resultados anteriores do segundo scan se o Serviço tiver sido definido como “Service 2.” Essencialmente, se o Serviço for diferente entre duas versões de um scan reimportado, eles serão tratados como Achados diferentes, mesmo que os scans em si sejam idênticos. + +Neste exemplo, se, na reimportação, o Serviço não for definido como Service 1 nem como Service 2, e for deixado em branco, a deduplicação não será aplicada nem ao primeiro nem ao segundo scan, e apenas os Achados sem Serviço serão encerrados. + +## Como os Serviços devem ser usados? + +Na prática, os Serviços são mais úteis quando: + +* Um único Ativo contém múltiplos componentes implantados de forma independente. +* Equipes diferentes são responsáveis por partes diferentes do mesmo Ativo. +* Os testes de segurança são realizados contra serviços individuais (por exemplo, ao escanear uma API específica ou um microsserviço). diff --git a/docs/content/asset_modelling/components/services.zh-hans.md b/docs/content/asset_modelling/components/services.zh-hans.md new file mode 100644 index 0000000000..958fa36d6b --- /dev/null +++ b/docs/content/asset_modelling/components/services.zh-hans.md @@ -0,0 +1,39 @@ +--- +title: 服务 +description: 跟踪微服务 +weight: 1 +--- + +## 什么是服务? + +服务(微服务的简称)是资产内的一个可选功能,用于为发现项在资产内的来源提供额外的上下文信息。它们有助于将发现项定位到资产的某个特定组成部分,而不是整个资产,从而在架构复杂的环境中提供更清晰的定位和更精确的报告。 + +当您需要对来自某次测试的结果进行进一步细分,或者预计在重新导入流程中会出现多个不希望去重的相同发现项实例时,服务会非常有用。某些扫描工具可能会为每个文件位置创建单独的发现项,如果您希望将这些发现项实例保留为独立的发现项,服务可以是标注这些不同位置的有效方式。 + +## Pro 版中的服务 + +服务在 Pro 版本中可用,但在很大程度上已被资产之间建立父子关系的能力所取代。服务可以达到相同的效果,并且在重构资产不可行,或者需要在不改变资产层级结构的情况下限定扫描级别的去重范围时,仍然可能有用,但它们会丢失上下文信息。例如,业务关键性、营收和人员信息可以归属于资产,但不能归属于服务。因此,服务主要在开源版 DefectDojo 中有用。 + +## 如何指定服务? + +在导入扫描或重新导入表单的可选字段下拉菜单中,可以指定服务选项。此后,去重将限定在具有相同服务值的测试范围内。 + +需要注意的是,服务是区分大小写的。如果初始导入的服务被标识为“Service 1”(大写 S),而您重新导入了一个已解决所有先前问题的扫描,并将服务标识为“service 1”(小写 s),那么去重将不会应用于预期的服务。 + +## 服务如何运作? + +服务的作用方式是允许您指定重新导入时哪些先前的测试将适用去重规则。 + +例如,如果您导入一次扫描并将服务设置为“Service 1”,然后重新导入第二次扫描并将服务设置为“Service 2”,由于服务不同,这两次扫描之间将不会进行去重。 + +任何后续的重新导入,只有在服务被设置为“Service 1”时,才会对第一次扫描的先前结果进行去重;只有在服务被设置为“Service 2”时,才会对第二次扫描的先前结果进行去重。本质上,如果两个版本的重新导入扫描之间服务不同,即使扫描本身完全相同,它们也会被视为不同的发现项。 + +在此示例中,如果在重新导入时既未将服务设置为 Service 1 也未设置为 Service 2,而是留空,那么去重将不会应用于第一次或第二次扫描,并且只有没有服务的发现项才会被关闭。 + +## 服务应该如何使用? + +在实践中,服务在以下情况下最为有用: + +* 单个资产包含多个独立部署的组件。 +* 不同团队负责同一资产的不同部分。 +* 针对单个服务执行安全测试(例如,扫描特定的 API 或微服务)。 diff --git a/docs/content/asset_modelling/engagements_tests/OS__assets.it.md b/docs/content/asset_modelling/engagements_tests/OS__assets.it.md new file mode 100644 index 0000000000..976d140bdd --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__assets.it.md @@ -0,0 +1,181 @@ +--- +title: Asset +description: Comprendere gli Asset in DefectDojo OS +audience: opensource +weight: 2 +aliases: +- /it/asset_modelling/engagements_tests/os__products/ +- /it/en/asset_modelling/engagements_tests/os__products/ +--- + +Organizations → **ASSET** → Engagement → Test → Riscontri + +## Panoramica + +Gli **Asset** sono al centro del modo in cui il lavoro di sicurezza è organizzato all'interno della gerarchia di oggetti di DefectDojo. Gli Asset rappresentano qualsiasi progetto, programma, software o bene fisico che il team di sicurezza sta testando, e ospitano tutto il lavoro di sicurezza e la cronologia dei test relativi all'obiettivo del test. Esempi di Asset possono includere: +- Release software +- Software di terze parti +- Macchine virtuali o asset in produzione +- Una singola applicazione +- Un microservizio +- Un'API +- Una piattaforma SaaS +- Un'app mobile +- Un sistema interno +- Un servizio aziendale +- Una piattaforma rivolta ai clienti +- Un ambiente cloud o un dominio di infrastruttura + +In generale, un Asset dovrebbe rappresentare la “cosa” di cui si vuole monitorare la postura di sicurezza nel tempo. Questo include la cronologia dei test associata, i Riscontri, le metriche, la proprietà, le integrazioni e i flussi di lavoro di remediation relativi a quella “cosa.” + +### Esempi di Asset + +Gli Asset possono diventare ancora più granulari a seconda delle esigenze della propria organizzazione. Ad esempio, si potrebbe considerare di creare Asset DefectDojo separati nei seguenti scenari: + +- “ExampleAsset” ha una versione Windows, una versione Mac e una versione Cloud +- “ExampleAsset 1.0” utilizza componenti software completamente diversi da “ExampleAsset 2.0”, ed entrambe le versioni sono attivamente supportate dalla propria azienda. +- Il team assegnato a lavorare su “ExampleAsset version A” è diverso dal team Asset assegnato a lavorare su “ExampleAsset version B”, e di conseguenza necessita di permessi di sicurezza diversi. + +Sebbene sia possibile scegliere di rappresentare queste variazioni come Engagement all'interno di un unico Asset, l'RBAC può essere impostato solo a livello di Asset o Organizations, il che può limitare l'accesso degli Utenti all'Engagement appropriato (così come ai Test e ai Riscontri all'interno di quegli Engagement) se organizzati in questo modo. Per maggiori informazioni su RBAC e permessi in DefectDojo, fare clic [qui](/admin/user_management/about_perms_and_roles/). + +## Dati dell'Asset + +Gli Asset includono sempre i seguenti componenti: + +- **Nome univoco** +- **Descrizione** +- **Organization** +- **Configurazione SLA** + +I metadati opzionali dell'Asset includono: + +- **Tag** +- **Informazioni sul personale** (ad es. Asset Manager, Team Manager, Technical Contact, ecc.) +- **Normative** (ad es. HIPAA, GLBA, OPPA, ecc.) +- **Criticità aziendale** +- **Piattaforma** (ad es. API, Desktop, IoT, Mobile, Web, ecc.) +- **Ciclo di vita** (ad es. Costruzione, Produzione, Dismissione, ecc.) +- **Origine** (ad es. Libreria di terze parti, Acquistato, Open Source, ecc.) +- **Record utente** (ovvero il numero stimato di record utente nell'Asset) +- **Ricavi** + +Questi metadati migliorano il filtraggio, il reporting e la definizione delle priorità nell'ambito del programma di sicurezza, ma soprattutto, gli Asset contengono anche tutti gli Engagement, i Test e i Riscontri relativi agli sforzi di test riguardanti quell'Asset. Tutti i Riscontri dei Test confluiscono infine a livello di Asset, consentendo il monitoraggio a lungo termine, l'analisi delle tendenze e il reporting. + +## Accesso agli Asset + +Gli Asset sono accessibili dalla barra laterale. Il sottomenu offre anche l'opzione per creare un nuovo Asset. + +![image](images/asset_ss3.png) + +### Permessi + +Agli Asset possono essere applicate regole di controllo degli accessi basato sui ruoli (RBAC), che limitano la capacità dei membri del team di visualizzarli e interagire con essi. + +I permessi si propagano verso il basso, il che significa che l'accesso a un Asset concede automaticamente l'accesso a tutti gli oggetti al suo interno (ad es. Engagement, Test e Riscontri). + +Per maggiori informazioni sui ruoli Utente, consulta il nostro [articolo di introduzione ai ruoli](/admin/user_management/about_perms_and_roles/). + +## Vista Asset + +Le viste degli Asset contengono una varietà di tabelle e grafici per interpretare a colpo d'occhio lo stato di un Asset. Questo include: + +- **Metadati** + - Inclusi Organization, criticità aziendale, ricavi e altri dettagli aggiunti dalle impostazioni dell'Asset. +- **Metriche** + - Un elenco dei Riscontri aperti all'interno dell'Asset, raggruppati per gravità +- **Service Level Agreement per gravità** + - Applica la configurazione SLA dell'Asset dalle impostazioni ai Riscontri all'interno dell'Asset. +- **Tecnologie** + - Ad es. next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo +- **Normative** +- **Avanzamento Benchmark** +- **Membri** +- **Gruppi** +- **Contatti** +- **Notifiche** + - Attiva e disattiva le notifiche in base a eventi specifici (ad es. un Engagement è stato aggiunto o chiuso) + +## Utilizzo degli Asset + +### Creare Asset + +Esistono più modi per creare un nuovo Asset, tra cui: + +- Il pulsante **Add Asset** nell'elenco All Assets + +![image](images/asset_ss2.png) + +- Dal menu a discesa della tabella Asset all'interno della vista di un'Organization + - Questo creerà automaticamente l'Asset all'interno di quell'Organization. + +![image](images/asset_ss1.png) + +- Il pulsante **Add Asset** nella barra laterale + +![image](images/asset_ss5.png) + +### Modificare gli Asset + +Un Asset può essere modificato dalle sue impostazioni, accessibili in due modi: + +- Il pulsante **Edit** all'interno del menu kebab ⋮ a sinistra dell'Asset nella vista All Assets + +![image](images/asset_ss6.png) + +- Il pulsante **Edit** all'interno del menu a discesa **Settings** nella vista dell'Asset + +![image](images/asset_ss7.png) + +### Eliminare gli Asset + +L'opzione per eliminare un Asset si trova in fondo agli stessi menu descritti nella sezione **Edit Assets** sopra. Questa azione non può essere annullata. Un Asset non può essere chiuso e riaperto in seguito. + +L'eliminazione di un Asset comporterà anche l'eliminazione di quanto segue: +- Tutti gli Engagement e i Test contenuti nell'Asset +- Tutta la cronologia di sicurezza associata, inclusi Riscontri e integrazioni +- Eventuali Jira Epic collegati +- Tutte le note e i file caricati associati agli Engagement e ai Test dell'Asset + +## Confini dell'Asset + +### Deduplicazione + +Gli Asset sono “isolati” e non interagiscono con altri Asset. Le Smart Features di DefectDojo, come la Deduplicazione, si applicano solo nel contesto di un singolo Asset. I Riscontri appartenenti ad Asset diversi non verranno deduplicati automaticamente. + +### Metriche + +La maggior parte del reporting e delle metriche aggrega i dati a livello di Asset, rendendo gli Asset l'unità primaria per misurare e monitorare il rischio. + +Di conseguenza, molte metriche chiave vengono calcolate per Asset, tra cui: + +- Numero totale di Riscontri (per gravità o stato) +- Tempo medio di remediation (MTTR) +- Tassi di conformità e violazione dell'SLA +- Andamento del rischio nel tempo + +Ciò significa che il modo in cui gli Asset sono strutturati influenzerà direttamente l'accuratezza e l'utilità dei report. Ad esempio, raggruppare più sistemi non correlati sotto un unico Asset può offuscare la visibilità del rischio, mentre strutture di Asset eccessivamente granulari possono frammentare il reporting, rendendo difficile identificare tendenze più ampie. + +Le metriche specifiche di un Asset sono accessibili dal pulsante **Metrics** nella barra superiore della vista dell'Asset scelto. + +![image](images/asset_ss8.png) + +### Pipeline CI/CD + +Le pipeline CI/CD automatizzano l'importazione dei risultati delle scansioni. Indipendentemente dal metodo di integrazione, tutti gli import di scansioni devono essere associati a un Asset, rendendo l'Asset il punto di ancoraggio per i dati di sicurezza generati dalla pipeline. + +Quando una pipeline invia i risultati di una scansione, deve: + +- Specificare un Asset esistente (ed eventualmente un Engagement), oppure +- Essere configurata in modo da mappare in modo coerente i risultati sull'Asset corretto + +Tutti i Riscontri importati erediteranno il contesto dell'Asset, inclusi proprietà, permessi, configurazione SLA e ambito di reporting. + +In pratica, gli Asset dovrebbero essere definiti in modo da riflettere come i sistemi vengono costruiti e distribuiti all'interno del CI/CD, per garantire che i risultati di sicurezza siano costantemente associati all'applicazione o al servizio corretto. + +### Relazioni con Jira + +Gli Asset possono essere mappati direttamente su Jira Project, che inviano i Riscontri dell'Asset a un'istanza Jira. + +Poiché i Riscontri ereditano rischio, priorità e proprietà dal loro Asset padre, l'Asset determina di fatto il contesto di remediation che confluisce nei ticket Jira e nei flussi di lavoro dei Downstream Connector. + +È importante notare che gli Asset sono anche il fattore determinante principale delle caratteristiche SLA di un Riscontro. Pertanto, l'SLA di un Riscontro dipende dalla configurazione SLA del suo Asset padre. Maggiori informazioni sulle configurazioni SLA sono disponibili [qui](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content). diff --git a/docs/content/asset_modelling/engagements_tests/OS__assets.pt-br.md b/docs/content/asset_modelling/engagements_tests/OS__assets.pt-br.md new file mode 100644 index 0000000000..905f192648 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__assets.pt-br.md @@ -0,0 +1,181 @@ +--- +title: Ativos +description: Entendendo os Ativos no DefectDojo OS +audience: opensource +weight: 2 +aliases: +- /pt-br/asset_modelling/engagements_tests/os__products/ +- /pt-br/en/asset_modelling/engagements_tests/os__products/ +--- + +Organizações → **ATIVOS** → Engajamentos → Testes → Achados + +## Visão Geral + +Os **Ativos** estão no centro de como o trabalho de segurança é organizado na hierarquia de objetos do DefectDojo. Os Ativos representam qualquer projeto, programa, software ou ativo físico que sua equipe de segurança esteja testando, e abrigam todo o trabalho de segurança e o histórico de testes relacionados ao objetivo do teste. Exemplos de Ativos podem incluir: +- Lançamentos de software +- Software de terceiros +- Máquinas virtuais ou ativos em produção +- Uma única aplicação +- Um microsserviço +- Uma API +- Uma plataforma SaaS +- Um aplicativo móvel +- Um sistema interno +- Um serviço de negócio +- Uma plataforma voltada para o cliente +- Um ambiente de nuvem ou domínio de infraestrutura + +Em geral, um Ativo deve representar a “coisa” cuja postura de segurança você deseja acompanhar ao longo do tempo. Isso inclui o histórico de testes associado, os Achados, as métricas, a titularidade, as integrações e os fluxos de remediação relacionados a essa “coisa”. + +### Exemplos de Ativos + +Os Ativos podem se tornar ainda mais granulares dependendo das necessidades da sua organização. Por exemplo, você pode considerar criar Ativos separados no DefectDojo nos seguintes cenários: + +- “ExampleAsset” tem uma versão para Windows, uma versão para Mac e uma versão em nuvem +- “ExampleAsset 1.0” usa componentes de software completamente diferentes de “ExampleAsset 2.0”, e ambas as versões são ativamente mantidas pela sua empresa. +- A equipe designada para trabalhar em “ExampleAsset versão A” é diferente da equipe de Ativo designada para trabalhar em “ExampleAsset versão B”, e por isso precisa ter permissões de segurança diferentes atribuídas. + +Embora você também possa optar por representar essas variações como Engajamentos dentro de um único Ativo, o RBAC só pode ser definido no nível de Ativos ou Organizações, o que pode limitar o acesso dos usuários ao Engajamento apropriado (assim como aos Testes e Achados dentro desses Engajamentos) se estiverem organizados dessa forma. Para mais informações sobre RBAC e permissões no DefectDojo, clique [aqui](/admin/user_management/about_perms_and_roles/). + +## Dados do Ativo + +Os Ativos sempre incluirão os seguintes componentes: + +- **Nome exclusivo** +- **Descrição** +- **Organização** +- **Configuração de SLA** + +Os metadados opcionais do Ativo incluem: + +- **Tags** +- **Informações de pessoal** (por exemplo, Gerente do Ativo, Gerente da Equipe, Contato Técnico, etc.) +- **Regulamentações** (por exemplo, HIPAA, GLBA, OPPA, etc.) +- **Criticidade para o negócio** +- **Plataforma** (por exemplo, API, Desktop, IoT, Mobile, Web, etc.) +- **Ciclo de vida** (por exemplo, Construção, Produção, Desativação, etc.) +- **Origem** (por exemplo, Biblioteca de Terceiros, Adquirido, Código Aberto, etc.) +- **Registros de usuários** (ou seja, o número estimado de registros de usuários no Ativo) +- **Receita** + +Esses metadados melhoram a filtragem, os relatórios e a priorização em todo o seu programa de segurança, mas, mais importante, os Ativos também contêm todos os Engajamentos, Testes e Achados relacionados aos esforços de teste em torno desse Ativo. Todos os Achados dos Testes acabam consolidados no nível do Ativo, permitindo acompanhamento de longo prazo, análise de tendências e relatórios. + +## Acessando Ativos + +Os Ativos são acessíveis pela barra lateral. O submenu também oferece a opção de criar um novo Ativo. + +![image](images/asset_ss3.png) + +### Permissões + +Os Ativos podem ter regras de Controle de Acesso Baseado em Função (RBAC) aplicadas, o que limita a capacidade dos membros da equipe de visualizá-los e interagir com eles. + +As permissões se propagam em cascata, o que significa que o acesso a um Ativo concede automaticamente acesso a todos os objetos dentro desse Ativo (por exemplo, Engajamentos, Testes e Achados). + +Para mais informações sobre funções de usuário, veja nosso [artigo de Introdução às Funções](/admin/user_management/about_perms_and_roles/). + +## Visualização do Ativo + +As visualizações de Ativo contêm uma variedade de tabelas e gráficos para interpretar rapidamente o status de um Ativo. Isso inclui: + +- **Metadados** + - Incluindo Organização, criticidade para o negócio, receita e outros detalhes adicionados nas configurações do Ativo. +- **Métricas** + - Uma lista de Achados abertos dentro do Ativo, agrupados por severidade +- **Acordo de Nível de Serviço por Severidade** + - Aplica a configuração de SLA do Ativo, definida nas configurações, aos Achados dentro do Ativo. +- **Tecnologias** + - Por exemplo, next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo +- **Regulamentações** +- **Progresso de Benchmark** +- **Membros** +- **Grupos** +- **Contatos** +- **Notificações** + - Ativa e desativa notificações dependendo de eventos específicos (por exemplo, um Engajamento foi adicionado ou encerrado) + +## Trabalhando com Ativos + +### Criar Ativos + +Existem várias maneiras de criar um novo Ativo, incluindo: + +- O botão **Add Asset** na lista de Todos os Ativos + +![image](images/asset_ss2.png) + +- No menu suspenso da tabela de Ativos dentro da visualização de uma Organização + - Isso criará automaticamente o Ativo dentro dessa Organização. + +![image](images/asset_ss1.png) + +- O botão **Add Asset** na barra lateral + +![image](images/asset_ss5.png) + +### Editar Ativos + +Um Ativo pode ser editado a partir de suas configurações, que podem ser acessadas de duas formas: + +- O botão **Edit** dentro do menu kebab (⋮) à esquerda do Ativo, na visualização de Todos os Ativos + +![image](images/asset_ss6.png) + +- O botão **Edit** dentro do menu suspenso **Settings** na visualização do Ativo + +![image](images/asset_ss7.png) + +### Excluir Ativos + +A opção de excluir um Ativo pode ser encontrada na parte inferior dos mesmos menus descritos na seção **Editar Ativos** acima. Essa ação não pode ser desfeita. O Ativo não pode ser fechado e reaberto posteriormente. + +Excluir um Ativo também excluirá o seguinte: +- Quaisquer Engajamentos e Testes contidos no Ativo +- Todo o histórico de segurança associado, incluindo Achados e integrações +- Quaisquer Épicos do Jira vinculados +- Todas as notas e uploads de arquivos associados aos Engajamentos e Testes do Ativo + +## Limites do Ativo + +### Deduplicação + +Os Ativos são “isolados” e não interagem com outros Ativos. Os Smart Features do DefectDojo, como a Deduplicação, aplicam-se apenas no contexto de um único Ativo. Achados em Ativos diferentes não serão deduplicados automaticamente. + +### Métricas + +A maior parte dos relatórios e métricas agrega dados no nível do Ativo, tornando os Ativos a unidade principal para medir e acompanhar o risco. + +Como resultado, muitas métricas-chave são calculadas por Ativo, incluindo: + +- Número total de Achados (por severidade ou status) +- Tempo médio de remediação (MTTR) +- Taxas de conformidade e violação de SLA +- Tendências de risco ao longo do tempo + +Isso significa que a forma como os Ativos são estruturados impactará diretamente a precisão e a utilidade dos relatórios. Por exemplo, agrupar vários sistemas não relacionados sob um único Ativo pode obscurecer a visibilidade de risco, enquanto estruturas de Ativo excessivamente granulares podem fragmentar os relatórios, dificultando a identificação de tendências mais amplas. + +As métricas específicas do Ativo podem ser acessadas pelo botão **Metrics** na barra superior da visualização do Ativo escolhido. + +![image](images/asset_ss8.png) + +### Pipeline de CI/CD + +Os pipelines de CI/CD automatizam a importação dos resultados de varredura. Independentemente do método de integração, todas as importações de varredura devem estar associadas a um Ativo, tornando o Ativo o ponto de ancoragem para os dados de segurança orientados por pipeline. + +Quando um pipeline envia resultados de varredura, ele deve: + +- Especificar um Ativo existente (e opcionalmente um Engajamento), ou +- Estar configurado de forma a mapear consistentemente os resultados para o Ativo correto + +Todos os Achados importados herdarão o contexto do Ativo, incluindo titularidade, permissões, configuração de SLA e escopo de relatórios. + +Na prática, os Ativos devem ser definidos de forma a refletir como os sistemas são construídos e implantados dentro do CI/CD, garantindo que os resultados de segurança sejam consistentemente associados à aplicação ou serviço correto. + +### Relações com o Jira + +Os Ativos podem ser mapeados diretamente para Projetos do Jira, que enviam os Achados do Ativo para uma instância do Jira. + +Como os Achados herdam risco, prioridade e titularidade de seu Ativo pai, o Ativo determina efetivamente o contexto de remediação que flui para os tickets do Jira e para os fluxos de trabalho dos Downstream Connectors. + +É importante notar que os Ativos também são o principal fator determinante nas características de SLA de um Achado. Portanto, o SLA de um Achado depende da configuração de SLA de seu Ativo pai. Mais informações sobre configurações de SLA podem ser encontradas [aqui](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content). diff --git a/docs/content/asset_modelling/engagements_tests/OS__assets.zh-hans.md b/docs/content/asset_modelling/engagements_tests/OS__assets.zh-hans.md new file mode 100644 index 0000000000..d22269df1b --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__assets.zh-hans.md @@ -0,0 +1,181 @@ +--- +title: 资产 +description: 了解 DefectDojo OS 中的资产 +audience: opensource +weight: 2 +aliases: +- /zh-hans/asset_modelling/engagements_tests/os__products/ +- /zh-hans/en/asset_modelling/engagements_tests/os__products/ +--- + +组织 → **资产** → 测试活动 → 测试 → 发现项 + +## 概述 + +**资产**是 DefectDojo 对象层级结构中组织安全工作的核心。资产代表贵组织安全团队正在测试的任何项目、计划、软件或实体资产，并承载与该测试目标相关的全部安全工作和测试历史。资产的示例包括： +- 软件发行版 +- 第三方软件 +- 虚拟机或生产环境中的资产 +- 单个应用程序 +- 微服务 +- API +- SaaS 平台 +- 移动应用 +- 内部系统 +- 业务服务 +- 面向客户的平台 +- 云环境或基础设施域 + +总的来说，资产应当代表您希望长期跟踪其安全态势的那个“对象”。这包括与该“对象”相关的测试历史、发现项、指标、所有权归属、集成以及修复工作流程。 + +### 资产示例 + +根据贵组织的需求，资产的划分可以更加细化。例如，在以下场景中，您可以考虑创建独立的 DefectDojo 资产： + +- “ExampleAsset”拥有 Windows 版本、Mac 版本和云端版本 +- “ExampleAsset 1.0”与“ExampleAsset 2.0”使用的软件组件完全不同，且贵公司仍在积极维护这两个版本。 +- 负责“ExampleAsset version A”的团队与负责“ExampleAsset version B”的资产团队不同，因此需要分配不同的安全权限。 + +虽然您也可以选择将这些差异表示为单个资产内的不同测试活动，但基于角色的访问控制（RBAC）只能在资产或组织级别设置，如果按这种方式组织，可能会限制用户访问相应测试活动（以及这些测试活动中的测试和发现项）的权限。有关 DefectDojo 中 RBAC 和权限的更多信息，请点击[此处](/admin/user_management/about_perms_and_roles/)。 + +## 资产数据 + +资产始终包含以下组成部分： + +- **唯一名称** +- **描述** +- **组织** +- **SLA 配置** + +可选的资产元数据包括： + +- **标签** +- **人员信息**（例如资产经理、团队经理、技术联系人等） +- **法规**（例如 HIPAA、GLBA、OPPA 等） +- **业务关键性** +- **平台**（例如 API、桌面端、物联网、移动端、Web 等） +- **生命周期**（例如构建、生产、退役等） +- **来源**（例如第三方库、外购、开源等） +- **用户记录数**（即该资产中估计的用户记录数量） +- **营收** + +这些元数据可以改进整个安全项目中的筛选、报告和优先级排序，但更重要的是，资产还包含围绕该资产开展的所有测试活动、测试和发现项。来自各测试的所有发现项最终都会汇总到资产级别，从而支持长期跟踪、趋势分析和报告。 + +## 访问资产 + +可以通过侧边栏访问资产。子菜单还提供了创建新资产的选项。 + +![image](images/asset_ss3.png) + +### 权限 + +资产可以应用基于角色的访问控制（RBAC）规则，从而限制团队成员查看和操作这些资产的能力。 + +权限会向下级联，这意味着对某个资产的访问权限会自动授予对该资产内所有对象（例如测试活动、测试和发现项）的访问权限。 + +有关用户角色的更多信息，请参阅我们的[角色介绍文章](/admin/user_management/about_perms_and_roles/)。 + +## 资产视图 + +资产视图包含多种表格和图表，可帮助您一目了然地了解某个资产的状态。具体包括： + +- **元数据** + - 包括组织、业务关键性、营收，以及在资产设置中添加的其他详细信息。 +- **指标** + - 该资产内开放发现项的列表，按严重程度分组 +- **按严重程度划分的服务级别协议** + - 将设置中的资产 SLA 配置应用于该资产内的发现项。 +- **技术栈** + - 例如 next.js、vue.js、npm v.1.2.3、Django、nginx、Hugo +- **法规** +- **基准进度** +- **成员** +- **组** +- **联系人** +- **通知** + - 根据特定事件（例如某个测试活动被添加或关闭）开启或关闭通知 + +## 使用资产 + +### 创建资产 + +创建新资产有多种方式，包括： + +- 全部资产列表中的**添加资产**按钮 + +![image](images/asset_ss2.png) + +- 在某个组织视图中，资产表格的下拉菜单 + - 这将自动在该组织内创建该资产。 + +![image](images/asset_ss1.png) + +- 侧边栏中的**添加资产**按钮 + +![image](images/asset_ss5.png) + +### 编辑资产 + +可以从资产的设置中编辑该资产，共有两种访问方式： + +- 在全部资产视图中，资产左侧 ⋮ 三点菜单内的**编辑**按钮 + +![image](images/asset_ss6.png) + +- 资产视图中**设置**下拉菜单内的**编辑**按钮 + +![image](images/asset_ss7.png) + +### 删除资产 + +删除资产的选项位于上文**编辑资产**部分所述的相同菜单底部。此操作无法撤销。资产无法先关闭再重新打开。 + +删除某个资产还会同时删除以下内容： +- 该资产内包含的所有测试活动和测试 +- 所有相关的安全历史记录，包括发现项和集成 +- 任何关联的 Jira Epic +- 与该资产的测试活动和测试相关联的所有备注和上传文件 + +## 资产边界 + +### 去重 + +资产之间是彼此“隔离”的，不会与其他资产产生交互。DefectDojo 的智能功能（例如去重）仅在单个资产的范围内生效。不同资产之间的发现项不会自动去重。 + +### 指标 + +大多数报告和指标都是在资产级别汇总数据的，这使资产成为衡量和跟踪风险的主要单位。 + +因此，许多关键指标都是按资产计算的，包括： + +- 发现项总数（按严重程度或状态划分） +- 平均修复时间（MTTR） +- SLA 合规率和违规率 +- 风险随时间的变化趋势 + +这意味着资产的结构方式会直接影响报告的准确性和实用性。例如，将多个不相关的系统归入同一个资产可能会掩盖风险的可见性，而过于细碎的资产结构则可能使报告变得零散，难以识别更宏观的趋势。 + +特定资产的指标可以通过所选资产视图顶部栏中的**指标**按钮访问。 + +![image](images/asset_ss8.png) + +### CI/CD 流水线 + +CI/CD 流水线可自动导入扫描结果。无论采用何种集成方式，所有扫描导入都必须关联到某个资产，这使得资产成为流水线驱动的安全数据的锚点。 + +当流水线提交扫描结果时，必须满足以下条件之一： + +- 指定一个现有资产（并可选择指定一个测试活动），或者 +- 以某种方式进行配置，使结果能够始终一致地映射到正确的资产 + +所有导入的发现项都会继承该资产的上下文信息，包括所有权归属、权限、SLA 配置和报告范围。 + +在实践中，资产的定义应当反映系统在 CI/CD 中的构建和部署方式，以确保安全结果始终与正确的应用程序或服务相关联。 + +### Jira 关联关系 + +资产可以直接映射到 Jira 项目，从而将该资产的发现项推送到 Jira 实例中。 + +由于发现项会从其父级资产继承风险、优先级和所有权归属，资产实际上决定了流入 Jira 工单和下游连接器工作流程的修复上下文。 + +需要特别指出的是，资产同样是决定发现项 SLA 特性的主要因素。因此，某个发现项的 SLA 取决于其父级资产的 SLA 配置。有关 SLA 配置的更多信息，请参见[此处](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content)。 diff --git a/docs/content/asset_modelling/engagements_tests/OS__calendar.it.md b/docs/content/asset_modelling/engagements_tests/OS__calendar.it.md new file mode 100644 index 0000000000..267849119e --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__calendar.it.md @@ -0,0 +1,61 @@ +--- +title: Calendario +description: Come utilizzare il Calendario in DefectDojo Pro +audience: opensource +weight: 9 +--- + +Il Calendario di DefectDojo fornisce una vista cronologica centralizzata di tutti gli Engagement e i Test con date di inizio e fine definite, permettendo agli Utenti di comprendere rapidamente l'attività di test tra i Prodotti, identificare sovrapposizioni di pianificazione e navigare direttamente verso gli oggetti correlati. + +Quando un Utente crea un Engagement o un Test e definisce le date di inizio e fine, una voce corrispondente viene aggiunta automaticamente al Calendario. Le voci compaiono in tutte le date comprese tra la data di inizio definita e la data di fine definita, inclusa. + +## Accesso al Calendario + +La pagina Calendario è accessibile tramite il pulsante Calendar nella barra laterale. + +![image](images/OSC_ss3.png) + +## Visibilità e permessi + +### Visibilità + +La pagina Calendario include filtri nella parte superiore e una griglia mensile del Calendario sottostante. Usa i controlli di navigazione sopra il Calendario per spostarti tra i mesi. + +La vista mensile viene visualizzata come una griglia fissa di sei settimane, a partire dalla settimana che contiene il primo giorno del mese selezionato. + +Le voci visibili nel Calendario possono essere filtrate in base al tipo di oggetto (Engagement o Test) e al Testing Lead, stabilito nelle impostazioni dell'Engagement o del Test. Dopo aver selezionato i criteri di filtro, fai clic su Apply per aggiornare la vista del Calendario. + +Può essere visualizzato un solo tipo di oggetto alla volta. Il passaggio tra Engagement e Test aggiorna di conseguenza la vista del Calendario. + +### Permessi + +Il Calendario rispetta i permessi a livello di oggetto di DefectDojo. Gli Utenti vedono solo gli Engagement e i Test a cui sono autorizzati ad accedere. + +## Visualizzazione e interazione con le voci + +All'interno di ogni cella data, le voci sono ordinate alfabeticamente in base al nome dell'oggetto. Facendo clic su una voce si viene reindirizzati all'oggetto corrispondente. + +Il numero di voci visualizzabili in ogni giorno è dinamico e varia in base alle dimensioni dello schermo e al livello di zoom del browser. Se il numero di voci supera lo spazio disponibile in una cella data, in fondo alla cella appare un link nel formato “+X more”. + +![image](images/OSC_ss1.png) + +Fai clic sul link “+X more” per aprire una finestra modale che mostra tutte le voci per quella data. + +![image](images/OSC_ss2.png) + +È importante notare che il Calendario stesso è una vista di sola lettura. Le date devono essere modificate all'interno delle impostazioni dell'oggetto Engagement o Test stesso. + +### Logica di denominazione + +La denominazione delle voci nel Calendario varia leggermente a seconda del tipo di oggetto. + +Le voci Engagement includono: +- Nome del Prodotto +- Nome dell'Engagement +- Testing Lead + +Le voci Test includono: +- Nome del Prodotto +- Nome dell'Engagement +- Tipo di Test +- Testing Lead diff --git a/docs/content/asset_modelling/engagements_tests/OS__calendar.pt-br.md b/docs/content/asset_modelling/engagements_tests/OS__calendar.pt-br.md new file mode 100644 index 0000000000..d3473583cb --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__calendar.pt-br.md @@ -0,0 +1,61 @@ +--- +title: Calendário +description: Como usar o Calendário no DefectDojo Pro +audience: opensource +weight: 9 +--- + +O Calendário do DefectDojo oferece uma visão cronológica centralizada de todos os Engajamentos e Testes com datas de início e término definidas, permitindo que os Usuários entendam rapidamente a atividade de testes entre os Produtos, identifiquem sobreposições de agenda e naveguem diretamente para os objetos relacionados. + +Quando um Usuário cria um Engajamento ou Teste e define as datas de início e término, uma entrada correspondente é adicionada automaticamente ao Calendário. As entradas aparecem em todas as datas a partir da data de início definida até a data de término definida, inclusive. + +## Acessando o Calendário + +A página do Calendário é acessível por meio do botão Calendar na barra lateral. + +![image](images/OSC_ss3.png) + +## Visibilidade e Permissões + +### Visibilidade + +A página do Calendário inclui filtros na parte superior e uma grade mensal do Calendário abaixo. Use os controles de navegação acima do Calendário para se mover entre os meses. + +A visualização mensal é exibida como uma grade fixa de seis semanas, começando pela semana que contém o primeiro dia do mês selecionado. + +As entradas visíveis no Calendário podem ser filtradas com base no tipo de objeto (Engajamentos ou Testes) e no Líder de Testes, definido nas configurações do Engajamento ou Teste. Depois de selecionar os critérios de filtro, clique em Apply para atualizar a visualização do Calendário. + +Apenas um tipo de objeto pode ser exibido por vez. Alternar entre Engajamentos e Testes atualiza a visualização do Calendário de acordo. + +### Permissões + +O Calendário respeita as permissões em nível de objeto do DefectDojo. Os Usuários só veem os Engajamentos e Testes aos quais têm autorização para acessar. + +## Visualizando e Interagindo com Entradas + +Dentro de cada célula de data, as entradas são ordenadas alfabeticamente com base no nome do objeto. Clicar em uma entrada redireciona para o objeto correspondente. + +O número de entradas visíveis em cada dia é dinâmico e varia dependendo do tamanho da tela e do nível de zoom do navegador. Se o número de entradas exceder o espaço disponível em uma célula de data, um link no formato “+X more” aparece na parte inferior da célula. + +![image](images/OSC_ss1.png) + +Clique no link “+X more” para abrir um modal exibindo todas as entradas daquela data. + +![image](images/OSC_ss2.png) + +É importante notar que o Calendário em si é uma visualização somente leitura. As datas devem ser modificadas nas configurações do próprio objeto de Engajamento ou Teste. + +### Lógica de Nomenclatura + +A nomenclatura das entradas no Calendário varia ligeiramente dependendo do tipo de objeto. + +As entradas de Engajamento incluem: +- Nome do Produto +- Nome do Engajamento +- Líder de Testes + +As entradas de Teste incluem: +- Nome do Produto +- Nome do Engajamento +- Tipo de Teste +- Líder de Testes diff --git a/docs/content/asset_modelling/engagements_tests/OS__calendar.zh-hans.md b/docs/content/asset_modelling/engagements_tests/OS__calendar.zh-hans.md new file mode 100644 index 0000000000..bc57a05a34 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__calendar.zh-hans.md @@ -0,0 +1,61 @@ +--- +title: 日历 +description: 如何在 DefectDojo Pro 中使用日历 +audience: opensource +weight: 9 +--- + +DefectDojo 的日历为所有已定义开始和结束日期的测试活动和测试提供了集中式的时间线视图，让用户能够快速了解各产品间的测试活动情况、识别日程安排上的重叠，并直接导航到相关对象。 + +当用户创建某个测试活动或测试并设置开始和结束日期后，系统会自动在日历中添加相应的条目。条目会显示在从设定的开始日期到设定的结束日期（含首尾两天）之间的所有日期上。 + +## 访问日历 + +可以通过侧边栏中的日历按钮访问日历页面。 + +![image](images/OSC_ss3.png) + +## 可见性与权限 + +### 可见性 + +日历页面顶部包含筛选条件，下方是按月显示的日历网格。使用日历上方的导航控件可以在各月之间切换。 + +月视图以固定的六周网格显示，从包含所选月份第一天的那一周开始。 + +日历中显示的条目可以按对象类型（测试活动或测试）以及测试负责人进行筛选，测试负责人是在测试活动或测试的设置中指定的。选择筛选条件后，点击“应用”即可刷新日历视图。 + +同一时间只能显示一种对象类型。在测试活动和测试之间切换会相应地更新日历视图。 + +### 权限 + +日历遵循 DefectDojo 的对象级权限设置。用户只能看到自己有权访问的测试活动和测试。 + +## 查看和操作条目 + +在每个日期单元格中，条目按对象名称的字母顺序排序。点击某个条目会跳转到相应的对象。 + +每天可见的条目数量是动态的，会随屏幕尺寸和浏览器缩放级别而变化。如果条目数量超出了日期单元格的可用空间，单元格底部会显示一个格式为“+X more”的链接。 + +![image](images/OSC_ss1.png) + +点击“+X more”链接可以打开一个模态框，显示该日期的所有条目。 + +![image](images/OSC_ss2.png) + +需要特别指出的是，日历本身是一个只读视图。日期必须在测试活动或测试对象自身的设置中进行修改。 + +### 命名逻辑 + +日历中条目的命名方式会根据对象类型略有不同。 + +测试活动条目包括： +- 产品名称 +- 测试活动名称 +- 测试负责人 + +测试条目包括： +- 产品名称 +- 测试活动名称 +- 测试类型 +- 测试负责人 diff --git a/docs/content/asset_modelling/engagements_tests/OS__engagements.it.md b/docs/content/asset_modelling/engagements_tests/OS__engagements.it.md new file mode 100644 index 0000000000..a8ecc612aa --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__engagements.it.md @@ -0,0 +1,182 @@ +--- +title: Engagement +description: Informazioni sugli Engagement in DefectDojo OS +audience: opensource +weight: 3 +--- + +Organizzazioni → Asset → **ENGAGEMENT** → Test → Riscontri + +## Panoramica + +Nella gerarchia dei prodotti di DefectDojo, gli Engagement sono contenitori delimitati nel tempo o legati a una pipeline che rappresentano gruppi di Test correlati all'interno di uno specifico Prodotto. Se hai pianificato un'attività di test, sia essa ricorrente o una tantum, un Engagement ti offre un luogo in cui archiviare tutti i risultati correlati. + +Esempi di Engagement includono: +- Penetration test una tantum +- Scansioni ricorrenti mensili o trimestrali +- Periodi di revisione per bug bounty +- Esecuzioni di pipeline CI/CD (per i team che trattano ogni pipeline come un proprio Engagement) +- Cicli di rilascio del codice (ad es. “revisione di sicurezza per il rilascio v4.2”) + +### Tipi di Engagement + +DefectDojo supporta due tipi di Engagement: **Interattivo** e **CI/CD**. Questi tipi determinano il modo in cui i Test vengono generalmente creati e come vengono importati i risultati delle scansioni. + +Un Engagement Interattivo viene generalmente condotto da un ingegnere. Gli Engagement Interattivi si concentrano sul test di un'applicazione mentre è in esecuzione, tramite un test automatizzato, un tester umano o qualsiasi attività che “interagisca” con le funzionalità dell'applicazione. + +Un Engagement CI/CD è pensato per l'integrazione automatizzata con una pipeline CI/CD. Gli Engagement CI/CD sono destinati a importare dati come azione automatizzata, attivata da una fase del processo di rilascio. + +| **Categoria** | **Engagement Interattivi** | **Engagement CI/CD** | +|------------------------|--------------------------------------------------------------|--------------------------------------------------------------------| +| **Caso d'uso principale** | Test di sicurezza manuali o ad-hoc | Test di sicurezza automatizzati e ricorrenti all'interno delle pipeline | +| **Durata** | Delimitata nel tempo e finita | Durata potenzialmente infinita | +| **Frequenza** | Periodica o una tantum | Continua o per ogni commit | +| **Flusso di lavoro** | Il tester umano esegue lo strumento → importa manualmente i risultati | La pipeline esegue lo strumento → invia automaticamente i risultati a DefectDojo | +| **Metodo di importazione dei risultati** | Caricamento manuale tramite UI o CLI | Importazione basata su API tramite automazione (ad es. CLI, connettori, cron job, script di pipeline) | +| **Tipo di test tipico** | Penetration test, esercitazioni red team, valutazioni manuali | Analisi statica, scansione delle dipendenze, scansione dei container | + +### Dati dell'Engagement + +In quanto contenitori che organizzano l'attività di test, gli Engagement possono archiviare o tracciare una varietà di dati: + +- Date di inizio e fine previste +- Descrizione e note sull'ambito +- Stato (in corso, pianificato, completato, ecc.) +- Assegnatario / Responsabile +- Test associati (ad es. scansioni, penetration test, test manuali, ecc.) +- Riscontri e tipi di Riscontro (ad es. attivo, mitigato, rischio accettato, duplicato, ecc.) +- Modelli di minaccia o informazioni sull'accettazione del rischio +- Tag +- File e note +- Impostazioni del progetto Jira +- Dettagli sull'ambiente (ad es. staging vs. produzione) +- ID di build (se collegato a CI/CD) +- Dati storici dei Test precedenti all'interno dell'Engagement + +## Accesso agli Engagement + +Gli Engagement sono accessibili tramite la barra laterale. Il sottomenu fornisce l'accesso a Engagement attivi e Tutti gli Engagement, oltre alla possibilità di visualizzare gli Engagement organizzati per Prodotto, tipo di Test e ambiente. + +![image](images/engagement_ss17.png) + +In alternativa, è possibile accedere agli Engagement di un determinato Prodotto dal sottomenu dell'opzione Engagement nella barra superiore. + +![image](images/engagement_ss18.png) + +### Permessi + +Gli Engagement si collocano al di sotto dei Prodotti e al di sopra dei Test nella gerarchia degli oggetti. Di conseguenza, l'accesso a un Prodotto concede automaticamente l'accesso a tutti gli Engagement al suo interno. Gli Engagement non dispongono di liste di controllo degli accessi indipendenti. + +## Utilizzo degli Engagement + +### Creazione di Engagement + +Esistono diversi approcci per creare un Engagement. Ciascun approccio richiede che venga prima creato un Prodotto che lo contenga. + +Una volta creato un Prodotto, è possibile aggiungere un nuovo Engagement Interattivo o CI/CD nella sezione Engagement della barra di navigazione del Prodotto. + +![image](images/engagement_ss4.png) + +Ogni Engagement deve avere definiti i seguenti campi: +- Tipo (Interattivo o CI/CD) +- Un nome univoco +- Date di inizio e fine previste + - Questo determinerà la comparsa dell'Engagement nella sezione Calendario +- Prodotto +- Stato + +#### Stati dell'Engagement + +Gli Engagement possono essere contrassegnati con stati diversi al momento della creazione. Lo stato può anche essere modificato in seguito nelle impostazioni dell'Engagement. + +Un Engagement può avere uno dei seguenti stati: +- Non iniziato +- Bloccato +- Annullato +- Completato +- In corso +- In sospeso +- Pianificato +- In attesa di risorsa + +Modificare lo stato di un Engagement in “Completato” comporterà che la maggior parte delle operazioni di scrittura (ad es. l'aggiunta di test, l'importazione di scansioni) diventino non disponibili o nascoste. Gli altri stati non influiscono in modo sostanziale sulla funzionalità dell'Engagement e servono principalmente a scopi di filtraggio/informativi. + +### Modifica degli Engagement + +Gli Engagement possono essere modificati facendo clic sul pulsante **Modifica** all'interno delle impostazioni dell'Engagement. Tutti i campi modificabili sono disponibili anche durante la creazione dell'Engagement. + +### Copia degli Engagement + +È possibile duplicare facilmente gli Engagement accedendo all'elenco degli Engagement all'interno di un Prodotto e facendo clic sul pulsante **Copia** dal menu kebab ⋮ accanto all'Engagement da copiare. Questo creerà una copia esatta dell'Engagement originale all'interno del Prodotto principale, inclusi i metadati, i Test e i Riscontri in esso contenuti. + +![image](images/engagement_ss19.png) + +### Chiusura degli Engagement + +Gli Engagement possono essere chiusi accedendo all'elenco degli Engagement all'interno di un Prodotto e facendo clic su “Chiudi” dal menu kebab ⋮ dell'Engagement scelto. + +![image](images/engagement_ss20.png) + +Una volta chiuso, lo stato dell'Engagement verrà modificato in “Completato”. Tuttavia, la maggior parte delle operazioni di scrittura (ad es. l'aggiunta di test, l'importazione di scansioni) rimarrà disponibile. + +La chiusura di un Engagement non modifica lo stato dei Riscontri all'interno di nessuno dei Test dell'Engagement. I Riscontri rimangono attivi, mitigati o a rischio accettato in base al proprio ciclo di vita e restano accessibili per la visualizzazione e la reportistica. + +Se l'Engagement è collegato a un Epic di Jira (vedi **[Integrazione Jira: Abilita il mapping Epic per gli Engagement](/connectors/os_jira/os__jira_guide/#enable-engagement-epic-mapping-for-products)**), la chiusura dell'Engagement attiverà un'attività asincrona che chiude l'Epic Jira associato nel tuo Jira Space collegato. + +### Riapertura degli Engagement + +Se un Engagement è chiuso, può essere riaperto facendo clic su **Riapri** dal menu kebab ⋮ nella tabella degli Engagement chiusi. Questo renderà nuovamente attivo l'Engagement e riporterà il suo stato a “In corso”. + +![image](images/engagement_ss21.png) + +### Engagement scaduti + +Un Engagement scade una volta superata la data di fine prevista. + +La scadenza dell'Engagement non ha un impatto diretto sulla sua funzionalità e serve principalmente come meccanismo di monitoraggio/notifica. + +Una volta scaduto, nel campo “Durata” dell'Engagement comparirà una notifica rossa “In ritardo di X giorni”, che tuttavia non limiterà alcuna funzionalità dell'Engagement. Lo stato dell'Engagement continuerà a comparire come “In corso”. + +Sebbene non sia abilitata per impostazione predefinita, nelle impostazioni di sistema è disponibile un'opzione per chiudere automaticamente un Engagement una volta scaduto da un determinato numero di giorni. + +![image](images/engagement_ss22.png) + +### Eliminazione degli Engagement + +L'eliminazione di un Engagement può essere effettuata selezionando **Elimina** dalle impostazioni dell'Engagement. Questa azione non può essere annullata. + +L'eliminazione di un Engagement comporterà anche l'eliminazione di quanto segue: +- Tutti i Test associati all'Engagement +- Tutti i Riscontri contenuti in tali Test +- Eventuali mapping con Epic Jira collegati (l'Epic stesso rimarrà in Jira, ma il collegamento tra DefectDojo e Jira verrà rimosso) +- Tutte le note e i file caricati associati all'Engagement + +A fini di audit, si consiglia di chiudere gli Engagement completati anziché eliminarli. + +| **Operazione** | **Risultati** | **Reversibile** | +|----------|---------|------------| +| **Chiudi** | Contrassegna come inattivo; i dati rimangono; può essere riaperto | Sì (riapertura) | +| **Scadenza** | Solo avviso visivo; chiusura automatica opzionale; notifiche | N/D | +| **Elimina** | Rimuove definitivamente Engagement, Test, Riscontri, note, file ed eventuali mapping con Epic Jira (gli Epic rimangono in Jira) | No | + +## Integrazione con Jira + +Gli Engagement possono essere collegati a uno Jira Space connesso, consentendo di inviare a Jira, come Issue, i Riscontri contenuti nell'Engagement. Per una guida completa alla configurazione di Jira, vedi **[Collegare DefectDojo a Jira](/connectors/os_jira/os__jira_guide/)**. + +### Mapping Epic dell'Engagement + +Quando l'opzione **Abilita mapping Epic per gli Engagement** è selezionata nelle impostazioni Jira di un Prodotto, gli Engagement verranno inviati a Jira come Epic. I Riscontri contenuti nell'Engagement vengono inviati come Issue figlie sotto l'Epic, rispecchiando la gerarchia Engagement → Riscontri di DefectDojo nella struttura Epic → Issue di Jira. + +Per maggiori informazioni su questa impostazione, vedi **[Abilita mapping Epic per gli Engagement](/connectors/os_jira/os__jira_guide/#enable-engagement-epic-mapping-for-products)**. + +### Impostazioni Jira a livello di Engagement + +Per impostazione predefinita, gli Engagement ereditano le proprie impostazioni Jira dal Prodotto principale. Tuttavia, i singoli Engagement possono sovrascrivere queste impostazioni per utilizzare configurazioni Jira diverse. Le seguenti impostazioni possono essere personalizzate per ogni Engagement: + +- **Project Key** — instrada i Riscontri verso uno Jira Space diverso +- **Issue Template** — utilizza un modello diverso per le Issue create da questo Engagement +- **Custom Fields** — applica mapping di campi personalizzati diversi +- **Jira Labels** — contrassegna le Issue con etichette specifiche dell'Engagement +- **Default Assignee** — assegna le Issue a un altro membro del team + +Queste impostazioni sono accessibili dalla pagina **Modifica Engagement**. Per maggiori dettagli, vedi **[Impostazioni Jira a livello di Engagement](/connectors/os_jira/os__jira_guide/#engagement-level-jira-settings)**. diff --git a/docs/content/asset_modelling/engagements_tests/OS__engagements.pt-br.md b/docs/content/asset_modelling/engagements_tests/OS__engagements.pt-br.md new file mode 100644 index 0000000000..a95a35d3a5 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__engagements.pt-br.md @@ -0,0 +1,182 @@ +--- +title: Engajamentos +description: Entendendo os Engajamentos no DefectDojo OS +audience: opensource +weight: 3 +--- + +Organizações → Ativos → **ENGAJAMENTOS** → Testes → Achados + +## Visão geral + +Na hierarquia de produtos do DefectDojo, os Engajamentos são contêineres limitados por tempo ou por pipeline que representam grupos de Testes relacionados dentro de um Produto específico. Se você tiver um esforço de teste planejado e agendado, seja em uma base rotineira ou pontual, um Engajamento oferece um local para armazenar todos os resultados relacionados. + +Exemplos de Engajamentos incluem: +- Testes de penetração pontuais +- Varreduras mensais ou trimestrais recorrentes +- Períodos de revisão de bug bounty +- Execuções de pipeline de CI/CD (para equipes que tratam cada pipeline como seu próprio Engajamento) +- Ciclos de lançamento de código (por exemplo, "revisão de segurança do lançamento v4.2") + +### Tipos de Engajamento + +O DefectDojo oferece suporte a dois tipos de Engajamento: **Interativo** e **CI/CD**. Esses tipos determinam como os Testes normalmente são criados e como os resultados das varreduras são importados. + +Um Engajamento Interativo normalmente é conduzido por um engenheiro. Os Engajamentos Interativos são focados em testar uma aplicação enquanto ela está em execução, usando um teste automatizado, um testador humano, ou qualquer atividade que "interaja" com a funcionalidade da aplicação. + +Um Engajamento de CI/CD é destinado à integração automatizada com um pipeline de CI/CD. Os Engajamentos de CI/CD têm como objetivo importar dados como uma ação automatizada, acionada por uma etapa no processo de lançamento. + +| **Categoria** | **Engajamentos Interativos** | **Engajamentos de CI/CD** | +|------------------------|--------------------------------------------------------------|--------------------------------------------------------------------| +| **Caso de Uso Principal** | Testes de segurança manuais ou pontuais | Testes de segurança automatizados e recorrentes dentro de pipelines | +| **Duração** | Limitada no tempo e finita | Duração potencialmente infinita | +| **Frequência** | Periódica ou pontual | Contínua ou por commit | +| **Fluxo de Trabalho** | Testador humano executa a ferramenta → importa os resultados manualmente | Pipeline executa a ferramenta → envia os resultados automaticamente ao DefectDojo | +| **Método de Importação de Resultados** | Upload manual via UI ou CLI | Importação orientada por API via automação (por exemplo, CLI, conectores, cron jobs, scripts de pipeline) | +| **Tipo de Teste Típico** | Testes de penetração, exercícios de red team, avaliações manuais | Análise estática, varredura de dependências, varredura de contêineres | + +### Dados do Engajamento + +Como contêineres que organizam a atividade de teste, os Engajamentos podem armazenar ou rastrear uma variedade de dados: + +- Datas de início e término previstas +- Descrição e notas de escopo +- Status (em andamento, planejado, concluído, etc.) +- Responsável / Líder +- Testes associados (por exemplo, varreduras, testes de penetração, testes manuais, etc.) +- Achados e Tipos de Achado (por exemplo, ativo, mitigado, risco aceito, duplicado, etc.) +- Modelos de ameaça ou informações de aceitação de risco +- Tags +- Arquivos e notas +- Configurações do projeto Jira +- Detalhes do ambiente (por exemplo, staging vs. produção) +- IDs de build (se vinculado a CI/CD) +- Dados históricos de Testes anteriores dentro do Engajamento + +## Acessando Engajamentos + +Os Engajamentos são acessíveis pela barra lateral. O submenu oferece acesso a Engajamentos Ativos e Todos os Engajamentos, além da opção de visualizar os Engajamentos organizados por Produto, tipos de Teste e Ambientes. + +![image](images/engagement_ss17.png) + +Alternativamente, os Engajamentos dentro de um Produto específico podem ser acessados pelo submenu da opção Engajamentos na barra superior. + +![image](images/engagement_ss18.png) + +### Permissões + +Os Engajamentos ficam abaixo dos Produtos e acima dos Testes na hierarquia de objetos. Assim, o acesso a um Produto concede automaticamente acesso a todos os Engajamentos dentro desse Produto. Os Engajamentos não possuem listas de controle de acesso independentes. + +## Trabalhando com Engajamentos + +### Criar Engajamentos + +Existem várias abordagens para criar um Engajamento. Cada abordagem exige que você primeiro crie um Produto para contê-lo. + +Depois de criar um Produto, você pode adicionar um novo Engajamento Interativo ou de CI/CD na seção Engajamentos da barra de navegação do Produto. + +![image](images/engagement_ss4.png) + +Todo Engajamento deve ter os seguintes campos definidos: +- Tipo (Interativo ou CI/CD) +- Um nome exclusivo +- Datas de início e término previstas + - Isso determinará a aparência do Engajamento na seção Calendário +- Produto +- Status + +#### Status de Engajamento + +Os Engajamentos podem receber diferentes status no momento da criação. O status também pode ser alterado posteriormente nas configurações do Engajamento. + +Um Engajamento pode ter qualquer um dos seguintes status: +- Não iniciado +- Bloqueado +- Cancelado +- Concluído +- Em andamento +- Em espera +- Agendado +- Aguardando recurso + +Alterar o status de um Engajamento para "Concluído" significa que a maioria das operações de escrita (por exemplo, adicionar testes, importar varreduras) ficará indisponível ou oculta. Outros status não afetam materialmente a funcionalidade do Engajamento, servindo mais para fins de filtragem/informação. + +### Editar Engajamentos + +Os Engajamentos podem ser editados clicando no botão **Editar** dentro das configurações do Engajamento. Todos os campos subsequentes que podem ser editados também estão disponíveis quando o Engajamento está sendo criado. + +### Copiar Engajamentos + +Você pode duplicar facilmente os Engajamentos navegando até a lista de Engajamentos dentro de um Produto e clicando no botão **Copiar** dentro do menu kebab ⋮ ao lado do Engajamento a ser copiado. Isso criará uma cópia exata do Engajamento original dentro do Produto pai, incluindo os metadados, Testes e Achados contidos nele. + +![image](images/engagement_ss19.png) + +### Fechar Engajamentos + +Os Engajamentos podem ser fechados navegando até a lista de Engajamentos dentro de um Produto e clicando em "Fechar" dentro do menu kebab ⋮ do Engajamento escolhido. + +![image](images/engagement_ss20.png) + +Depois de fechado, o status do Engajamento será alterado para "Concluído". Ainda assim, a maioria das operações de escrita (por exemplo, adicionar testes, importar varreduras) permanecerá disponível. + +Fechar um Engajamento não altera o status dos Achados dentro de nenhum dos Testes do Engajamento. Os Achados permanecem ativos, mitigados ou com risco aceito de acordo com seu próprio ciclo de vida, e continuam acessíveis para visualização e geração de relatórios. + +Se o Engajamento estiver vinculado a um Épico do Jira (consulte **[Integração com o Jira: Habilitar Mapeamento de Épico de Engajamento](/connectors/os_jira/os__jira_guide/#enable-engagement-epic-mapping-for-products)**), fechar o Engajamento acionará uma tarefa assíncrona que fecha o Épico do Jira associado no seu Espaço Jira conectado. + +### Reabrir Engajamentos + +Se um Engajamento estiver fechado, ele pode ser reaberto clicando em **Reabrir** dentro do menu kebab ⋮ na tabela de Engajamentos Fechados. Isso tornará o Engajamento ativo novamente e retornará seu status para "Em andamento". + +![image](images/engagement_ss21.png) + +### Engajamentos Expirados + +Um Engajamento expira quando sua data de término prevista é ultrapassada. + +A expiração do Engajamento não tem impacto direto sobre sua funcionalidade, servindo principalmente como um mecanismo de monitoramento/notificação. + +Depois de expirado, uma notificação vermelha "X dias em atraso" aparecerá no campo "Duração" do Engajamento, mas isso não restringirá nenhuma funcionalidade do Engajamento. O status do Engajamento continuará aparecendo como "Em andamento". + +Embora não esteja habilitada por padrão, existe uma opção nas configurações do sistema para fechar automaticamente um Engajamento depois que ele estiver expirado por um determinado número de dias. + +![image](images/engagement_ss22.png) + +### Excluir Engajamentos + +A exclusão de um Engajamento pode ser realizada selecionando **Excluir** nas configurações do Engajamento. Essa ação não pode ser desfeita. + +Excluir um Engajamento também excluirá o seguinte: +- Quaisquer Testes associados ao Engajamento +- Todos os Achados contidos nesses Testes +- Quaisquer mapeamentos de Épico do Jira vinculados (o Épico em si permanecerá no Jira, mas o vínculo entre o DefectDojo e o Jira será removido) +- Todas as notas e arquivos enviados associados ao Engajamento + +Para fins de auditoria, recomenda-se fechar os Engajamentos concluídos, em vez de excluí-los. + +| **Operação** | **Resultados** | **Reversível** | +|----------|---------|------------| +| **Fechar** | Marca como inativo; os dados permanecem; pode ser reaberto | Sim (reabrir) | +| **Expirar** | Apenas aviso visual; fechamento automático opcional; notificações | N/A | +| **Excluir** | Remove permanentemente o Engajamento, Testes, Achados, notas, arquivos e quaisquer mapeamentos de Épico do Jira (os Épicos permanecem no Jira) | Não | + +## Integração com o Jira + +Os Engajamentos podem ser vinculados a um Espaço Jira conectado, permitindo que os Achados dentro do Engajamento sejam enviados ao Jira como Issues. Para um guia completo sobre a configuração do Jira, consulte **[Conectando o DefectDojo ao Jira](/connectors/os_jira/os__jira_guide/)**. + +### Mapeamento de Épico de Engajamento + +Quando a opção **Habilitar Mapeamento de Épico de Engajamento** está marcada nas configurações do Jira de um Produto, os Engajamentos são enviados ao Jira como Épicos. Os Achados dentro do Engajamento são enviados como Issues filhas abaixo do Épico, espelhando a hierarquia Engajamento → Achados do DefectDojo na estrutura Épico → Issue do Jira. + +Para mais informações sobre essa configuração, consulte **[Habilitar Mapeamento de Épico de Engajamento](/connectors/os_jira/os__jira_guide/#enable-engagement-epic-mapping-for-products)**. + +### Configurações do Jira em Nível de Engajamento + +Por padrão, os Engajamentos herdam suas configurações do Jira do Produto pai. No entanto, Engajamentos individuais podem substituir essas configurações para usar configurações diferentes do Jira. As seguintes configurações podem ser personalizadas por Engajamento: + +- **Chave do Projeto** — direciona os Achados para um Espaço Jira diferente +- **Template de Issue** — usa um template diferente para Issues criadas a partir deste Engajamento +- **Campos Personalizados** — aplica mapeamentos de campos personalizados diferentes +- **Labels do Jira** — marca Issues com labels específicas do Engajamento +- **Responsável Padrão** — atribui Issues a um membro diferente da equipe + +Essas configurações são acessíveis na página **Editar Engajamento**. Para mais detalhes, consulte **[Configurações do Jira em Nível de Engajamento](/connectors/os_jira/os__jira_guide/#engagement-level-jira-settings)**. diff --git a/docs/content/asset_modelling/engagements_tests/OS__engagements.zh-hans.md b/docs/content/asset_modelling/engagements_tests/OS__engagements.zh-hans.md new file mode 100644 index 0000000000..474b977084 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__engagements.zh-hans.md @@ -0,0 +1,182 @@ +--- +title: 测试活动 +description: 了解 DefectDojo OS 中的测试活动 +audience: opensource +weight: 3 +--- + +组织 → 资产 → **测试活动** → 测试 → 发现项 + +## 概述 + +在 DefectDojo 的产品层级结构中,测试活动(Engagement)是以时间或流水线为边界的容器,代表特定产品内一组相关测试的集合。如果您安排了一项计划中的测试工作,无论是例行性质还是一次性的,测试活动都能为您提供一个存放所有相关结果的地方。 + +测试活动的示例包括: +- 一次性渗透测试 +- 按月或按季度进行的定期扫描 +- 漏洞赏金审查周期 +- CI/CD 流水线运行(适用于将每次流水线运行视为独立测试活动的团队) +- 代码发布周期(例如“v4.2 版本发布安全审查”) + +### 测试活动类型 + +DefectDojo 支持两种测试活动类型:**交互式(Interactive)** 和 **CI/CD**。这些类型决定了测试通常是如何创建的,以及扫描结果是如何导入的。 + +交互式测试活动通常由工程师执行。交互式测试活动侧重于在应用程序运行期间对其进行测试,可以使用自动化测试、人工测试人员,或任何与应用程序功能进行“交互”的活动。 + +CI/CD 测试活动用于与 CI/CD 流水线的自动化集成。CI/CD 测试活动旨在作为自动化操作导入数据,由发布流程中的某个步骤触发。 + +| **类别** | **交互式测试活动** | **CI/CD 测试活动** | +|------------------------|--------------------------------------------------------------|--------------------------------------------------------------------| +| **主要用例** | 手动或临时性的安全测试 | 流水线内自动化、定期的安全测试 | +| **持续时间** | 有时间限制,持续时间有限 | 可能持续时间无限 | +| **频率** | 周期性或一次性 | 持续进行或按提交触发 | +| **工作流程** | 人工测试人员运行工具 → 手动导入结果 | 流水线运行工具 → 自动将结果推送至 DefectDojo | +| **结果导入方式** | 通过界面或 CLI 手动上传 | 通过自动化方式进行 API 驱动的导入(例如 CLI、连接器、定时任务、流水线脚本) | +| **典型测试类型** | 渗透测试、红队演练、人工评估 | 静态分析、依赖项扫描、容器扫描 | + +### 测试活动数据 + +作为组织测试活动的容器,测试活动可以存储或跟踪各种数据: + +- 目标开始和结束日期 +- 描述和范围说明 +- 状态(进行中、计划中、已完成等) +- 负责人/主导人 +- 关联的测试(例如扫描、渗透测试、人工测试等) +- 发现项及发现项类型(例如活动、已缓解、风险已接受、重复等) +- 威胁模型或风险接受信息 +- 标签 +- 文件和备注 +- Jira 项目设置 +- 环境详情(例如预发布环境与生产环境) +- 构建 ID(如果与 CI/CD 关联) +- 该测试活动内以往测试的历史数据 + +## 访问测试活动 + +测试活动可通过侧边栏访问。子菜单提供了对活动中的测试活动和所有测试活动的访问入口,同时还可以选择按产品、测试类型和环境来查看测试活动。 + +![image](images/engagement_ss17.png) + +此外,也可以通过顶部栏中“测试活动”选项的子菜单,访问特定产品内的测试活动。 + +![image](images/engagement_ss18.png) + +### 权限 + +在对象层级结构中,测试活动位于产品之下、测试之上。因此,对某个产品的访问权限会自动授予对该产品内所有测试活动的访问权限。测试活动没有独立的访问控制列表。 + +## 使用测试活动 + +### 创建测试活动 + +创建测试活动有多种方式。每种方式都要求您先创建一个产品来容纳该测试活动。 + +创建产品后,您可以在该产品导航栏的“测试活动”部分添加新的交互式或 CI/CD 测试活动。 + +![image](images/engagement_ss4.png) + +每个测试活动都必须定义以下字段: +- 类型(交互式或 CI/CD) +- 唯一名称 +- 目标开始和结束日期 + - 这将决定该测试活动在日历部分中的显示位置 +- 产品 +- 状态 + +#### 测试活动状态 + +测试活动在创建时可以被标记为不同的状态。之后也可以在测试活动的设置中更改该状态。 + +测试活动可以具有以下任意一种状态: +- 未开始 +- 已阻塞 +- 已取消 +- 已完成 +- 进行中 +- 已暂停 +- 已排期 +- 等待资源 + +将测试活动的状态更改为“已完成”意味着大多数写操作(例如添加测试、导入扫描)将变得不可用或被隐藏。其他状态不会对测试活动的功能产生实质性影响,主要仅用于筛选/信息展示目的。 + +### 编辑测试活动 + +在测试活动的设置中点击 **编辑** 按钮即可对其进行编辑。所有可编辑的字段在创建测试活动时同样可用。 + +### 复制测试活动 + +您可以通过导航到某产品内的测试活动列表,并在要复制的测试活动旁边的 ⋮ 三点菜单中点击 **复制** 按钮,轻松复制测试活动。这将在父产品内创建原测试活动的完全副本,包括其中的元数据、测试和发现项。 + +![image](images/engagement_ss19.png) + +### 关闭测试活动 + +要关闭测试活动,请导航到某产品内的测试活动列表,并在所选测试活动的 ⋮ 三点菜单中点击“关闭”。 + +![image](images/engagement_ss20.png) + +关闭后,测试活动的状态将变更为“已完成”。尽管如此,大多数写操作(例如添加测试、导入扫描)仍然可用。 + +关闭测试活动不会改变其所有测试中发现项的状态。发现项会根据自身的生命周期继续保持打开、已缓解或风险已接受的状态,并且仍可用于查看和生成报告。 + +如果该测试活动已与某个 Jira Epic 关联(参见 **[Jira 集成:启用测试活动 Epic 映射](/connectors/os_jira/os__jira_guide/#enable-engagement-epic-mapping-for-products)**),关闭该测试活动将触发一个异步任务,在您所连接的 Jira 空间中关闭相关联的 Jira Epic。 + +### 重新打开测试活动 + +如果测试活动已关闭,可以在“已关闭测试活动”表格中,通过其 ⋮ 三点菜单点击 **重新打开** 来重新激活该测试活动。这将使该测试活动重新变为活动状态,并将其状态恢复为“进行中”。 + +![image](images/engagement_ss21.png) + +### 已过期测试活动 + +测试活动一旦超过其目标结束日期,就会过期。 + +测试活动过期不会对其功能产生直接影响,主要起到监控/通知机制的作用。 + +过期后,测试活动的“时长”字段中会出现一条红色的“逾期 X 天”提示,但不会限制该测试活动的任何功能。测试活动的状态仍会显示为“进行中”。 + +虽然默认未启用,但系统设置中有一个选项,可以在测试活动过期达到一定天数后自动将其关闭。 + +![image](images/engagement_ss22.png) + +### 删除测试活动 + +在测试活动的设置中选择 **删除** 即可删除该测试活动。此操作无法撤销。 + +删除测试活动还会删除以下内容: +- 与该测试活动关联的所有测试 +- 这些测试中的所有发现项 +- 任何已关联的 Jira Epic 映射(Epic 本身仍会保留在 Jira 中,但 DefectDojo 与 Jira 之间的关联将被移除) +- 与该测试活动关联的所有备注和上传文件 + +出于审计目的,建议关闭已完成的测试活动,而不是将其删除。 + +| **操作** | **结果** | **是否可逆** | +|----------|---------|------------| +| **关闭** | 标记为非活动;数据保留;可重新打开 | 是(可重新打开) | +| **过期** | 仅显示视觉提示;可选自动关闭;发送通知 | 不适用 | +| **删除** | 永久删除测试活动、测试、发现项、备注、文件以及任何 Jira Epic 映射(Epic 仍保留在 Jira 中) | 否 | + +## Jira 集成 + +测试活动可以与已连接的 Jira 空间关联,从而将该测试活动内的发现项作为 Issue 推送到 Jira。有关设置 Jira 的完整指南,请参见 **[将 DefectDojo 连接到 Jira](/connectors/os_jira/os__jira_guide/)**。 + +### 测试活动 Epic 映射 + +当在产品的 Jira 设置中勾选 **启用测试活动 Epic 映射** 时,测试活动会作为 Epic 推送到 Jira。该测试活动内的发现项会作为该 Epic 下的子 Issue 推送,从而在 Jira 的 Epic → Issue 结构中映射出 DefectDojo 的测试活动 → 发现项层级结构。 + +有关此设置的更多信息,请参见 **[启用测试活动 Epic 映射](/connectors/os_jira/os__jira_guide/#enable-engagement-epic-mapping-for-products)**。 + +### 测试活动级 Jira 设置 + +默认情况下,测试活动的 Jira 设置继承自其父产品。但是,单个测试活动可以覆盖这些设置,以使用不同的 Jira 配置。以下设置可按测试活动进行自定义: + +- **Project Key(项目密钥)** — 将发现项路由到不同的 Jira 空间 +- **Issue Template(Issue 模板)** — 为从该测试活动创建的 Issue 使用不同的模板 +- **Custom Fields(自定义字段)** — 应用不同的自定义字段映射 +- **Jira Labels(Jira 标签)** — 使用特定于该测试活动的标签标记 Issue +- **Default Assignee(默认负责人)** — 将 Issue 分配给不同的团队成员 + +这些设置可以在 **编辑测试活动** 页面中访问。有关更多详情,请参见 **[测试活动级 Jira 设置](/connectors/os_jira/os__jira_guide/#engagement-level-jira-settings)**。 diff --git a/docs/content/asset_modelling/engagements_tests/OS__findings.it.md b/docs/content/asset_modelling/engagements_tests/OS__findings.it.md new file mode 100644 index 0000000000..d43f1d8f56 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__findings.it.md @@ -0,0 +1,302 @@ +--- +title: Riscontri +description: Informazioni sui Riscontri in DefectDojo OS +audience: opensource +weight: 5 +--- + +Organizzazioni → Asset → Engagement → Test → **RISCONTRI** + +## Panoramica + +I **Riscontri** rappresentano il livello più basso della Gerarchia dei Prodotti, dove le singole vulnerabilità vengono tracciate e gestite, e costituiscono il modo principale in cui DefectDojo standardizza e guida il processo di reportistica e remediation dei tuoi strumenti di sicurezza. Indipendentemente dal fatto che una vulnerabilità sia stata segnalata da SonarQube, Acunetix o da uno strumento personalizzato del tuo team, i Riscontri ti offrono la possibilità di gestire ogni vulnerabilità allo stesso modo. + +Esempi di Riscontri includono: +- Cookie non contrassegnato come HttpOnly +- Versione obsoleta (PHP) +- Valutazione del codice out-of-band (PHP) +- Versione obsoleta (MySQL) +- Rilevato codice sorgente di backup +- Blind Cross-Site Scripting + +Oltre ad archiviare i dati sulla vulnerabilità e fornire un framework di remediation, DefectDojo migliora i tuoi Riscontri anche nei seguenti modi: +- Aggiunta automatica dei punteggi EPSS correlati a un Riscontro per descriverne la sfruttabilità +- Traduzione automatica della metrica di gravità di uno strumento di sicurezza in un punteggio di Gravità per ogni Riscontro, che assegna al Riscontro un SLA in base alla configurazione SLA del tuo Asset. Per maggiori informazioni sulla configurazione SLA, clicca [qui](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content). + +Nel complesso, i Riscontri sono progettati per funzionare insieme alla Gerarchia dei Prodotti al fine di standardizzare i tuoi sforzi e applicare un metodo coerente a ogni Asset. + +## Accesso ai Riscontri + +I Riscontri sono accessibili tramite la barra laterale. Il sottomenu fornisce l'accesso ai Riscontri aperti e chiusi, a Tutti i Riscontri (indipendentemente dallo stato aperto o chiuso), ai [Riscontri a rischio accettato](/triage_findings/findings_workflows/os__risk_acceptance/), oltre ai Modelli di Riscontro. I singoli Riscontri sono accessibili anche dall'interno del Test che li contiene. + +![image](images/osfindings_ss1.png) + +### Permessi + +Ogni Riscontro appartiene a un Test, il che consente a DefectDojo di conservare l'informazione su quale scansione o valutazione ha originariamente identificato la vulnerabilità. + +Poiché i Riscontri appartengono ai Test, l'accesso ai Riscontri è determinato dall'accesso di un Utente all'Asset che contiene il Test. I Test non dispongono di liste di controllo degli accessi indipendenti. + +## Vista dei Riscontri +Le viste dei Riscontri contengono diverse tabelle utili per interpretare a colpo d'occhio lo stato di un Riscontro. Tra queste: +- **Panoramica** + - **ID**: Il numero ID univoco di quel Riscontro. + - **Gravità**: La valutazione di gravità di quel Riscontro, applicata automaticamente. + - Come menzionato in precedenza, DefectDojo traduce automaticamente la metrica di gravità di uno strumento di sicurezza in un punteggio di Gravità per ogni Riscontro, che assegna al Riscontro un SLA in base alla configurazione SLA del tuo Asset. + - **SLA**: La data di scadenza prevista entro cui il Riscontro dovrebbe essere risolto. + - **Stato**: Lo stato del Riscontro (ad es. Attivo, Verificato, Falso positivo, Duplicato, Fuori ambito e In revisione difetto). + - **Tipo di Riscontro**: Se il Riscontro è Statico (SAST) o Dinamico (DAST). + - **Data di rilevamento**: La data in cui il Riscontro è stato rilevato. + - **CWE**: La classificazione CWE del Riscontro. + - **ID vulnerabilità**: ID delle vulnerabilità presenti negli avvisi di sicurezza associati al Riscontro (ad es. CVE o altre fonti). + - **Rilevato da**: Lo strumento che ha rilevato il Riscontro. +- **Riscontri simili**: Altri Riscontri all'interno dello stesso Asset che non sono duplicati esatti ma presentano valori simili per ID vulnerabilità, CWE, file_path, numero di riga, ecc. +- **Cronologia importazioni**: Elenco delle importazioni/reimportazioni che hanno creato/chiuso/riattivato questo Riscontro in qualsiasi Test. +- **Endpoint/sistemi vulnerabili**: Endpoint/sistemi che il Riscontro rivela essere vulnerabili. +- **Descrizione**: La descrizione del Riscontro (aggiunta automaticamente a seconda del tipo di Riscontro, oppure creata manualmente). +- **Mitigazione**: Passaggi consigliati per la mitigazione. +- **Impatto**: Impatto potenziale nel lasciare il Riscontro irrisolto. +- **Passaggi per la riproduzione**: Passaggi per riprodurre il Riscontro. +- **Motivazione della gravità**: Descrizione scritta del motivo per cui è stata associata al Riscontro una determinata valutazione di Gravità. +- **Riferimenti**: URL per fare riferimento incrociato alla descrizione specifica del Riscontro fornita dallo strumento di scansione di terze parti. Ad esempio, i Riferimenti potrebbero essere link a una voce pertinente in un catalogo di Riscontri, oppure un singolo URL di un avviso. +- **Note**: Note lasciate dagli Utenti relative al Riscontro. Contrassegnare una nota come Privata comporterà la sua esclusione da qualsiasi report generato che includa il Riscontro selezionato. + +## Dati dei Riscontri + +I Riscontri richiedono i seguenti metadati: +**Titolo** +**Data** +**Gravità** +**Descrizione** + +Oltre ai metadati corrispondenti alle tabelle nella vista di un Riscontro, i campi di metadati opzionali includono: +- **Gruppo**: I Gruppi di Riscontri che includono il Riscontro selezionato. +- **Vettore e punteggio CVSS3/CVSS4**: Il vettore e il punteggio CVSS3 e CVSS4 del Riscontro selezionato. +- **Coppie di richiesta e risposta**: Una copia del messaggio inviato dal client e della risposta del server alla richiesta. +- **Endpoint da aggiungere**: Endpoint vulnerabili che potrebbero essere interessati dal Riscontro selezionato e che non sono riportati nell'elenco precedente di sistemi/endpoint. +- **Punteggio e percentile EPSS**: Punteggio e percentile EPSS per la CVE. +- **Data di aggiunta al KEV**: La data in cui il Riscontro è stato aggiunto al catalogo KEV. +- **Disponibilità e versione della correzione**: Definisce se è disponibile una correzione per la vulnerabilità e la versione del componente interessato in cui la correzione è stata implementata. +- **Utente che ha richiesto la revisione del difetto**: Registra chi ha richiesto una revisione del difetto per la vulnerabilità in questione. +- **Numero di riga**: Numero di riga del codice sorgente del vettore di attacco. +- **Percorso del file**: File identificati che contengono il difetto. +- **Nome e versione del componente**: Nome e versione del componente interessato. +- **ID univoco dello strumento**: ID tecnico della vulnerabilità proveniente dallo strumento di origine. +- **ID vulnerabilità dello strumento**: ID tecnico non univoco proveniente dallo strumento di origine. +- **Oggetto sorgente SAST, numero di riga e percorso del file**: Oggetto sorgente, numero di riga e percorso del file del vettore di attacco. +- **Oggetto sink SAST**: Oggetto sink del vettore di attacco. +- **Numero di occorrenze**: Numero di occorrenze nello strumento di origine quando più vulnerabilità sono state rilevate e aggregate dallo scanner. +- **Data di pubblicazione**: Data in cui il Riscontro è stato pubblicato. +- **Servizio**: I Servizi connessi (componenti funzionali autonomi all'interno di un Asset) interessati dal Riscontro selezionato. Quando è popolato, questo campo viene incluso nella corrispondenza di deduplicazione (ovvero, i Riscontri con campi Servizio identici verranno deduplicati). +- **Data e versione di remediation pianificata**: La data entro cui è prevista la remediation del Riscontro e la versione del componente interessato in cui verrà implementata la correzione. +- **Impegno per la correzione**: Il livello di impegno richiesto per correggere il Riscontro (ad es. Bassa, Media o Alta). +- **Tag**: Eventuali tag aggiunti al Riscontro. + +I metadati esatti disponibili dipendono dal parser/scanner che ha rilevato il Riscontro. Alcuni forniscono solo informazioni di base come titolo e gravità, mentre altri includono vettori CVSS, componenti vulnerabili, endpoint, coppie di richiesta/risposta e altri metadati specifici dello scanner. + +Questi metadati migliorano il filtraggio, la reportistica e la definizione delle priorità in tutto il tuo programma di sicurezza, consentendo il tracciamento a lungo termine e l'analisi delle tendenze. Ulteriori dettagli e descrizioni dei metadati sono disponibili [qui](/triage_findings/findings_workflows/intro_to_findings/#a-finding-page). + +### Deduplicazione + +DefectDojo include funzionalità di deduplicazione che aiutano a identificare e gestire i Riscontri che rappresentano la stessa vulnerabilità sottostante. Man mano che i risultati delle scansioni vengono importati da uno o più strumenti, DefectDojo utilizza una logica di corrispondenza configurabile per identificare i Riscontri che rappresentano la stessa vulnerabilità. + +La deduplicazione impedisce che la stessa vulnerabilità compaia più volte quando viene rilevata ripetutamente dallo stesso scanner o da scanner diversi, consentendo alla cronologia di remediation di rimanere associata a un singolo Riscontro. + +Ulteriori informazioni sulla deduplicazione sono disponibili [qui](/triage_findings/finding_deduplication/about_deduplication/). + +### Reimportazione + +La funzione di Reimportazione di DefectDojo consente di aggiornare i Riscontri man mano che vengono importati nuovi risultati di scansione. Quando una scansione viene reimportata, DefectDojo confronta i risultati in arrivo con i Riscontri esistenti e aggiorna i record corrispondenti invece di crearne di completamente nuovi. Questo preserva un contesto prezioso, come le variazioni di stato, la cronologia di remediation, i commenti e le informazioni sulla proprietà, fornendo una registrazione continua del ciclo di vita di un Riscontro attraverso più cicli di test. + +Ulteriori informazioni sulla funzione di Reimportazione sono disponibili [qui](/import_data/import_intro/reimport/#main-content). + +### Accettazioni del rischio + +Le Accettazioni del rischio sono uno stato speciale che può essere applicato ai Riscontri per documentare formalmente e rendere operativa la decisione di riconoscerli senza porvi rimedio immediatamente. + +Ulteriori informazioni sulle Accettazioni del rischio sono disponibili [qui](/triage_findings/findings_workflows/os__risk_acceptance/). + +### Stati + +Ogni Riscontro creato in DefectDojo ha uno Stato che comunica informazioni rilevanti e aiuta il tuo team a monitorare i progressi nella risoluzione dei problemi. + +Ulteriori informazioni sugli Stati sono disponibili [qui](/triage_findings/findings_workflows/finding_status_definitions/). + +## Utilizzo dei Riscontri + +### Creazione di Riscontri + +Sebbene la maggior parte dei Riscontri venga generata automaticamente tramite importazioni di scansioni e integrazioni, DefectDojo supporta anche la creazione manuale dei Riscontri. I Riscontri manuali sono utili per tracciare vulnerabilità e problematiche di sicurezza identificate tramite penetration test, revisioni architetturali, valutazioni di conformità, programmi di bug bounty, incarichi di consulenza o altre attività che non producono un output da scanner. + +Per creare manualmente un Riscontro: +1. Vai al Test in cui desideri aggiungere manualmente il Riscontro, fai clic sul segno + e poi su **New Finding**. + +![image](images/osfindings_ss2.png) + +2. Si aprirà il modulo New Finding, che potrai compilare con qualsiasi informazione pertinente relativa al tuo Riscontro. + +3. Seleziona **Aggiungi un altro Riscontro** per aggiungere manualmente un altro Riscontro, oppure **Terminato** per concludere il processo di creazione manuale del Riscontro. + +Il Riscontro comparirà ora nell'elenco dei Riscontri contenuti nel Test originale. + +È importante notare che l'aggiunta manuale di un Riscontro dalla barra superiore creerà automaticamente un Engagement e un Test ad hoc per contenere il nuovo Riscontro, anziché aggiungerlo al Test attualmente visualizzato (vedi l'immagine sottostante). Questo perché la barra superiore fa riferimento all'Asset nel suo complesso. Se desideri aggiungere manualmente un Riscontro a un Test specifico e preesistente, è preferibile farlo dall'interno del Test stesso, come descritto nei passaggi 1-3 sopra. + +![image](images/osfindings_ss3.png) + +### Modifica dei Riscontri + +#### Menu kebab ⋮ + +Il menu kebab ⋮ accanto ai Riscontri contiene le seguenti funzioni: +- **Visualizza**: Apri e visualizza il Riscontro. +- **Modifica**: Modifica il Riscontro. +- **Copia**: Crea una copia del Riscontro. La copia può essere salvata in uno qualsiasi dei Test contenuti nell'Engagement corrispondente. +- **Richiedi Peer Review**: Avvia il processo di Peer Review e modifica lo stato del Riscontro in “In revisione”. Ulteriori informazioni sulle Peer Review sono disponibili [qui](/triage_findings/findings_workflows/finding_status_definitions/#under-review). +- **Touch Finding**: Registrerà l'interattività con il Riscontro nella sua cronologia. +- **Rendi il Riscontro un Modello**: Creerà automaticamente un Modello di Riscontro basato sul Riscontro selezionato. +- **Applica Modello al Riscontro**: Consentirà di applicare un Modello di Riscontro preesistente a un Riscontro. +- **Chiudi Riscontro**: Avvierà il processo di chiusura del Riscontro. +- **Aggiungi Accettazione del rischio**: Avvierà il processo di Accettazione del rischio. Ulteriori informazioni sono disponibili [qui](/triage_findings/findings_workflows/os__risk_acceptance/#main-content). +- **Visualizza cronologia**: Mostra la cronologia del Riscontro selezionato. +- **Elimina**: Elimina il Riscontro selezionato. + +#### Allegare file ai Riscontri +Puoi allegare file a qualsiasi Riscontro per fornire un contesto visivo — ad esempio, uno screenshot di una vulnerabilità in azione o un'immagine di proof-of-concept. + +I tipi di file supportati includono: + +``` +.txt .pdf .json .xml .csv .yml .png .jpeg +.sarif .xlsx .doc .html .js .nessus .zip .fpr +``` + +Per allegare un file a un Riscontro: +1. Apri il Riscontro a cui vuoi allegare un file. +2. Apri il menu delle azioni (il pulsante ☰ in alto a destra del Riscontro) e fai clic su Gestisci file. + +![image](images/OS_manage_files_menu.png) + +3. Nella pagina Aggiungi file, inserisci un Titolo per il file e scegli il file dal tuo computer. Puoi aggiungere fino a tre file alla volta; salva e torna indietro per aggiungerne altri se necessario. + +![image](images/OS_manage_files_form.png) + +4. Fai clic su **Salva**. + +Il file viene quindi elencato nel pannello **File** del Riscontro. I file immagine vengono visualizzati come miniature: + +![image](images/OS_finding_files_panel.png) + +#### Modifica in blocco dei Riscontri + +I Riscontri possono essere modificati in blocco da un elenco di Riscontri, come la tabella di Tutti i Riscontri accessibile dalla barra laterale, oppure dalla tabella dei Riscontri all'interno di uno specifico Test. + +Ulteriori informazioni su come modificare in blocco i Riscontri sono disponibili [qui](/triage_findings/findings_workflows/editing_findings/#bulk-edit-findings). + +### Chiusura dei Riscontri + +Una volta completato il lavoro su un Riscontro, puoi chiuderlo manualmente facendo clic su **Chiudi Riscontro** nel menu kebab ⋮ o nel menu delle azioni ☰ del Riscontro. In alternativa, se una scansione viene reimportata in DefectDojo senza contenere un Riscontro registrato in precedenza, quest'ultimo verrà chiuso automaticamente. + +Se non desideri che alcun Riscontro venga chiuso, puoi disabilitare questo comportamento durante la Reimportazione: + +- Deseleziona la casella Close Old Findings se utilizzi l'interfaccia utente +- Imposta close_old_findings su False se utilizzi l'API ​ + +### Eliminazione dei Riscontri + +L'eliminazione di un Riscontro può essere effettuata dal menu kebab ⋮ o dal menu delle azioni ☰ del Riscontro. Questa azione non può essere annullata. + +A fini di audit, si consiglia di chiudere i Riscontri risolti anziché eliminarli. + +## Gruppi di Riscontri + +I **Gruppi di Riscontri** ti consentono di trattare più Riscontri correlati come un'unica unità logica ai fini del triage, della reportistica e del coordinamento della remediation. + +Ad esempio, una scansione potrebbe generare 10 Riscontri di SQL injection su endpoint diversi. Invece di gestirli singolarmente, puoi raggrupparli in un unico Gruppo di Riscontri che rappresenta il problema più ampio di SQL injection. + +Un Gruppo di Riscontri non sostituisce i singoli Riscontri. Ogni Riscontro continua a esistere con la propria gravità, stato, metadati, commenti e cronologia di remediation. Un Gruppo di Riscontri fornisce semplicemente un ulteriore livello organizzativo al di sopra dei Riscontri che contiene. + +### Accesso ai Gruppi di Riscontri + +I Gruppi di Riscontri sono accessibili tramite la barra laterale. Il sottomenu fornisce l'accesso ai Gruppi di Riscontri aperti e chiusi, nonché a Tutti i Gruppi di Riscontri (indipendentemente dallo stato aperto). + +![image](images/osfindings_ss1.png) + +### Creazione di Gruppi di Riscontri + + +I Gruppi di Riscontri possono essere creati manualmente o automaticamente. + +È importante notare che i Gruppi di Riscontri possono essere creati solo a partire dai Riscontri contenuti in un singolo Test. I Riscontri provenienti da Test, Engagement o Prodotti diversi non possono essere aggiunti allo stesso Gruppo di Riscontri. + +#### Gruppi di Riscontri manuali + +Per eseguire manualmente le azioni sui Gruppi di Riscontri: +1. Vai a un elenco di Riscontri all'interno di un Test. +2. Seleziona il/i Riscontro/i che desideri aggiungere a un Gruppo di Riscontri facendo clic sulla casella corrispondente. +3. Fai clic sulla casella **Gruppo**. +4. Fai clic sull'azione corrispondente che desideri completare. + - **Crea**: Crea un Gruppo di Riscontri che include i Riscontri selezionati. + - **Aggiungi a**: Aggiunge i Riscontri selezionati a un Gruppo di Riscontri preesistente. + - **Rimuovi da qualsiasi gruppo**: Rimuove i Riscontri selezionati da qualsiasi Gruppo di Riscontri di cui facevano precedentemente parte. + - **Raggruppa per**: Raggruppa i Riscontri selezionati in base all'opzione scelta (ad es. Nome componente, Percorso file, Titolo del Riscontro, ecc.) +5. Fai clic su **Invia**. + +![image](images/osfindings_ss4.png) + +Nota che l'unica azione possibile quando si selezionano Riscontri dall'elenco Tutti i Riscontri è rimuoverli da qualsiasi Gruppo di Riscontri. Questo perché, come menzionato, i Gruppi di Riscontri possono essere creati solo a partire dai Riscontri contenuti in un singolo Test. + +#### Gruppi di Riscontri automatici + +Durante l'importazione di una scansione, la funzione “Raggruppa per” può creare automaticamente Gruppi di Riscontri in base a un metodo di raggruppamento scelto. Questo è utile quando uno scanner produce molti Riscontri correlati che dovrebbero essere gestiti insieme. + +La casella adiacente **Crea Gruppi di Riscontri per tutti i Riscontri** svolge due funzioni: +- **Selezionata**: Crea un Gruppo di Riscontri per ogni Riscontro importato, anche se tale Riscontro è l'unico membro del gruppo. +- **Deselezionata**: Crea Gruppi di Riscontri solo quando sono effettivamente presenti più Riscontri da raggruppare. + +![image](images/osfindings_ss5.png) + +Se durante l'importazione non viene selezionata alcuna opzione dal menu a discesa Raggruppa per, non verrà eseguito alcun raggruppamento. + +Se il criterio di raggruppamento (ad es. nome del componente, ID vulnerabilità, ecc.) non è popolato nel Riscontro, per quest'ultimo non verrà creato alcun gruppo né verrà aggiunto a un Gruppo di Riscontri preesistente. + +Se viene importata una scansione che rivela 10 Riscontri non raggruppati, e la stessa scansione viene successivamente reimportata con i Riscontri raggruppati, i primi 10 Riscontri non verranno aggiunti a quel Gruppo di Riscontri (ovvero, il Gruppo di Riscontri includerà solo i 10 Riscontri della reimportazione, non i 10 Riscontri dell'importazione iniziale e successiva). + +## Modelli di Riscontro + +I **Modelli di Riscontro** consentono agli Utenti di creare modelli riutilizzabili per le vulnerabilità e i problemi di sicurezza segnalati più comunemente. Un modello può includere informazioni standardizzate come titolo, descrizione, impatto, passaggi per la riproduzione, mitigazione, riferimenti e altri metadati del Riscontro. + +I Modelli di Riscontro sono particolarmente utili nelle situazioni in cui gli Utenti devono creare ripetutamente Riscontri manuali e vogliono evitare di reinserire ogni volta le stesse informazioni di supporto. + +### Accesso ai Modelli di Riscontro + +I Modelli di Riscontro si trovano nel sottomenu Riscontri della barra laterale. + +![image](images/osfindings_ss6.png) + +### Creazione di Modelli di Riscontro + +I Modelli di Riscontro possono essere creati facendo clic sul pulsante + in alto a destra nella vista dei Modelli di Riscontro. + +La pagina successiva fornisce una panoramica dei metadati che verranno applicati a un Riscontro quando viene utilizzato un Modello di Riscontro. + +Puoi anche utilizzare un Riscontro preesistente come base per un nuovo Modello di Riscontro facendo clic su **Rendi il Riscontro un Modello** nel menu kebab ⋮ del Riscontro. + +### Applicazione dei Modelli di Riscontro + +I Modelli di Riscontro possono essere applicati ai Riscontri facendo clic sul pulsante **Applica Modello al Riscontro** nel menu kebab ⋮ del Riscontro selezionato. + +![image](images/osfindings_ss7.png) + +La pagina successiva ti permetterà di selezionare il modello da applicare al Riscontro in questione, e quindi se mantenere, sostituire o combinare i metadati del Riscontro con quelli del modello. + +### Reportistica + +Il generatore di report di DefectDojo ti consente di assemblare un report personalizzato a partire da un insieme di widget di contenuto, eseguirlo ed esportare il risultato (ad esempio, stampandolo in PDF). I report personalizzati possono riassumere i Riscontri o gli Endpoint che desideri condividere con un pubblico esterno e possono includere branding e testo standard. + +Ulteriori informazioni sul Generatore di Report di DefectDojo sono disponibili [qui](/metrics_reports/reports/using-the-report-builder/). + +#### Esportazione dei Riscontri + +Le pagine che mostrano un elenco di Riscontri o un elenco di Engagement dispongono di un'opzione di esportazione in CSV ed Excel nel menu a discesa in alto a destra. + +Da qualsiasi pagina con un elenco di Riscontri, apri il menu a discesa nell'angolo in alto a destra per esportare i Riscontri visibili come file CSV o Excel. Anche l'elenco degli Engagement può essere esportato come CSV o Excel utilizzando lo stesso menu a discesa nella pagina dell'elenco Engagement. diff --git a/docs/content/asset_modelling/engagements_tests/OS__findings.pt-br.md b/docs/content/asset_modelling/engagements_tests/OS__findings.pt-br.md new file mode 100644 index 0000000000..2e41aae4dd --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__findings.pt-br.md @@ -0,0 +1,302 @@ +--- +title: Achados +description: Entendendo os Achados no DefectDojo OS +audience: opensource +weight: 5 +--- + +Organizações → Ativos → Engajamentos → Testes → **ACHADOS** + +## Visão geral + +**Achados** representam o nível mais baixo da Hierarquia de Produtos, onde vulnerabilidades individuais são rastreadas e gerenciadas, e são a principal forma pela qual o DefectDojo padroniza e orienta o processo de relato e remediação das suas ferramentas de segurança. Independentemente de uma vulnerabilidade ter sido relatada no SonarQube, no Acunetix ou na ferramenta personalizada da sua equipe, os Achados permitem gerenciar cada vulnerabilidade da mesma forma. + +Exemplos de Achados incluem: +- Cookie não marcado como HttpOnly +- Versão desatualizada (PHP) +- Avaliação de código fora de banda (PHP) +- Versão desatualizada (MySQL) +- Código-fonte de backup detectado +- Cross-Site Scripting cego + +Além de armazenar os dados da vulnerabilidade e fornecer uma estrutura de remediação, o DefectDojo também aprimora seus Achados das seguintes formas: +- Adicionando automaticamente as pontuações EPSS relacionadas a um Achado para descrever sua explorabilidade +- Traduzindo automaticamente a métrica de severidade de uma ferramenta de segurança em uma pontuação de Severidade para cada Achado, o que confere um SLA ao Achado de acordo com a configuração de SLA do seu Ativo. Para mais informações sobre a configuração de SLA, clique [aqui](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content). + +No geral, os Achados são projetados para funcionar em conjunto com a Hierarquia de Produtos, padronizando seus esforços e aplicando um método consistente a cada Ativo. + +## Acessando Achados + +Os Achados são acessíveis pela barra lateral. O submenu oferece acesso a Achados Abertos e Fechados, Todos os Achados (independentemente do status Aberto ou Fechado), [Achados com Risco Aceito](/triage_findings/findings_workflows/os__risk_acceptance/), além dos Templates de Achados. Achados individuais também são acessíveis a partir do Teste que os contém. + +![image](images/osfindings_ss1.png) + +### Permissões + +Todo Achado pertence a um Teste, o que permite que o DefectDojo preserve qual varredura ou avaliação identificou originalmente a vulnerabilidade. + +Como os Achados pertencem a Testes, o acesso aos Achados é determinado pelo acesso do Usuário ao Ativo que contém o Teste. Os Testes não possuem listas de controle de acesso independentes. + +## Visualização de Achados +As visualizações de Achado contêm uma variedade de tabelas para ajudar a interpretar o status de um Achado rapidamente. Isso inclui: +- **Visão geral** + - **ID**: O número de ID exclusivo desse Achado. + - **Severidade**: A classificação de severidade desse Achado, aplicada automaticamente. + - Como mencionado acima, o DefectDojo traduz automaticamente a métrica de severidade de uma ferramenta de segurança em uma pontuação de Severidade para cada Achado, o que confere um SLA ao Achado de acordo com a configuração de SLA do seu Ativo. + - **SLA**: A data limite prevista para a resolução do Achado. + - **Status**: O status do Achado (por exemplo, Ativo, Verificado, Falso positivo, Duplicado, Fora do escopo e Em revisão de defeito). + - **Tipo de Achado**: Se o Achado é Estático (SAST) ou Dinâmico (DAST). + - **Data de descoberta**: A data em que o Achado foi descoberto. + - **CWE**: A classificação CWE do Achado. + - **ID da vulnerabilidade**: IDs de vulnerabilidades em avisos de segurança associados ao Achado (por exemplo, CVE ou outras fontes). + - **Encontrado por**: A ferramenta que revelou o Achado. +- **Achados semelhantes**: Outros Achados dentro do mesmo Ativo que não são duplicatas exatas, mas possuem valores semelhantes para vulnerability ID, CWE, file_path, número de linha, etc. +- **Histórico de importação**: Lista de importações/reimportações que criaram/fecharam/reativaram esse Achado em qualquer Teste. +- **Endpoints/sistemas vulneráveis**: Endpoints/Sistemas que o Achado revela estarem vulneráveis. +- **Descrição**: A descrição do Achado (adicionada automaticamente dependendo do tipo de Achado, ou criada manualmente). +- **Mitigação**: Passos sugeridos para mitigação. +- **Impacto**: Impacto potencial de deixar o Achado sem resolução. +- **Passos para reproduzir**: Passos para reproduzir o Achado. +- **Justificativa de severidade**: Descrição escrita do motivo pelo qual uma determinada classificação de Severidade foi associada ao Achado. +- **Referências**: URL para referência cruzada com a descrição específica do Achado feita pela ferramenta de varredura de terceiros. Por exemplo, as Referências podem ser links para uma entrada relevante em um catálogo de Achados, ou uma única URL de aviso. +- **Notas**: Notas deixadas por Usuários relacionadas ao Achado. Marcar uma nota como privada significa que ela não será incluída em nenhum relatório gerado que inclua o Achado selecionado. + +## Dados dos Achados + +Os Achados exigem os seguintes metadados: +**Título** +**Data** +**Severidade** +**Descrição** + +Além dos metadados correspondentes às tabelas na visualização de um Achado, os campos de metadados opcionais incluem: +- **Grupo**: Grupos de Achados que incluem o Achado selecionado. +- **Vetor e pontuação CVSS3/CVSS4**: O vetor e a pontuação CVSS3 e CVSS4 do Achado selecionado. +- **Pares de solicitação e resposta**: Uma cópia da mensagem enviada pelo cliente e da resposta do servidor à solicitação. +- **Endpoints a adicionar**: Endpoints vulneráveis que podem ser afetados pelo Achado selecionado e que não estão refletidos na lista anterior de sistemas/endpoints. +- **Pontuação e percentil EPSS**: Pontuação e percentil EPSS para o CVE. +- **Data de adição ao KEV**: A data em que o Achado foi adicionado ao catálogo KEV. +- **Disponibilidade e versão da correção**: Define se há uma correção disponível para a vulnerabilidade, e a versão do componente afetado na qual a correção foi implementada. +- **Usuário que solicitou uma revisão de defeito**: Registra quem solicitou uma revisão de defeito para a falha em questão. +- **Número da linha**: Número da linha de origem do vetor de ataque. +- **Caminho do arquivo**: Arquivos identificados que contêm a falha. +- **Nome e versão do componente**: Nome e versão do componente afetado. +- **ID exclusivo da ferramenta**: ID técnico exclusivo da vulnerabilidade na ferramenta de origem. +- **ID de vulnerabilidade da ferramenta**: ID técnico não exclusivo na ferramenta de origem. +- **Objeto de origem SAST, número da linha e caminho do arquivo**: Objeto de origem, número da linha e caminho do arquivo do vetor de ataque. +- **Objeto de destino SAST**: Objeto de destino (sink) do vetor de ataque. +- **Número de ocorrências**: Número de ocorrências na ferramenta de origem quando várias vulnerabilidades foram encontradas e agregadas pelo scanner. +- **Data de publicação**: Data em que o Achado foi publicado. +- **Serviço**: Serviços conectados (partes autocontidas de funcionalidade dentro de um Ativo) que são afetados pelo Achado selecionado. Quando preenchido, esse campo é incluído na correspondência de deduplicação (ou seja, Achados com campos de Serviço idênticos serão deduplicados). +- **Data e versão de remediação planejada**: A data em que o Achado está planejado para ser remediado, e a versão do componente afetado na qual a correção será implementada. +- **Esforço para correção**: O nível de esforço envolvido na correção do Achado (por exemplo, Baixo, Médio ou Alto). +- **Tags**: Quaisquer tags que tenham sido adicionadas ao Achado. + +Os metadados exatos disponíveis dependerão do parser/scanner que revelou o Achado. Alguns fornecem apenas informações básicas, como título e severidade, enquanto outros incluem vetores CVSS, componentes vulneráveis, endpoints, pares de solicitação/resposta e outros metadados específicos do scanner. + +Esses metadados melhoram a filtragem, a geração de relatórios e a priorização em todo o seu programa de segurança, permitindo o rastreamento de longo prazo e a análise de tendências. Detalhes adicionais e descrições de metadados podem ser encontrados [aqui](/triage_findings/findings_workflows/intro_to_findings/#a-finding-page). + +### Deduplicação + +O DefectDojo inclui capacidades de deduplicação que ajudam a identificar e gerenciar Achados que representam a mesma vulnerabilidade subjacente. À medida que os resultados de varredura são importados de uma ou mais ferramentas, o DefectDojo usa uma lógica de correspondência configurável para identificar Achados que representam a mesma vulnerabilidade. + +A deduplicação evita que a mesma vulnerabilidade apareça várias vezes quando descoberta repetidamente pelo mesmo scanner ou por scanners diferentes, permitindo que o histórico de remediação permaneça vinculado a um único Achado. + +Mais informações sobre deduplicação podem ser encontradas [aqui](/triage_findings/finding_deduplication/about_deduplication/). + +### Reimportação + +A função de Reimportação do DefectDojo permite que os Achados sejam atualizados à medida que novos resultados de varredura são importados. Quando uma varredura é reimportada, o DefectDojo compara os resultados recebidos com os Achados existentes e atualiza os registros correspondentes em vez de criar registros totalmente novos. Isso preserva um contexto valioso, como alterações de status, histórico de remediação, comentários e informações de propriedade, fornecendo um registro contínuo do ciclo de vida de um Achado ao longo de vários ciclos de teste. + +Mais informações sobre a função de Reimportação podem ser encontradas [aqui](/import_data/import_intro/reimport/#main-content). + +### Aceitações de Risco + +As Aceitações de Risco são um status especial que pode ser aplicado aos Achados para documentar formalmente e operacionalizar a decisão de reconhecê-los sem remediá-los imediatamente. + +Mais informações sobre Aceitações de Risco podem ser encontradas [aqui](/triage_findings/findings_workflows/os__risk_acceptance/). + +### Status + +Cada Achado criado no DefectDojo tem um Status que comunica informações relevantes e ajuda sua equipe a acompanhar o progresso na resolução dos problemas. + +Mais informações sobre Status podem ser encontradas [aqui](/triage_findings/findings_workflows/finding_status_definitions/). + +## Trabalhando com Achados + +### Criando Achados + +Embora a maioria dos Achados seja gerada automaticamente por meio de importações de varreduras e integrações, o DefectDojo também oferece suporte à criação manual de Achados. Os Achados manuais são úteis para rastrear vulnerabilidades e questões de segurança identificadas por meio de testes de penetração, revisões de arquitetura, avaliações de conformidade, programas de bug bounty, engajamentos de consultoria ou outras atividades que não produzem saída de scanner. + +Para criar um Achado manualmente: +1. Navegue até o Teste no qual deseja adicionar manualmente o Achado, clique no sinal + (mais) e depois clique em **Novo Achado**. + +![image](images/osfindings_ss2.png) + +2. Isso abre o formulário de Novo Achado, que você pode preencher com qualquer informação relevante sobre seu Achado. + +3. Selecione **Adicionar Outro Achado** para adicionar manualmente outro Achado, ou **Concluído** para finalizar o processo de criação manual do Achado. + +O Achado agora aparecerá na lista de Achados contidos no Teste original. + +É importante notar que adicionar manualmente um Achado a partir da barra superior criará automaticamente um Engajamento e um Teste ad hoc para conter o novo Achado, em vez de adicioná-lo ao Teste que está sendo visualizado no momento (veja a imagem abaixo). Isso ocorre porque a barra superior diz respeito ao Ativo como um todo. Se você deseja adicionar manualmente um Achado a um Teste específico e já existente, é melhor fazer isso a partir do próprio Teste, conforme descrito nos passos 1 a 3 acima. + +![image](images/osfindings_ss3.png) + +### Editando Achados + +#### Menu Kebab ⋮ + +O menu kebab ⋮ ao lado dos Achados contém as seguintes funções: +- **Visualizar**: Abre e exibe o Achado. +- **Editar**: Edita o Achado. +- **Copiar**: Cria uma cópia do Achado. A cópia pode ser salva em qualquer um dos Testes contidos no Engajamento correspondente. +- **Solicitar Revisão por Pares**: Inicia o processo de Revisão por Pares e altera o status do Achado para "Em revisão". Mais informações sobre Revisões por Pares podem ser encontradas [aqui](/triage_findings/findings_workflows/finding_status_definitions/#under-review). +- **Registrar Interação com o Achado**: Registra a interatividade com o Achado no histórico do Achado. +- **Transformar Achado em Template**: Cria automaticamente um Template de Achado com base no Achado selecionado. +- **Aplicar Template ao Achado**: Permite aplicar um Template de Achado pré-existente a um Achado. +- **Fechar Achado**: Inicia o processo de fechamento do Achado. +- **Adicionar Aceitação de Risco**: Inicia o processo de Aceitação de Risco. Mais informações podem ser encontradas [aqui](/triage_findings/findings_workflows/os__risk_acceptance/#main-content). +- **Ver Histórico**: Revela o histórico do Achado selecionado. +- **Excluir**: Exclui o Achado selecionado. + +#### Anexando Arquivos aos Achados +Você pode anexar arquivos a qualquer Achado para fornecer contexto visual — por exemplo, uma captura de tela de uma vulnerabilidade em ação ou uma imagem de prova de conceito. + +Os tipos de arquivo compatíveis incluem: + +``` +.txt .pdf .json .xml .csv .yml .png .jpeg +.sarif .xlsx .doc .html .js .nessus .zip .fpr +``` + +Para anexar um arquivo a um Achado: +1. Abra o Achado ao qual deseja anexar um arquivo. +2. Abra o menu de ações (o botão ☰ no canto superior direito do Achado) e clique em Gerenciar Arquivos. + +![image](images/OS_manage_files_menu.png) + +3. Na página Adicionar arquivos, digite um Título para o arquivo e escolha o arquivo do seu computador. Você pode adicionar até três arquivos por vez; salve e retorne para adicionar mais, se necessário. + +![image](images/OS_manage_files_form.png) + +4. Clique em **Salvar**. + +O arquivo é então listado no painel **Arquivos** do Achado. Arquivos de imagem aparecem como miniaturas: + +![image](images/OS_finding_files_panel.png) + +#### Edição em Massa de Achados + +Os Achados podem ser editados em massa a partir de uma lista de Achados, como a tabela de Todos os Achados acessível pela barra lateral, ou a partir da tabela de Achados dentro de um Teste específico. + +Mais informações sobre como editar Achados em massa podem ser encontradas [aqui](/triage_findings/findings_workflows/editing_findings/#bulk-edit-findings). + +### Fechando Achados + +Depois que o trabalho em um Achado é concluído, você pode fechá-lo manualmente clicando em **Fechar Achado** dentro do menu kebab ⋮ ou do menu de ações ☰ do Achado. Alternativamente, se uma varredura for reimportada no DefectDojo e não contiver um Achado registrado anteriormente, o Achado registrado anteriormente será fechado automaticamente. + +Se você não quiser que nenhum Achado seja fechado, pode desabilitar esse comportamento na Reimportação: + +- Desmarque a caixa de seleção Close Old Findings, se estiver usando a UI +- Defina close_old_findings como False, se estiver usando a API ​ + +### Excluindo Achados + +A exclusão de um Achado pode ser feita a partir do menu kebab ⋮ ou do menu de ações ☰ do Achado. Essa ação não pode ser desfeita. + +Para fins de auditoria, recomenda-se fechar os Achados remediados, em vez de excluí-los. + +## Grupos de Achados + +Os **Grupos de Achados** permitem tratar múltiplos Achados relacionados como uma única unidade lógica para triagem, geração de relatórios e coordenação de remediação. + +Por exemplo, uma varredura pode produzir 10 Achados de injeção de SQL em diferentes endpoints. Em vez de gerenciar cada um independentemente, você pode agrupá-los em um único Grupo de Achados que represente o problema mais amplo de injeção de SQL. + +Um Grupo de Achados não substitui os Achados individuais. Cada Achado continua existindo com sua própria severidade, status, metadados, comentários e histórico de remediação. Um Grupo de Achados simplesmente fornece uma camada organizacional adicional acima dos Achados que ele contém. + +### Acessando Grupos de Achados + +Os Grupos de Achados podem ser acessados pela barra lateral. O submenu oferece acesso a Grupos de Achados Abertos e Fechados, bem como a Todos os Grupos de Achados (independentemente do status Aberto). + +![image](images/osfindings_ss1.png) + +### Criando Grupos de Achados + + +Os Grupos de Achados podem ser criados manual ou automaticamente. + +Notavelmente, os Grupos de Achados só podem ser criados a partir dos Achados contidos em um único Teste. Achados de Testes, Engajamentos ou Produtos diferentes não podem ser adicionados ao mesmo Grupo de Achados. + +#### Grupos de Achados Manuais + +Para realizar manualmente ações de Grupo de Achados: +1. Navegue até uma lista de Achados dentro de um Teste. +2. Selecione o(s) Achado(s) que deseja adicionar a um Grupo de Achados clicando na caixa de seleção correspondente. +3. Clique na caixa de seleção **Grupo**. +4. Clique na ação correspondente que deseja realizar. + - **Criar**: Cria um Grupo de Achados que inclui os Achados selecionados. + - **Adicionar a**: Adiciona os Achados selecionados a um Grupo de Achados pré-existente. + - **Remover de qualquer grupo**: Remove os Achados selecionados de quaisquer Grupos de Achados dos quais faziam parte anteriormente. + - **Agrupar por**: Agrupa os Achados selecionados com base na opção escolhida (por exemplo, nome do componente, caminho do arquivo, título do Achado, etc.) +5. Clique em **Enviar**. + +![image](images/osfindings_ss4.png) + +Observe que a única ação possível ao selecionar Achados na lista Todos os Achados é remover os Achados selecionados de qualquer Grupo de Achados. Isso ocorre porque, como mencionado, os Grupos de Achados só podem ser criados a partir dos Achados contidos em um único Teste. + +#### Grupos de Achados Automáticos + +Ao importar uma varredura, o recurso "Agrupar por" pode criar automaticamente Grupos de Achados com base em um método de agrupamento escolhido. Isso é útil quando um scanner produz muitos Achados relacionados que devem ser gerenciados em conjunto. + +A caixa de seleção adjacente **Criar Grupos de Achados para todos os Achados** realiza duas funções: +- **Marcada**: Cria um Grupo de Achados para cada Achado importado, mesmo que esse Achado seja o único membro do grupo. +- **Desmarcada**: Cria Grupos de Achados somente quando há de fato múltiplos Achados para agrupar. + +![image](images/osfindings_ss5.png) + +Se nenhuma opção for selecionada no menu suspenso Agrupar por durante a importação, nenhum agrupamento ocorrerá. + +Se o critério de agrupamento (por exemplo, nome do componente, ID de vulnerabilidade, etc.) não estiver preenchido no Achado, ele não terá um grupo criado nem será adicionado a um Grupo de Achados pré-existente. + +Se uma varredura for importada revelando 10 Achados que não são agrupados, e a mesma varredura for reimportada e os Achados forem agrupados, os primeiros 10 Achados não serão adicionados a esse Grupo de Achados (ou seja, o Grupo de Achados incluirá apenas os 10 Achados da reimportação, não os 10 Achados da importação inicial e subsequente). + +## Templates de Achados + +**Templates de Achados** permitem que os Usuários criem templates reutilizáveis para vulnerabilidades e problemas de segurança comumente relatados. Um template pode incluir informações padronizadas, como título, descrição, impacto, passos para reproduzir, mitigação, referências e outros metadados de Achado. + +Os Templates de Achados são mais úteis em situações em que os Usuários precisam criar Achados manuais repetidamente e desejam evitar reinserir as mesmas informações de apoio todas as vezes. + +### Acessando Templates de Achados + +Os Templates de Achados são encontrados no submenu de Achados na barra lateral. + +![image](images/osfindings_ss6.png) + +### Criando Templates de Achados + +Os Templates de Achados podem ser criados clicando no botão + (mais) no canto superior direito da visualização de Templates de Achados. + +A página seguinte fornece uma visão geral dos metadados que serão aplicados a um Achado quando um Template de Achado for usado. + +Você também pode usar um Achado pré-existente como base para um novo Template de Achado clicando em **Transformar Achado em Template** dentro do menu kebab ⋮ do Achado. + +### Aplicando Templates de Achados + +Os Templates de Achados podem ser aplicados a Achados clicando no botão **Aplicar Template ao Achado** dentro do menu kebab ⋮ do Achado selecionado. + +![image](images/osfindings_ss7.png) + +A página seguinte permitirá que você selecione o template a ser aplicado ao Achado em questão, e então decida se deseja manter, substituir ou combinar os metadados do Achado com o template. + +### Relatórios + +O construtor de relatórios do DefectDojo permite montar um relatório personalizado a partir de um conjunto de widgets de conteúdo, executá-lo e exportar o resultado (por exemplo, imprimindo-o em PDF). Relatórios personalizados podem resumir os Achados ou Endpoints que você deseja compartilhar com um público externo, e podem incluir branding e texto padrão. + +Mais informações sobre o Construtor de Relatórios do DefectDojo podem ser encontradas [aqui](/metrics_reports/reports/using-the-report-builder/). + +#### Exportar Achados + +Páginas que exibem uma lista de Achados ou uma lista de Engajamentos têm uma opção de exportação em CSV e Excel no menu suspenso no canto superior direito. + +Em qualquer página de lista de Achados, abra o menu suspenso no canto superior direito para exportar os Achados visíveis como um arquivo CSV ou Excel. A lista de Engajamentos também pode ser exportada como CSV ou Excel usando o mesmo menu suspenso na página de lista de Engajamentos. diff --git a/docs/content/asset_modelling/engagements_tests/OS__findings.zh-hans.md b/docs/content/asset_modelling/engagements_tests/OS__findings.zh-hans.md new file mode 100644 index 0000000000..49aeacec0a --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__findings.zh-hans.md @@ -0,0 +1,302 @@ +--- +title: 发现项 +description: 了解 DefectDojo OS 中的发现项 +audience: opensource +weight: 5 +--- + +组织 → 资产 → 测试活动 → 测试 → **发现项** + +## 概述 + +**发现项** 代表产品层级结构中的最低层级,单个漏洞在此处被跟踪和管理,也是 DefectDojo 用于标准化和指导各类安全工具报告与修复流程的主要方式。无论漏洞是由 SonarQube、Acunetix 报告,还是由您团队的自定义工具报告,发现项都能让您以相同的方式管理每一个漏洞。 + +发现项的示例包括: +- Cookie 未标记为 HttpOnly +- 版本过时(PHP) +- 带外代码执行(PHP) +- 版本过时(MySQL) +- 检测到备份源代码 +- 盲跨站脚本攻击 + +除了存储漏洞数据和提供修复框架之外,DefectDojo 还通过以下方式增强您的发现项: +- 自动为发现项添加相关的 EPSS 分数,以描述其可利用性 +- 自动将安全工具的严重程度指标转换为每个发现项的严重程度评分,并根据您资产的 SLA 配置为该发现项赋予相应的 SLA。有关 SLA 配置的更多信息,请点击[此处](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content)。 + +总体而言,发现项旨在与产品层级结构协同工作,以规范您的工作,并为每个资产应用一致的方法。 + +## 访问发现项 + +发现项可通过侧边栏访问。子菜单提供了对打开的发现项和已关闭的发现项、所有发现项(无论打开或关闭状态)、[风险已接受的发现项](/triage_findings/findings_workflows/os__risk_acceptance/)以及发现项模板的访问入口。单个发现项也可以从包含它的测试内部访问。 + +![image](images/osfindings_ss1.png) + +### 权限 + +每个发现项都属于某个测试,这使 DefectDojo 能够保留最初发现该漏洞的扫描或评估记录。 + +由于发现项属于测试,对发现项的访问权限取决于用户对包含该测试的资产的访问权限。测试没有独立的访问控制列表。 + +## 发现项视图 +发现项视图包含多种表格,可帮助您一目了然地了解发现项的状态。这些表格包括: +- **概览** + - **ID**:该发现项的唯一 ID 编号。 + - **严重程度**:该发现项的严重程度评级,系统会自动应用。 + - 如上所述,DefectDojo 会自动将安全工具的严重程度指标转换为每个发现项的严重程度评分,并根据您资产的 SLA 配置为该发现项赋予相应的 SLA。 + - **SLA**:该发现项预计应解决的到期日期。 + - **状态**:该发现项的状态(例如活动、已验证、误报、重复、超出范围以及正在进行缺陷审查)。 + - **发现项类型**:该发现项是静态(SAST)还是动态(DAST)。 + - **发现日期**:该发现项被发现的日期。 + - **CWE**:该发现项的 CWE 分类。 + - **漏洞 ID**:与该发现项相关联的安全公告中的漏洞 ID(例如 CVE 或其他来源)。 + - **发现工具**:揭示该发现项的工具。 +- **相似发现项**:同一资产内其他并非完全重复、但在漏洞 ID、CWE、file_path、行号等方面具有相似值的发现项。 +- **导入历史**:在任何测试中创建/关闭/重新激活该发现项的导入/重新导入记录列表。 +- **易受攻击的端点/系统**:该发现项所揭示的存在漏洞的端点/系统。 +- **描述**:该发现项的描述(根据发现项类型自动添加,或手动创建)。 +- **缓解措施**:建议的缓解步骤。 +- **影响**:未解决该发现项可能造成的潜在影响。 +- **重现步骤**:重现该发现项的步骤。 +- **严重程度说明**:关于为何将某一严重程度评级关联到该发现项的文字说明。 +- **参考资料**:用于交叉引用第三方扫描工具对该发现项具体描述的 URL。例如,参考资料可以是指向发现项目录中相关条目的链接,或单个公告 URL。 +- **备注**:用户就该发现项留下的备注。将某条备注标记为私密后,该备注将不会包含在任何包含所选发现项的已生成报告中。 + +## 发现项数据 + +发现项需要以下元数据: +**标题** +**日期** +**严重程度** +**描述** + +除了与发现项视图中的表格相对应的元数据外,可选的元数据字段还包括: +- **组**:包含所选发现项的发现项组。 +- **CVSS3/CVSS4 向量和评分**:所选发现项的 CVSS3 和 CVSS4 向量及评分。 +- **请求和响应对**:客户端发送的消息及服务器对该请求回复的副本。 +- **待添加的端点**:可能受所选发现项影响、但尚未反映在前述系统/端点列表中的易受攻击端点。 +- **EPSS 分数和百分位**:该 CVE 的 EPSS 分数和百分位。 +- **KEV 添加日期**:该发现项被添加到 KEV 目录的日期。 +- **修复可用性和版本**:定义该漏洞是否有可用的修复方案,以及实施该修复的受影响组件版本。 +- **发起缺陷审查的用户**:记录是谁针对该缺陷发起了缺陷审查请求。 +- **行号**:攻击向量的源代码行号。 +- **文件路径**:包含该缺陷的已识别文件。 +- **组件名称和版本**:受影响组件的名称和版本。 +- **来自工具的唯一 ID**:源工具提供的漏洞技术 ID。 +- **来自工具的漏洞 ID**:源工具提供的非唯一技术 ID。 +- **SAST 源对象、行号和文件路径**:攻击向量的源对象、行号和文件路径。 +- **SAST 汇聚对象**:攻击向量的汇聚对象。 +- **出现次数**:当扫描器发现并聚合多个漏洞时,源工具中记录的出现次数。 +- **发布日期**:该发现项的发布日期。 +- **服务**:受所选发现项影响的关联服务(资产内自成一体的功能单元)。填写该字段后,它将被纳入去重匹配(即,服务字段相同的发现项将会被去重)。 +- **计划修复日期和版本**:计划修复该发现项的日期,以及实施修复的受影响组件版本。 +- **修复工作量**:修复该发现项所需的工作量级别(例如低、中或高)。 +- **标签**:已添加到该发现项的任何标签。 + +具体可用的元数据取决于揭示该发现项的解析器/扫描器。有些扫描器仅提供标题和严重程度等基本信息,而另一些则包括 CVSS 向量、易受攻击的组件、端点、请求/响应对以及其他特定于该扫描器的元数据。 + +这些元数据可改善您整个安全项目中的筛选、报告和优先级排序,从而实现长期跟踪和趋势分析。有关更多详情和元数据说明,请参见[此处](/triage_findings/findings_workflows/intro_to_findings/#a-finding-page)。 + +### 去重 + +DefectDojo 具备去重功能,可帮助识别和管理代表同一底层漏洞的发现项。当从一个或多个工具导入扫描结果时,DefectDojo 会使用可配置的匹配逻辑来识别代表同一漏洞的发现项。 + +去重功能可防止同一漏洞在被相同或不同的扫描器反复发现时多次出现,从而使修复历史能够持续关联到单个发现项。 + +有关去重的更多信息,请参见[此处](/triage_findings/finding_deduplication/about_deduplication/)。 + +### 重新导入 + +DefectDojo 的重新导入功能允许在导入新的扫描结果时更新发现项。重新导入扫描时,DefectDojo 会将新导入的结果与现有发现项进行比对,并更新匹配的记录,而不是创建全新的记录。这样可以保留诸如状态变更、修复历史、评论和所属信息等有价值的上下文,从而在多个测试周期中持续记录发现项的生命周期。 + +有关重新导入功能的更多信息,请参见[此处](/import_data/import_intro/reimport/#main-content)。 + +### 风险接受 + +风险接受是一种可应用于发现项的特殊状态,用于正式记录并落实“确认发现项但不立即修复”这一决定。 + +有关风险接受的更多信息,请参见[此处](/triage_findings/findings_workflows/os__risk_acceptance/)。 + +### 状态 + +在 DefectDojo 中创建的每个发现项都有一个状态,用于传达相关信息,并帮助您的团队跟踪问题解决的进度。 + +有关状态的更多信息,请参见[此处](/triage_findings/findings_workflows/finding_status_definitions/)。 + +## 使用发现项 + +### 创建发现项 + +虽然大多数发现项都是通过扫描导入和集成自动生成的,但 DefectDojo 也支持手动创建发现项。手动发现项适用于跟踪通过渗透测试、架构审查、合规评估、漏洞赏金计划、顾问项目或其他不产生扫描器输出的活动所识别出的漏洞和安全问题。 + +要手动创建发现项: +1. 导航到您希望手动添加发现项的测试,点击 + 加号,然后点击 **新建发现项**。 + +![image](images/osfindings_ss2.png) + +2. 这将打开“新建发现项”表单,您可以在其中填写与发现项相关的任何信息。 + +3. 选择 **添加另一个发现项** 以手动添加另一个发现项,或选择 **完成** 以结束手动创建发现项的流程。 + +该发现项现在将出现在原始测试所包含的发现项列表中。 + +需要注意的是,通过顶部栏手动添加发现项,将自动创建一个临时测试活动和测试来容纳该新发现项,而不会将其添加到当前正在查看的测试中(见下图)。这是因为顶部栏针对的是整个资产。如果您希望手动将发现项添加到某个特定的、已存在的测试中,最好按照上述步骤 1-3 所述,在该测试内部进行操作。 + +![image](images/osfindings_ss3.png) + +### 编辑发现项 + +#### ⋮ 三点菜单 + +发现项旁边的 ⋮ 三点菜单包含以下功能: +- **查看**:打开并查看该发现项。 +- **编辑**:编辑该发现项。 +- **复制**:创建该发现项的副本。该副本可以保存到相应测试活动内的任意测试中。 +- **请求同行评审**:启动同行评审流程,并将发现项的状态更改为“审查中”。有关同行评审的更多信息,请参见[此处](/triage_findings/findings_workflows/finding_status_definitions/#under-review)。 +- **触碰发现项**:将在发现项的历史记录中记录与该发现项的交互。 +- **将发现项设为模板**:将根据所选发现项自动创建一个发现项模板。 +- **将模板应用于发现项**:允许将已有的发现项模板应用到某个发现项。 +- **关闭发现项**:将启动关闭该发现项的流程。 +- **添加风险接受**:将启动风险接受流程。更多信息请参见[此处](/triage_findings/findings_workflows/os__risk_acceptance/#main-content)。 +- **查看历史记录**:显示所选发现项的历史记录。 +- **删除**:删除所选发现项。 + +#### 为发现项附加文件 +您可以为任何发现项附加文件,以提供直观的背景信息 — 例如漏洞实际发生的截图,或概念验证图片。 + +支持的文件类型包括: + +``` +.txt .pdf .json .xml .csv .yml .png .jpeg +.sarif .xlsx .doc .html .js .nessus .zip .fpr +``` + +要为发现项附加文件: +1. 打开您想要附加文件的发现项。 +2. 打开操作菜单(发现项右上角的 ☰ 按钮),然后点击“管理文件”。 + +![image](images/OS_manage_files_menu.png) + +3. 在“添加文件”页面上,为文件输入标题,并从计算机中选择文件。您一次最多可以添加三个文件;如有需要,可保存后返回继续添加。 + +![image](images/OS_manage_files_form.png) + +4. 点击 **保存**。 + +该文件随后将列示在发现项的 **文件** 面板中。图片文件将显示为缩略图: + +![image](images/OS_finding_files_panel.png) + +#### 批量编辑发现项 + +发现项可以从发现项列表中批量编辑,例如通过侧边栏访问的“所有发现项”表格,或特定测试内的发现项表格。 + +有关如何批量编辑发现项的更多信息,请参见[此处](/triage_findings/findings_workflows/editing_findings/#bulk-edit-findings)。 + +### 关闭发现项 + +一旦某个发现项的处理工作完成,您可以在该发现项的 ⋮ 三点菜单或 ☰ 操作菜单中点击 **关闭发现项** 来手动关闭它。此外,如果重新导入 DefectDojo 的扫描结果中不包含此前记录的某个发现项,该发现项将自动关闭。 + +如果您不希望任何发现项被关闭,可以在重新导入时禁用此行为: + +- 如果使用界面,请取消勾选“关闭旧发现项”复选框 +- 如果使用 API,请将 close_old_findings 设置为 False ​ + +### 删除发现项 + +可以从发现项的 ⋮ 三点菜单或 ☰ 操作菜单中删除该发现项。此操作无法撤销。 + +出于审计目的,建议关闭已修复的发现项,而不是将其删除。 + +## 发现项组 + +**发现项组** 使您能够将多个相关发现项视为单一逻辑单元,以便进行分类处理、报告和修复协调。 + +例如,一次扫描可能会在不同端点上产生 10 个 SQL 注入发现项。您无需单独管理每一个,而是可以将它们归入一个代表整体 SQL 注入问题的发现项组。 + +发现项组并不会取代各个独立的发现项。每个发现项依然拥有各自的严重程度、状态、元数据、评论和修复历史。发现项组只是在其所包含的发现项之上,提供了一个额外的组织层级。 + +### 访问发现项组 + +发现项组可通过侧边栏访问。子菜单提供了对打开和已关闭的发现项组,以及所有发现项组(无论是否处于打开状态)的访问入口。 + +![image](images/osfindings_ss1.png) + +### 创建发现项组 + + +发现项组既可以手动创建,也可以自动创建。 + +需要注意的是,发现项组只能由单个测试内所包含的发现项创建。来自不同测试、测试活动或产品的发现项无法添加到同一个发现项组中。 + +#### 手动发现项组 + +要手动执行发现项组操作: +1. 导航到某个测试内的发现项列表。 +2. 点击相应的复选框,选择您希望添加到发现项组的发现项。 +3. 点击 **组** 复选框。 +4. 点击您希望执行的相应操作。 + - **创建**:创建一个包含所选发现项的发现项组。 + - **添加至**:将所选发现项添加到已有的发现项组中。 + - **从所有组中移除**:将所选发现项从其此前所属的任何发现项组中移除。 + - **分组依据**:根据所选选项(例如组件名称、文件路径、发现项标题等)对所选发现项进行分组 +5. 点击 **提交**。 + +![image](images/osfindings_ss4.png) + +请注意,在“所有发现项”列表中选择发现项时,唯一可执行的操作是将所选发现项从任何发现项组中移除。这是因为,如前所述,发现项组只能由单个测试内所包含的发现项创建。 + +#### 自动发现项组 + +在导入扫描结果时,“分组依据”功能可以根据所选的分组方式自动创建发现项组。当某个扫描器生成大量应统一管理的相关发现项时,该功能非常实用。 + +与之相邻的 **为所有发现项创建发现项组** 复选框具有两项功能: +- **勾选**:为每个导入的发现项创建一个发现项组,即使该发现项是该组中唯一的成员。 +- **取消勾选**:仅当确实存在多个需要归为一组的发现项时,才创建发现项组。 + +![image](images/osfindings_ss5.png) + +如果在导入过程中未从“分组依据”下拉菜单中选择任何选项,则不会进行分组。 + +如果发现项中未填写分组条件(例如组件名称、漏洞 ID 等),则不会为其创建分组,也不会将其添加到已有的发现项组中。 + +如果导入的一次扫描揭示了 10 个未分组的发现项,而后重新导入同一扫描并对发现项进行了分组,则最初的这 10 个发现项不会被添加到该发现项组中(即,该发现项组将仅包含重新导入时产生的 10 个发现项,而不包括最初及后续导入产生的 10 个发现项)。 + +## 发现项模板 + +**发现项模板** 允许用户为常见的、经常被报告的漏洞和安全问题创建可复用的模板。模板可以包含标准化的信息,例如标题、描述、影响、重现步骤、缓解措施、参考资料以及其他发现项元数据。 + +发现项模板在用户需要反复手动创建发现项、并希望避免每次都重新录入相同的支持信息时最为实用。 + +### 访问发现项模板 + +发现项模板位于侧边栏的“发现项”子菜单中。 + +![image](images/osfindings_ss6.png) + +### 创建发现项模板 + +在“发现项模板”视图右上角点击 + 加号按钮即可创建发现项模板。 + +随后打开的页面提供了在使用某个发现项模板时,将应用于发现项的元数据概览。 + +您也可以在发现项的 ⋮ 三点菜单中点击 **将发现项设为模板**,以某个已有发现项为基础创建新的发现项模板。 + +### 应用发现项模板 + +在所选发现项的 ⋮ 三点菜单中点击 **将模板应用于发现项** 按钮,即可将发现项模板应用到该发现项。 + +![image](images/osfindings_ss7.png) + +随后打开的页面将允许您选择要应用于该发现项的模板,并选择是保留、替换,还是将发现项的元数据与模板的元数据进行合并。 + +### 报告 + +DefectDojo 的报告构建器允许您通过一组内容小部件组装自定义报告、运行该报告,并导出结果(例如将其打印为 PDF)。自定义报告可以汇总您希望与外部受众分享的发现项或端点,并可以包含品牌信息和样板文字。 + +有关 DefectDojo 报告构建器的更多信息,请参见[此处](/metrics_reports/reports/using-the-report-builder/)。 + +#### 导出发现项 + +显示发现项列表或测试活动列表的页面,在右上角的下拉菜单中提供 CSV 和 Excel 导出选项。 + +在任意发现项列表页面中,打开右上角的下拉菜单,即可将可见的发现项导出为 CSV 或 Excel 文件。在测试活动列表页面上使用同样的下拉菜单,也可以将测试活动列表导出为 CSV 或 Excel 文件。 diff --git a/docs/content/asset_modelling/engagements_tests/OS__organizations.it.md b/docs/content/asset_modelling/engagements_tests/OS__organizations.it.md new file mode 100644 index 0000000000..7701f1abf2 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__organizations.it.md @@ -0,0 +1,139 @@ +--- +title: Organizzazioni +description: Comprendere le Organizzazioni in DefectDojo OS +audience: opensource +weight: 1 +aliases: +- /it/asset_modelling/engagements_tests/os_producttype/ +- /it/en/asset_modelling/engagements_tests/os_producttype/ +--- + +**ORGANIZZAZIONI** → Asset → Engagement → Test → Riscontri + +## Panoramica + +Le **Organizzazioni** si trovano al vertice della gerarchia degli oggetti di DefectDojo. Le Organizzazioni si distinguono dagli oggetti discendenti della gerarchia—Asset, Engagement, Test e Riscontri—perché non sono obiettivi tecnici di scansione, ma servono principalmente come astrazioni organizzative che suddividono i vostri sforzi di sicurezza in base a: +- Ambito aziendale +- Team di sviluppo +- Team di sicurezza +- Applicazioni software +- Famiglia di prodotto generale +- Cliente o filiale +- Struttura di reporting +- ecc. + +Il filo conduttore degli esempi precedenti illustra l'utilità essenziale delle Organizzazioni: in genere dovrebbero rappresentare confini stabili e di lunga durata all'interno del vostro programma di sicurezza. + +## Dati e struttura dell'Organizzazione + +Poiché le Organizzazioni non vengono scansionate direttamente, l'unico campo obbligatorio per crearle è il nome. Al di là di questo, fungono da contenitori per gli Asset e per gli Engagement, i Test e i Riscontri che ne discendono. + +Quando create un'Organizzazione, considerate come la sua struttura influenzerà il vostro reporting. Avete principalmente bisogno che le Organizzazioni rappresentino i team che lavorano sui progetti (Asset) che le Organizzazioni conterranno? Oppure le Organizzazioni rappresenterebbero meglio progetti generali che contengono al loro interno diverse iterazioni dei progetti (Asset)? + +Se avete un'unica Organizzazione che contiene tutte le informazioni rilevanti per un dato ambito aziendale o team di sviluppo, rappresentarla come un'Organizzazione faciliterà un reporting più fluido, invece di dover assemblare un report a partire da vari Asset e Organizzazioni. + +Se un particolare progetto software presenta molte distribuzioni o versioni distinte, può valere la pena creare un'unica Organizzazione che copra l'ambito dell'intero progetto e far sì che ogni versione esista come Asset individuali. In alcuni flussi di lavoro, le Organizzazioni possono anche essere usate per separare le fasi del ciclo di vita del software: un'Organizzazione per “In sviluppo”, un'Organizzazione per “In produzione”, ecc. + +Le Organizzazioni possono essere usate per determinare l'accesso a filiali, società acquisite o altre unità aziendali regolamentate ai fini RBAC. Nelle aziende complesse, dove esistono molti progetti unici con regole di accesso diverse, le Organizzazioni sono particolarmente rilevanti. + +In definitiva, la decisione su come usare Organizzazioni e Asset dipende da come preferite riflettere la vostra struttura organizzativa unica e le esigenze del vostro team di sicurezza. + +Di seguito alcuni esempi di struttura per orientarvi su come designare i vostri oggetti come Organizzazioni o Asset. + +- **Organizzazione**: Divisione Pagamenti + - Asset: Payments API - Produzione + - Asset: Payments API - Staging + - Asset: Billing Worker + +- **Organizzazione**: Prodotto Software A + - Asset: Portale Web + - Asset: Backend Mobile + +Inoltre, la seguente è una guida illustrativa per capire se qualcosa è meglio rappresentato da un'Organizzazione o da un Asset: + +| Organizzazioni | Asset | +|--------------|--------| +| Unità aziendali | Applicazioni individuali | +| Dipartimenti | Distribuzioni/ambienti | +| Domini di responsabilità della sicurezza | Componenti infrastrutturali | +| Famiglie di prodotto | Microservizi specifici | +| Reporting a livello di portafoglio | Obiettivi di scansione | +| Clienti | Versioni software specifiche | + +Come indicato, la vostra struttura potrebbe differire a seconda delle vostre esigenze di sicurezza specifiche. + +## Accesso alle Organizzazioni + +Le Organizzazioni sono accessibili tramite la barra laterale. Il sottomenu offre anche l'opzione per creare nuove Organizzazioni. + +![image](images/organization_ss1.png) + +### Vista Organizzazione + +La vista di un'Organizzazione contiene diverse tabelle e grafici per interpretarne lo stato a colpo d'occhio. Questi includono: +- **Descrizione** +- **Casella Key/Critical** + - Selezionare Critical o Key serve esclusivamente a scopi di filtraggio +- **Elenco degli Asset all'interno dell'Organizzazione** +- **Utenti autorizzati** (Utenti DefectDojo) + +## Lavorare con le Organizzazioni + +### Creare Organizzazioni + +Esistono due modi per creare Organizzazioni: + +- Dall'opzione **Add Organization** nel menu laterale +- Dal pulsante **Add Organization** in cima all'elenco All Organizations + +### Modificare le Organizzazioni + +Le Organizzazioni possono essere modificate facendo clic su **Edit** dal menu a discesa in alto a destra della tabella Description nella vista dell'Organizzazione. Lo stesso menu è accessibile anche facendo clic sul menu kebab ⋮ a sinistra dell'Organizzazione nell'elenco All Organizations. + +Tutti i campi modificabili di seguito sono disponibili anche durante la creazione dell'Organizzazione. + +### Eliminare le Organizzazioni + +È possibile eliminare un'Organizzazione selezionando **Delete Organization** dalle impostazioni dell'Organizzazione. + +Poiché le Organizzazioni si trovano al vertice della gerarchia, la loro eliminazione rimuove tutta la cronologia di sicurezza, le relazioni e gli oggetti figli a valle, tra cui: +- Qualsiasi Asset, Engagement e Test contenuto nell'Organizzazione +- Tutta la cronologia di sicurezza associata, inclusi Riscontri e integrazioni +- Eventuali Epic Jira collegate +- Tutte le note e i file caricati associati agli Asset, agli Engagement e ai Test all'interno di quell'Organizzazione + +L'eliminazione di un'Organizzazione non può essere annullata. Se desiderate “dismettere” un'Organizzazione senza eliminare i dati sottostanti (ad esempio, per conservare i registri di test software legacy a fini di audit), potete cambiare il nome dell'Organizzazione o aggiungere un Tag per indicare che si trova in uno stato deprecato. + +## Organizzazioni vs. Metadati + +Le Organizzazioni hanno lo scopo di rappresentare la responsabilità strutturale o i confini di reporting, non classificazioni leggere. Attributi come lo stato di distribuzione, le etichette interne o gli stati di workflow temporanei potrebbero essere meglio rappresentati tramite tag o metadati piuttosto che da Organizzazioni separate. + +## Confini delle Organizzazioni + +Le Organizzazioni stabiliscono sia i confini di reporting sia quelli di accesso all'interno di DefectDojo. Poiché integrazioni, permessi RBAC, proprietà, metriche e modelli di deduplicazione ereditano spesso la struttura delle Organizzazioni, progettare confini chiari fin dall'inizio aiuta a evitare una proliferazione della gerarchia e una frammentazione del reporting in seguito. + +### Riscontri e automazione + +Sebbene le integrazioni siano tipicamente configurate su oggetti di livello inferiore come Asset, Engagement o Riscontri, le Organizzazioni definiscono comunque i confini di proprietà, reporting e accesso entro cui tali integrazioni operano. + +I permessi si propagano verso il basso, il che significa che l'accesso a un'Organizzazione concede automaticamente l'accesso a tutti gli oggetti al suo interno (ad es. Asset, Engagement, Test e Riscontri). + +Il modello RBAC di DefectDojo può essere usato per limitare l'accesso degli utenti umani, ma può anche limitare l'accesso dei token API a particolari Organizzazioni. + +Per maggiori informazioni sui ruoli utente, consultate il nostro articolo [Permessi](/admin/user_management/os__authorized_users/). + +### Proprietà + +In quanto oggetti di primo livello, le Organizzazioni implicano anche la proprietà sugli oggetti figli al loro interno. Il monitoraggio degli SLA, i workflow di remediation, l'instradamento dei ticket e la governance generale funzionano in modo più fluido quando le Organizzazioni sono state configurate per riflettere accuratamente le persone responsabili di esse. + +### Metriche/Reporting + +Le dashboard delle metriche, i riquadri e le viste possono essere filtrati per Organizzazione, il che le rende una componente critica del modo in cui i vostri dati di sicurezza vengono calcolati, visualizzati e infine esportati. + +Ai fini del reporting, in genere è più semplice combinare più Organizzazioni in un unico documento che suddividere una singola Organizzazione in documenti separati. Pertanto, consigliamo di impostare le Organizzazioni al livello di granularità più adatto ai report del vostro team. Ad esempio, non è necessario rappresentare una grande divisione aziendale come un'Organizzazione se farete principalmente report verso i singoli dipartimenti al suo interno. + +Strutturare efficacemente le vostre Organizzazioni in modo da riflettere le vostre esigenze di reporting è fondamentale per valutare accuratamente la vostra postura di sicurezza. Per maggiori informazioni sulle Metriche, fate clic [qui](/metrics_reports/dashboards/introduction_dashboard/). + +### Deduplicazione + +La deduplicazione in DefectDojo avviene a livello di Asset e non è influenzata dall'Organizzazione principale. diff --git a/docs/content/asset_modelling/engagements_tests/OS__organizations.pt-br.md b/docs/content/asset_modelling/engagements_tests/OS__organizations.pt-br.md new file mode 100644 index 0000000000..2d1002c648 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__organizations.pt-br.md @@ -0,0 +1,139 @@ +--- +title: Organizações +description: Entendendo as Organizações no DefectDojo OS +audience: opensource +weight: 1 +aliases: +- /pt-br/asset_modelling/engagements_tests/os_producttype/ +- /pt-br/en/asset_modelling/engagements_tests/os_producttype/ +--- + +**ORGANIZAÇÕES** → Ativos → Engajamentos → Testes → Achados + +## Visão geral + +**Organizações** ficam bem no topo da hierarquia de objetos do DefectDojo. As Organizações são diferentes dos objetos descendentes na hierarquia — Ativos, Engajamentos, Testes e Achados — porque não são alvos técnicos de varredura, mas servem principalmente como abstrações organizacionais que compartimentam seus esforços de segurança de acordo com: +- Domínio de negócio +- Equipe de desenvolvimento +- Equipe de segurança +- Aplicações de software +- Família de produtos abrangente +- Cliente ou subsidiária +- Estrutura de relatórios +- etc. + +O tema dos exemplos acima ilustra a utilidade essencial das Organizações: elas geralmente devem representar limites estáveis e duradouros dentro do seu programa de segurança. + +## Dados e estrutura da Organização + +Como as Organizações não são varridas diretamente, o único campo obrigatório para criá-las é um nome. Além disso, elas funcionam como contêineres para Ativos e seus Engajamentos, Testes e Achados descendentes. + +Ao criar uma Organização, considere como sua estrutura influenciará seus relatórios. Você precisa principalmente que as Organizações representem as equipes que trabalham nos projetos (Ativos) que as Organizações vão conter? Ou as Organizações representariam melhor projetos abrangentes que contêm diferentes iterações dos projetos (Ativos) dentro deles? + +Se você tem uma única Organização que contém todas as informações relevantes para um determinado domínio de negócio ou equipe de desenvolvimento, representá-la como uma Organização facilitará relatórios mais consistentes, em vez de ter que reunir um relatório a partir de vários Ativos e Organizações. + +Se um determinado projeto de software tem muitas implantações ou versões distintas, pode valer a pena criar uma única Organização que cubra o escopo de todo o projeto e deixar cada versão existir como Ativos individuais. Em alguns fluxos de trabalho, as Organizações também podem ser usadas para separar estágios do ciclo de vida do software: uma Organização para "Em Desenvolvimento", outra Organização para "Em Produção", etc. + +As Organizações podem ser usadas para determinar o acesso a subsidiárias, empresas adquiridas ou outras unidades de negócio regulamentadas para fins de RBAC. Em empresas complexas, onde há muitos projetos únicos com regras de acesso diferentes, as Organizações são particularmente relevantes. + +Em última análise, a decisão de como usar Organizações e Ativos depende de como você deseja melhor refletir sua estrutura organizacional exclusiva e as necessidades da sua equipe de segurança. + +Abaixo estão alguns exemplos de estruturas para orientar como você designa seus objetos como Organizações ou Ativos. + +- **Organização**: Divisão de Pagamentos + - Ativo: API de Pagamentos - Produção + - Ativo: API de Pagamentos - Homologação + - Ativo: Worker de Faturamento + +- **Organização**: Produto de Software A + - Ativo: Portal Web + - Ativo: Backend Mobile + +Além disso, o guia a seguir ilustra se algo é melhor representado por uma Organização ou por um Ativo: + +| Organizações | Ativos | +|--------------|--------| +| Unidades de negócio | Aplicações individuais | +| Departamentos | Implantações/ambientes | +| Domínios de propriedade de segurança | Componentes de infraestrutura | +| Famílias de produtos | Microsserviços específicos | +| Relatórios em nível de portfólio | Alvos de varredura | +| Clientes | Versões específicas de software | + +Conforme observado, sua estrutura pode variar de acordo com as necessidades de segurança exclusivas da sua equipe. + +## Acessando Organizações + +As Organizações são acessíveis pela barra lateral. O submenu também oferece a opção de criar novas Organizações. + +![image](images/organization_ss1.png) + +### Visualização da Organização + +A visualização de uma Organização contém uma variedade de tabelas e gráficos para interpretar seu status rapidamente. Isso inclui: +- **Descrição** +- **Caixa de seleção Chave/Crítica** + - Marcar Crítica ou Chave é usado somente para fins de filtragem +- **Lista de Ativos dentro da Organização** +- **Usuários autorizados** (Usuários do DefectDojo) + +## Trabalhando com Organizações + +### Criar Organizações + +Existem duas maneiras de criar Organizações: + +- Na opção **Adicionar Organização** no menu lateral +- No botão **Adicionar Organização** no topo da lista Todas as Organizações + +### Editar Organizações + +As Organizações podem ser editadas clicando em **Editar** no menu suspenso no canto superior direito da tabela de Descrição na visualização da Organização. O mesmo menu também pode ser acessado clicando no menu kebab ⋮ à esquerda da Organização na lista Todas as Organizações. + +Todos os campos subsequentes que podem ser editados também estão disponíveis quando a Organização está sendo criada. + +### Excluir Organizações + +A exclusão de uma Organização pode ser realizada selecionando **Excluir Organização** nas configurações da Organização. + +Como as Organizações ficam no topo da hierarquia, excluí-las remove todo o histórico de segurança, relacionamentos e objetos filhos a jusante, tais como: +- Quaisquer Ativos, Engajamentos e Testes contidos na Organização +- Todo o histórico de segurança associado, incluindo Achados e integrações +- Quaisquer Epics do Jira vinculados +- Todas as notas e uploads de arquivos associados aos Ativos, Engajamentos e Testes dentro dessa Organização + +A exclusão de uma Organização não pode ser desfeita. Se você quiser "desativar" uma Organização sem excluir os dados subjacentes (por exemplo, preservando registros de testes de software legados para fins de auditoria), você pode alterar o nome da Organização ou adicionar uma Tag para indicar que ela está em um estado obsoleto. + +## Organizações vs. Metadados + +As Organizações têm como objetivo representar a propriedade estrutural ou os limites de relatórios, e não classificações leves. Atributos como status de implantação, rótulos internos ou estados de fluxo de trabalho temporários podem ser melhor representados por meio de tags ou metadados, em vez de Organizações separadas. + +## Limites das Organizações + +As Organizações estabelecem tanto limites de relatórios quanto de acesso dentro do DefectDojo. Como integrações, permissões de RBAC, propriedade, métricas e modelos de deduplicação frequentemente herdam a estrutura das Organizações, projetar limites claros desde o início ajuda a evitar a expansão descontrolada da hierarquia e a fragmentação de relatórios mais tarde. + +### Achados e automação + +Embora as integrações normalmente sejam configuradas em objetos de nível inferior, como Ativos, Engajamentos ou Achados, as Organizações ainda definem os limites de propriedade, relatórios e acesso dentro dos quais essas integrações operam. + +As permissões são propagadas para baixo, o que significa que o acesso a uma Organização concede automaticamente acesso a todos os objetos dentro dessa Organização (por exemplo, Ativos, Engajamentos, Testes e Achados). + +O modelo de RBAC do DefectDojo pode ser usado para controlar o acesso de usuários humanos, mas também pode restringir o acesso de tokens de API a Organizações específicas. + +Para mais informações sobre funções de usuário, consulte nosso artigo [Permissões](/admin/user_management/os__authorized_users/). + +### Propriedade + +Como objetos de nível superior, as Organizações também implicam propriedade sobre os objetos filhos dentro delas. O acompanhamento de SLA, os fluxos de trabalho de correção, o roteamento de tickets e a governança geral fluem com mais tranquilidade quando as Organizações foram configuradas para refletir com precisão os indivíduos responsáveis por elas. + +### Métricas/Relatórios + +Os painéis, blocos e visualizações de métricas podem ser filtrados por Organização, tornando-os um componente essencial de como seus dados de segurança são calculados, visualizados e, por fim, exportados. + +Para fins de relatório, geralmente é mais fácil combinar várias Organizações em um único documento do que subdividir uma única Organização em documentos separados. Portanto, recomendamos configurar as Organizações no nível mais granular que fizer sentido para os relatórios da sua equipe. Por exemplo, não há necessidade de representar uma grande divisão de negócios como uma Organização se você for reportar principalmente para departamentos individuais dentro dessa divisão. + +Estruturar suas Organizações de forma eficaz para refletir as necessidades de relatório da sua equipe é fundamental para avaliar com precisão sua postura de segurança. Para mais informações sobre Métricas, clique [aqui](/metrics_reports/dashboards/introduction_dashboard/). + +### Deduplicação + +A deduplicação no DefectDojo ocorre no nível do Ativo e não é afetada pela Organização pai. diff --git a/docs/content/asset_modelling/engagements_tests/OS__organizations.zh-hans.md b/docs/content/asset_modelling/engagements_tests/OS__organizations.zh-hans.md new file mode 100644 index 0000000000..73c1ddcd70 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__organizations.zh-hans.md @@ -0,0 +1,139 @@ +--- +title: 组织 +description: 了解 DefectDojo OS 中的组织 +audience: opensource +weight: 1 +aliases: +- /zh-hans/asset_modelling/engagements_tests/os_producttype/ +- /zh-hans/en/asset_modelling/engagements_tests/os_producttype/ +--- + +**组织** → 资产 → 测试活动 → 测试 → 发现项 + +## 概述 + +**组织**位于 DefectDojo 对象层级结构的最顶层。组织与层级结构中位于其下的对象——资产、测试活动、测试和发现项——不同，因为它们并非技术性的扫描目标，而是主要作为组织性抽象，用于按以下方式划分您的安全工作： +- 业务领域 +- 开发团队 +- 安全团队 +- 软件应用 +- 总体产品系列 +- 客户或子公司 +- 报告结构 +- 等等 + +上述示例的共同主题体现了组织的核心作用：组织通常应代表您安全计划中稳定、长期存在的边界。 + +## 组织的数据与结构 + +由于组织不会被直接扫描，创建组织所需的唯一必填字段是名称。除此之外，组织充当资产及其下属测试活动、测试和发现项的容器。 + +创建组织时，请考虑其结构将如何影响您的报告方式。您主要是需要组织来代表负责组织内所含项目（资产）的团队？还是希望组织更好地代表包含其中不同项目迭代版本（资产）的总体项目？ + +如果您有一个组织，其中包含特定业务领域或开发团队的所有相关信息，将其表示为一个组织将有助于更顺畅地生成报告，而不必从多个资产和组织中拼凑报告。 + +如果某个软件项目拥有许多不同的部署或版本，那么创建一个涵盖整个项目范围的组织，并让每个版本作为单独的资产存在，可能是值得的。在某些工作流程中，组织也可用于区分软件生命周期阶段：例如，一个组织代表“开发中”，另一个组织代表“生产中”等等。 + +组织可用于确定对子公司、被收购公司或其他受监管业务部门的访问权限，以满足基于角色的访问控制（RBAC）需求。在业务复杂、存在大量具有不同访问规则的独特项目的情况下，组织尤为重要。 + +归根结底，如何使用组织和资产取决于您希望如何最好地反映您独特的组织结构以及安全团队的需求。 + +以下是一些示例结构，供您参考如何将对象指定为组织或资产。 + +- **组织**：支付部门 + - 资产：支付 API - 生产环境 + - 资产：支付 API - 预发布环境 + - 资产：账单处理服务 + +- **组织**：软件产品 A + - 资产：Web 门户 + - 资产：移动端后台 + +此外，以下是一份说明性指南，用于判断某个事物更适合表示为组织还是资产： + +| 组织 | 资产 | +|--------------|--------| +| 业务单元 | 单个应用程序 | +| 部门 | 部署/环境 | +| 安全责任域 | 基础设施组件 | +| 产品系列 | 特定微服务 | +| 组合层面的报告 | 扫描目标 | +| 客户 | 特定软件版本 | + +如前所述，您的结构可能会因您独特的安全需求而有所不同。 + +## 访问组织 + +组织可通过侧边栏访问。子菜单还提供了创建新组织的选项。 + +![image](images/organization_ss1.png) + +### 组织视图 + +组织视图包含各种表格和图表，可让您一目了然地了解其状态。其中包括： +- **描述** +- **关键/严重复选框** + - 勾选“严重”或“关键”仅用于筛选目的 +- **组织内的资产列表** +- **授权用户**（DefectDojo 用户） + +## 使用组织 + +### 创建组织 + +创建组织有两种方式： + +- 通过侧边菜单中的**添加组织**选项 +- 通过“所有组织”列表顶部的**添加组织**按钮 + +### 编辑组织 + +要编辑组织，可在组织视图中“描述”表格右上角的下拉菜单中点击**编辑**。也可以通过点击“所有组织”列表中组织左侧的 ⋮ 竖排菜单来访问同一菜单。 + +随后可编辑的所有字段，在创建组织时也同样可用。 + +### 删除组织 + +要删除组织，可在组织的设置中选择**删除组织**。 + +由于组织位于层级结构的顶端，删除组织会移除其下所有安全历史记录、关联关系及子对象，包括： +- 组织内包含的所有资产、测试活动和测试 +- 所有相关的安全历史记录，包括发现项和集成 +- 任何关联的 Jira Epic +- 与该组织内资产、测试活动和测试相关联的所有备注和上传文件 + +删除组织的操作无法撤销。如果您希望在不删除底层数据的情况下“停用”某个组织（例如出于审计目的保留旧版软件测试记录），可以更改组织的名称，或添加标签以表明其处于已废弃状态。 + +## 组织与元数据 + +组织旨在表示结构性的归属关系或报告边界，而非轻量级的分类。诸如部署状态、内部标签或临时工作流状态等属性，用标签或元数据来表示可能比创建单独的组织更为合适。 + +## 组织边界 + +组织在 DefectDojo 中同时确立了报告边界和访问边界。由于集成、RBAC 权限、归属关系、指标以及去重模型通常会继承组织的结构，因此尽早设计清晰的边界有助于避免日后出现层级结构膨胀和报告碎片化的问题。 + +### 发现项与自动化 + +尽管集成通常配置在资产、测试活动或发现项等较低层级的对象上，但组织仍然定义了这些集成运作所依据的归属关系、报告及访问边界。 + +权限会向下级联，这意味着对某个组织的访问权限会自动授予对该组织内所有对象（例如资产、测试活动、测试和发现项）的访问权限。 + +DefectDojo 的 RBAC 模型既可用于控制人工用户的访问权限，也可用于限制 API 令牌对特定组织的访问权限。 + +有关用户角色的更多信息，请参阅我们的[权限](/admin/user_management/os__authorized_users/)一文。 + +### 归属 + +作为顶层对象，组织也隐含着对其内部子对象的归属关系。当组织的设置能够准确反映负责人时，SLA 跟踪、修复工作流、工单路由以及总体治理都会运作得更加顺畅。 + +### 指标/报告 + +指标仪表板、磁贴和视图都可以按组织进行筛选，这使组织成为安全数据如何被计算、可视化并最终导出的关键组成部分。 + +就报告而言，将多个组织合并到一份文档中通常比将单个组织拆分为多份文档更容易。因此，我们建议按照对您团队报告有意义的粒度来设置组织。例如，如果您主要是向某个业务部门内的各个具体部门进行报告，就没有必要将整个大型业务部门表示为一个组织。 + +有效地构建组织结构以反映您的报告需求，对于准确评估您的安全态势至关重要。有关指标的更多信息，请点击[此处](/metrics_reports/dashboards/introduction_dashboard/)。 + +### 去重 + +DefectDojo 中的去重发生在资产层级，不受上级组织的影响。 diff --git a/docs/content/asset_modelling/engagements_tests/OS__tests.it.md b/docs/content/asset_modelling/engagements_tests/OS__tests.it.md new file mode 100644 index 0000000000..8bc6ca55ec --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__tests.it.md @@ -0,0 +1,274 @@ +--- +title: Test +description: Comprendere i Test in DefectDojo OS +audience: opensource +weight: 4 +--- + +Organizzazioni → Asset → Engagement → **TEST** → Riscontri + +## Panoramica + +Un Test è un contenitore per una o più esecuzioni di scansione, utilizzate per individuare le vulnerabilità in un Prodotto. I Test sono la componente finale e più granulare della gerarchia dei prodotti di DefectDojo, fungendo da contenitore per i Riscontri che derivano dall'esecuzione di uno strumento di sicurezza o di una valutazione manuale, aggiungendo al contempo il contesto in cui tali Riscontri sono stati individuati (ossia quale strumento li ha segnalati, quando tale strumento è stato eseguito l'ultima volta, ecc.). + +Esempi di Test includono: +- Static Application Security Testing +- Dynamic Application Security Testing +- Software Composition Analysis +- Scansioni di sicurezza dei container +- Scansioni di infrastruttura / rete +- Penetration test manuali +- Scansioni di pipeline CI/CD + +### Tipi di Test + +Esistono due modi principali per creare Test in DefectDojo: +1. **Parser specifici per fornitore** (ad es. Burp, OWASP ZAP, Acunetix, Invicti) +2. **Generic Findings Import** + +Ciascun metodo può creare nuovi Test o reimportare i Riscontri in Test esistenti, a seconda della configurazione e della strategia di deduplicazione. + +Sebbene ciascun metodo differisca principalmente nel modo in cui i dati di scansione vengono analizzati e importati, alla fine tutti comportano l'associazione dei Riscontri a un Test. + +#### Parser + +I **Parser** sono componenti che elaborano formati di output di scansione specifici (ad es. XML, JSON, CSV) e li mappano nel modello interno dei Riscontri di DefectDojo. Quando i risultati di una scansione vengono importati, DefectDojo utilizza il parser selezionato per estrarre i Riscontri e collegarli a un Test appena creato o esistente. + +#### Generic Findings Import + +Quando non esiste un parser nativo per un determinato strumento, **Generic Findings Import** consente di importare i riscontri utilizzando uno schema JSON o CSV standardizzato, indipendentemente dalla fonte originale. + +DefectDojo analizza i dati forniti, crea un nuovo Test (oppure importa in uno esistente) e collega i Riscontri. Viene inoltre creato un Test Type corrispondente in base al campo opzionale `type` del report: quando `type` viene omesso (o è uguale al tipo di scansione), il Test Type è “Generic Findings Import”; quando `type` viene fornito, diventa “{type} Scan (Generic Findings Import)” (un `type` che termina già con il suffisso “(Generic Findings Import)” viene utilizzato così com'è). + +| | **Parser nativi** | **Generic Findings Import** | +|----------|---------------|------------------------| +| **Scopo principale** | Importa gli output di strumenti supportati | Importa dati non supportati/personalizzati tramite uno schema fisso | +| **Formato di input** | Specifico per lo strumento (ad es. ZAP XML, SARIF) | Schema JSON/CSV rigoroso | +| **Chi gestisce la normalizzazione** | DefectDojo (parser integrato) | Utente (deve rispettare lo schema) | +| **Trigger di creazione del Test** | Caricamento manuale o import via API | Caricamento manuale o import via API | +| **Test Type** | Predefinito (ad es. “ZAP Scan”) | Tipo “Generic” creato automaticamente | +| **Impegno di configurazione** | Basso | Moderato (richiede trasformazione dei dati) | +| **Flessibilità** | Bassa (solo strumenti supportati) | Media | +| **Livello di automazione** | Basso–Moderato | Basso–Moderato | +| **Caso d'uso tipico** | Scanner standard (SAST, DAST, SCA) | Script personalizzati, strumenti non supportati | + +Indipendentemente dal metodo di importazione, tutti i dati di scansione in DefectDojo vengono infine rappresentati come Riscontri collegati a un Test, che funge da unità di esecuzione e tracciamento del ciclo di vita. + +### Dati del Test + +I Test memorizzano una serie di metadati utili a documentare i vari aspetti di ciascuno sforzo di test, come: +- Titolo / nome del Test +- Tipo di Test +- Descrizione / note del Test +- Data di inizio e fine +- L'Ambiente in cui il Test è stato eseguito (ad es. Development, Staging, Pre-Production, Production, ecc.) +- Versione / Branch / Build ID / Commit Hash +- Configurazione della scansione API +- File aggiuntivi utilizzabili per audit o reimportazioni successive +- L'Engagement, l'Asset e l'Organizzazione principali +- Cronologia di importazione e reimportazione + +Ogni Test mantiene una cronologia di importazione, che registra tutte le importazioni e reimportazioni di scansioni associate al Test. Questo include metadati come data della scansione, versione, branch, commit hash e build ID. + +Questa cronologia garantisce la tracciabilità tra più esecuzioni di scansione all'interno dello stesso Test. + +### Permessi + +Più Test possono essere memorizzati all'interno di un singolo Engagement, e gli Engagement sono memorizzati all'interno dei Prodotti. Di conseguenza, l'accesso a un Prodotto concede automaticamente l'accesso a tutti i Test (ed Engagement) al suo interno. I Test non dispongono di elenchi di controllo degli accessi indipendenti. + +### Accesso ai Test + +Sebbene i Test esistano come oggetto indipendente in DefectDojo OS, non dispongono di una sezione specifica dedicata all'interno dell'interfaccia utente. Pertanto, ogni Test è accessibile principalmente tramite il Prodotto e/o l'Engagement che lo contiene. + +### Vista Test + +La vista Test ospita diverse tabelle, tra cui l'Engagement principale, la cronologia di importazione e reimportazione, un elenco dei Riscontri contenuti nel Test, nonché eventuali Gruppi di Riscontri. + +Sono presenti anche tabelle per Potential Findings, File e Note, tutte aggiungibili manualmente. + +#### Impostazioni del Test + +Le seguenti impostazioni sono disponibili in ciascuna vista Test: +- **Edit Test** + - Consente di modificare i dati del Test, come titolo, pianificazione, ambiente e altri dettagli. +- **Copy Test** + - Duplica un Test, insieme a tutti i metadati e i Riscontri associati, e ne consente l'attribuzione a un Engagement diverso. +- **Re-Upload Scan** + - Avvia il processo di reimportazione. Maggiori informazioni sulla reimportazione sono riportate più avanti in questo articolo. +- **Add Notes** + - Consente all'utente di aggiungere una Nota. In fondo alla pagina è presente anche una tabella delle Note. + - Una Nota può essere impostata come Private, nel qual caso non viene inviata a Jira, ai Report e alle esportazioni dei Riscontri. +- **Report** + - Avvia il processo di generazione di un Report, in cui è possibile applicare numerosi filtri per creare un report contenente solo i Riscontri filtrati. +- **Add To Calendar** + - Scarica un file .ics del Test selezionato, che può essere aggiunto alla vostra applicazione di calendario di terze parti. +- **View History** + - Apre una cronologia delle modifiche apportate al Test a fini di tracciamento, reporting e audit. + +## Lavorare con i Test + +### Creare Test + +I Test possono essere creati automaticamente quando i dati di scansione vengono importati direttamente in un Engagement, generando un nuovo Test contenente i dati della scansione. I Test possono anche essere creati in previsione della pianificazione di futuri Engagement, oppure per riscontri di sicurezza inseriti manualmente che richiedono tracciamento e remediation. + +#### Flussi di lavoro manuali + +Esistono diversi modi per creare un Test nella versione OS: + +- Selezionate un Prodotto e fate clic su “Import Scan Results” nel menu Findings nella barra di navigazione + - Questo creerà un Engagement ad hoc per contenere il Test + +![image](images/tests_ss5.png) + +- Selezionate un Engagement all'interno di un Prodotto, fate clic sul menu a discesa nella sottosezione Tests, quindi fate clic su “Add Tests” oppure su “Import Scan Results” + - Questo creerà il Test risultante direttamente all'interno dell'Engagement scelto + +![image](images/tests_ss6.png) + +- Durante la creazione di un Engagement + +![image](images/tests_ss7.png) + +Utilizzando il terzo metodo sopra descritto, durante la creazione di un Engagement potete: + +- Importare immediatamente i risultati di una scansione +- Creare un Test vuoto (nel quale importerete in seguito una scansione) +- Non fare nessuna delle due cose e limitarvi a creare l'Engagement facendo clic su “Done” + +Avrete la possibilità di aggiungere metadati sia durante l'importazione di una scansione sia durante la creazione di un Test vuoto. Eventuali metadati verranno riportati nella sezione Import History della vista Test. + +#### Flussi di lavoro automatizzati + +Nei flussi di lavoro automatizzati, i Test possono essere creati a livello programmatico come parte del processo di importazione della scansione, consentendo alle pipeline di caricare i risultati senza che sia necessario creare un Test manualmente in anticipo. + +Quando si utilizza l'API per importare i risultati di una scansione, è possibile creare automaticamente un nuovo Test fornendo un engagement anziché un test. + +##### API + +curl -X POST `"https:///api/v2/import-scan/"` \ + -H `"Authorization: Token "` \ + -F `"engagement=45"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` + +In base a quanto sopra, viene creato un nuovo Test all'interno dell'Engagement specificato e i risultati della scansione vengono collegati a quel Test. + +Se viene invece fornito un ID `test`, i risultati della scansione verranno aggiunti a un Test esistente, come avviene comunemente nei flussi di reimportazione. + +### Modificare i Test + +I Test possono essere modificati facendo clic su **Edit Test** dal menu kebab ⋮ nella tabella Tests all'interno della vista dell'Engagement principale, oppure dal menu delle impostazioni nella vista del Test. Tutti i campi modificabili di seguito sono disponibili anche durante la creazione del Test. + +![image](images/tests_ss24.png) + +![image](images/tests_ss12.png) + +#### Aggiungere manualmente Riscontri a un Test + +Un Riscontro può essere aggiunto manualmente a un Test facendo clic su **Add Finding to Test** dal menu kebab ⋮ accanto al Test nella vista dell'Engagement principale, oppure dalle impostazioni della tabella Findings nella vista del Test. + +![image](images/tests_ss29.png) + +![image](images/tests_ss30.png) + +### Eliminare i Test + +È possibile eliminare un Test selezionando **Delete Test** dal menu kebab ⋮ accanto al Test nella vista dell'Engagement principale, oppure dal menu delle impostazioni nella vista del Test. Questa azione non può essere annullata. + +L'eliminazione di un Test comporta anche l'eliminazione di tutti i Riscontri contenuti in quel Test. + +![image](images/tests_ss25.png) + +![image](images/tests_ss26.png) + +## Reimportazione + +La reimportazione delle scansioni all'interno dei Test è fondamentale per una deduplicazione efficace. Quando i risultati di una scansione vengono reimportati nello stesso Test: + +- I Riscontri esistenti possono essere aggiornati +- I Riscontri duplicati possono essere soppressi +- Possono essere creati nuovi Riscontri se non viene trovata alcuna corrispondenza + +Questo comportamento dipende dalle regole di deduplicazione configurate e dal tipo di scansione. + +Creare un nuovo Test invece di reimportare in uno esistente può comportare la creazione di Riscontri duplicati anziché il loro aggiornamento. + +#### Reimportazione vs. Importazione + +La reimportazione viene tipicamente utilizzata quando: + +- Si eseguono scansioni ricorrenti sullo stesso obiettivo +- Si monitora l'evoluzione dei Riscontri nel tempo +- Si mantiene una visione continua della postura di sicurezza applicativa + +Al contrario, l'importazione (creazione di un nuovo Test) è più adatta per esecuzioni di scansione singole o indipendenti. + +### Reimportazione dei risultati di scansione (interfaccia utente) + +Per aggiungere nuovi dati a un Test esistente, potete fare clic su **Re-Upload Scan Results** dal menu kebab ⋮ accanto al Test nella vista dell'Engagement principale, oppure su **Re-Upload Scan** nel menu delle impostazioni della vista del Test. + +![image](images/tests_ss27.png) + +![image](images/tests_ss10.png) + +Durante la compilazione del modulo Reimport Scan, avrete la possibilità di aggiornare i metadati della scansione in fase di reimportazione, tra cui versione, branch tag, commit hash e build ID. + +Queste modifiche vengono riportate nella sezione Import History della vista Test, che includerà anche gli stessi metadati delle scansioni importate in precedenza. + +Ad esempio, nella schermata seguente, branch tag, build ID, commit hash e versione sono stati tutti aggiornati manualmente tra l'importazione iniziale e la successiva reimportazione. + +![image](images/tests_ss28.png) + +Per modificare i metadati della scansione reimportata più di recente, seguite le istruzioni riportate nella sezione precedente Modificare i Test e aggiornate i metadati come desiderato. È possibile modificare solo i metadati dell'importazione più recente. + +### Reimportazione dei risultati di scansione (API) + +Quando i Test vengono creati o aggiornati tramite una pipeline CI/CD, è possibile includere metadati provenienti dall'esecuzione della pipeline, in modo che i Test possano essere collegati correttamente al codice che hanno scansionato. Questo consente di: +- Associare i risultati della scansione a un commit o branch specifico. +- Monitorare l'evoluzione dei Riscontri attraverso le modifiche al codice. +- Migliorare la Deduplicazione comprendendo quando due scansioni si applicano alla stessa versione del codice o a versioni diverse. +- Supportare la tracciabilità (auditability) mostrando esattamente quale codice è stato scansionato e quando. + +L'API di DefectDojo accetta questi valori durante l'importazione o la reimportazione, in modo che possano essere memorizzati come parte dell'importazione della scansione e riportati nella cronologia di importazione del Test. Questi metadati possono essere utilizzati per identificare commit hash o qualsiasi altra informazione rilevante del repository associata a un'esecuzione CI/CD. + +#### Campi di metadati supportati + +L'API supporta un insieme definito di campi di metadati che possono essere inclusi durante la reimportazione. Tra questi: + +- `tags` +- `version` +- `build_id` +- `branch_tag` +- `commit_hash` +- `scan_date` +- `minimum_severity` +- flag `active / verified` + +Questi campi rappresentano il meccanismo principale per collegare metadati contestuali durante un'operazione di reimportazione. + +Nelle pipeline automatizzate, i metadati forniti più comunemente includono: +- build_id (identificatore del job CI) +- commit_hash (riferimento al controllo del codice sorgente) +- branch_tag (contesto di branch o ambiente) +- tags (ad es. nightly, staging, production) + +Questi campi garantiscono la tracciabilità tra le scansioni senza richiedere alcun intervento manuale. + +Sebbene i metadati possano essere aggiornati manualmente tramite il modulo Reimport Scan, la maggior parte degli ambienti automatizzati gestisce questa operazione chiamando direttamente l'endpoint `/api/v2/reimport-scan/`. Questo approccio consente alla pipeline di collegare automaticamente i metadati al momento della reimportazione. + +##### Reimportazione API con metadati + +curl -X POST `"https:///api/v2/reimport-scan/"` \ + -H `"Authorization: Token "` \ + -F `"test=123"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` \ + -F `"tags=nightly,api-scan"` \ + -F `"version=1.4.2"` \ + -F `"build_id=jenkins-842"` \ + -F `"branch_tag=main"` \ + -F `"commit_hash=a1b2c3d4"` + +##### Metadati, reimportazione e scansioni pianificate + +Le scansioni possono anche essere pianificate per essere eseguite a intervalli regolari, ad esempio tramite job cron. Le scansioni pianificate non sono legate all'attività del repository, il che rende irrilevanti metadati come commit hash o nomi di branch, a meno che non vengano iniettati esplicitamente dallo script stesso. Ciononostante, l'uso della reimportazione può comunque essere utile se preferite mantenere un registro continuo della vostra postura di sicurezza all'interno di un singolo Test. diff --git a/docs/content/asset_modelling/engagements_tests/OS__tests.pt-br.md b/docs/content/asset_modelling/engagements_tests/OS__tests.pt-br.md new file mode 100644 index 0000000000..fa4f2d1d22 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__tests.pt-br.md @@ -0,0 +1,274 @@ +--- +title: Testes +description: Entendendo os Testes no DefectDojo OS +audience: opensource +weight: 4 +--- + +Organizações → Ativos → Engajamentos → **TESTES** → Achados + +## Visão geral + +Um Teste é um contêiner para uma ou mais execuções de varredura, usadas para descobrir falhas em um Produto. Os Testes são o componente final e mais granular da hierarquia de produtos do DefectDojo, servindo como o contêiner para os Achados resultantes da execução de uma ferramenta de segurança ou de uma avaliação manual, além de adicionar o contexto em que tais Achados foram encontrados (ou seja, qual ferramenta os reportou, quando essa ferramenta foi executada pela última vez, etc.). + +Exemplos de Testes incluem: +- Teste Estático de Segurança de Aplicações +- Teste Dinâmico de Segurança de Aplicações +- Análise de Composição de Software +- Varreduras de Segurança de Contêineres +- Varreduras de Infraestrutura / Rede +- Testes de Penetração Manuais +- Varreduras de Pipeline de CI/CD + +### Tipos de Teste + +Existem duas formas principais de criar Testes no DefectDojo: +1. **Parsers específicos de fornecedor** (por exemplo, Burp, OWASP ZAP, Acunetix, Invicti) +2. **Importação Genérica de Achados** + +Cada método pode criar novos Testes ou reimportar Achados para Testes existentes, dependendo da configuração e da estratégia de deduplicação. + +Embora cada método difira principalmente na forma como os dados de varredura são analisados e ingeridos, todos eles resultam, em última instância, em Achados associados a um Teste. + +#### Parsers + +**Parsers** são componentes que processam formatos específicos de saída de varredura (por exemplo, XML, JSON, CSV) e os mapeiam para o modelo interno de Achado do DefectDojo. Quando os resultados de uma varredura são importados, o DefectDojo usa o parser selecionado para extrair os Achados e anexá-los a um Teste recém-criado ou existente. + +#### Importação Genérica de Achados + +Quando não existe um parser nativo para uma determinada ferramenta, a **Importação Genérica de Achados** permite importar achados usando um esquema JSON ou CSV padronizado, independentemente da fonte original. + +O DefectDojo analisa os dados fornecidos, cria um novo Teste (ou importa para um já existente) e anexa os Achados. Um Tipo de Teste correspondente também é criado com base no campo opcional `type` do relatório: quando `type` é omitido (ou é igual ao tipo de varredura) o Tipo de Teste é "Generic Findings Import"; quando `type` é fornecido, ele se torna "{type} Scan (Generic Findings Import)" (um `type` que já termina com o sufixo "(Generic Findings Import)" é usado literalmente). + +| | **Parsers Nativos** | **Importação Genérica de Achados** | +|----------|---------------|------------------------| +| **Objetivo principal** | Ingerir saídas de ferramentas suportadas | Ingerir dados não suportados/personalizados por meio de um esquema fixo | +| **Formato de entrada** | Específico da ferramenta (por exemplo, ZAP XML, SARIF) | Esquema estrito JSON/CSV | +| **Quem trata a normalização** | DefectDojo (parser integrado) | Usuário (deve estar em conformidade com o esquema) | +| **Gatilho de criação do Teste** | Upload manual ou importação via API | Upload manual ou importação via API | +| **Tipo de Teste** | Predefinido (por exemplo, "ZAP Scan") | Tipo "Generic" criado automaticamente | +| **Esforço de configuração** | Baixo | Moderado (é necessária transformação de dados) | +| **Flexibilidade** | Baixa (somente ferramentas suportadas) | Média | +| **Nível de automação** | Baixo a moderado | Baixo a moderado | +| **Caso de uso típico** | Scanners padrão (SAST, DAST, SCA) | Scripts personalizados, ferramentas não suportadas | + +Independentemente do método de ingestão, todos os dados de varredura no DefectDojo são, em última instância, representados como Achados anexados a um Teste, que serve como a unidade de execução e de rastreamento do ciclo de vida. + +### Dados do Teste + +Os Testes armazenam uma variedade de metadados que ajudam a documentar diversos componentes de cada esforço de teste, tais como: +- Título / nome do Teste +- Tipo de Teste +- Descrição / notas do Teste +- Data de início e término +- O Ambiente em que o Teste foi executado (por exemplo, Desenvolvimento, Homologação, Pré-Produção, Produção, etc.) +- Versão / Branch / ID de Build / Hash de Commit +- Configuração de varredura de API +- Arquivos adicionais que podem ser usados para auditorias posteriores ou reimportações +- O Engajamento, o Ativo e a Organização pais +- Histórico de importação e reimportação + +Cada Teste mantém um histórico de importação, que registra todas as importações e reimportações de varredura associadas ao Teste. Isso inclui metadados como data da varredura, versão, branch, hash de commit e ID de build. + +Esse histórico fornece rastreabilidade em várias execuções de varredura dentro do mesmo Teste. + +### Permissões + +Vários Testes podem ser armazenados dentro de um único Engajamento, e os Engajamentos são armazenados dentro dos Produtos. Assim, o acesso a um Produto concede automaticamente acesso a todos os Testes (e Engajamentos) dentro desse Produto. Os Testes não possuem listas de controle de acesso independentes. + +### Acessando Testes + +Embora os Testes existam como um objeto independente no DefectDojo OS, eles não têm uma seção específica dedicada a eles na interface. Assim, cada Teste é acessível principalmente através do Produto e/ou Engajamento que o contém. + +### Visualização do Teste + +A visualização do Teste hospeda uma variedade de tabelas, incluindo o Engajamento pai, o histórico de importação e reimportação, uma lista de Achados contidos no Teste, bem como quaisquer Grupos de Achados. + +Também há tabelas para Achados Potenciais, Arquivos e Notas, todas as quais podem ser adicionadas manualmente. + +#### Configurações do Teste + +As seguintes configurações estão disponíveis em cada visualização de Teste: +- **Editar Teste** + - Permite a edição dos dados do Teste, como título, agendamento, ambiente e outros detalhes diversos. +- **Copiar Teste** + - Duplica um Teste, junto com todos os metadados e Achados associados, e permite atribuí-lo a um Engajamento diferente. +- **Reenviar Varredura** + - Inicia o processo de reimportação. Mais informações sobre Reimportação estão disponíveis mais adiante neste artigo. +- **Adicionar Notas** + - Permite que o usuário adicione uma Nota. Uma tabela de Notas também está presente na parte inferior da página. + - Uma Nota pode ser marcada como Privada, caso em que fica impedida de ser enviada para o Jira, Relatórios e exportações de Achados. +- **Relatório** + - Inicia o processo de geração de um Relatório, no qual inúmeros filtros podem ser aplicados para criar um relatório apenas com os Achados filtrados. +- **Adicionar ao Calendário** + - Baixa um arquivo .ics do Teste escolhido, que pode ser adicionado ao seu aplicativo de calendário de terceiros. +- **Ver Histórico** + - Abre um histórico das edições feitas no Teste para fins de rastreamento, relatórios e auditoria. + +## Trabalhando com Testes + +### Criar Testes + +Os Testes podem ser criados automaticamente quando dados de varredura são importados diretamente em um Engajamento, resultando em um novo Teste contendo os dados da varredura. Os Testes também podem ser criados em antecipação ao planejamento de futuros Engajamentos, ou para achados de segurança inseridos manualmente que exigem rastreamento e correção. + +#### Fluxos de Trabalho Manuais + +Existem várias maneiras de criar um Teste na versão OS: + +- Selecione um Produto e clique em "Importar Resultados de Varredura" no menu Achados na barra de navegação + - Isso criará um Engajamento ad hoc para conter o Teste + +![image](images/tests_ss5.png) + +- Selecione um Engajamento dentro de um Produto, clique no menu suspenso na subseção Testes e clique em "Adicionar Testes" ou "Importar Resultados de Varredura" + - Isso criará o Teste resultante diretamente dentro do Engajamento escolhido + +![image](images/tests_ss6.png) + +- Durante a criação de um Engajamento + +![image](images/tests_ss7.png) + +Usando o terceiro método acima, você pode fazer o seguinte durante a criação de um Engajamento: + +- Importar imediatamente os resultados da varredura +- Criar um shell de Teste (no qual você importará uma varredura posteriormente) +- Não fazer nenhum dos dois e simplesmente criar o Engajamento clicando em "Concluído" + +Você terá a oportunidade de adicionar metadados tanto ao importar uma varredura quanto ao criar um shell de Teste. Quaisquer metadados serão refletidos na seção Histórico de Importação da Visualização do Teste. + +#### Fluxos de Trabalho Automatizados + +Em fluxos de trabalho automatizados, os Testes podem ser criados programaticamente como parte do processo de importação de varredura, permitindo que os pipelines enviem resultados sem exigir que um Teste seja criado manualmente com antecedência. + +Ao usar a API para importar resultados de varredura, um novo Teste pode ser criado automaticamente fornecendo um engagement em vez de um test. + +##### API + +curl -X POST `"https:///api/v2/import-scan/"` \ + -H `"Authorization: Token "` \ + -F `"engagement=45"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` + +Diante do exposto acima, um novo Teste é criado sob o Engajamento especificado, e os resultados da varredura são anexados a esse Teste. + +Se um ID de `test` for fornecido em vez disso, os resultados da varredura serão adicionados a um Teste existente, o que é comum em fluxos de trabalho de reimportação. + +### Editar Testes + +Os Testes podem ser editados clicando em **Editar Teste** no menu kebab ⋮ na tabela de Testes dentro da visualização do Engajamento pai, ou no menu de configurações dentro da visualização do Teste. Todos os campos subsequentes que podem ser editados também estão disponíveis quando o Teste está sendo criado. + +![image](images/tests_ss24.png) + +![image](images/tests_ss12.png) + +#### Adicionar Achados Manualmente a um Teste + +Um Achado pode ser adicionado manualmente a um Teste clicando em **Adicionar Achado ao Teste** no menu kebab ⋮ ao lado do Teste na visualização do Engajamento pai, ou nas configurações da tabela de Achados na visualização do Teste. + +![image](images/tests_ss29.png) + +![image](images/tests_ss30.png) + +### Excluir Testes + +A exclusão de um Teste pode ser realizada selecionando **Excluir Teste** no menu kebab ⋮ ao lado do Teste na visualização do Engajamento pai, ou no menu de configurações dentro da visualização do Teste. Essa ação não pode ser desfeita. + +A exclusão de um Teste também excluirá quaisquer Achados contidos nesse Teste. + +![image](images/tests_ss25.png) + +![image](images/tests_ss26.png) + +## Reimportação + +A reimportação de varreduras dentro de Testes é fundamental para uma deduplicação eficaz. Quando os resultados de uma varredura são reimportados no mesmo Teste: + +- Os Achados existentes podem ser atualizados +- Achados duplicados podem ser suprimidos +- Novos Achados podem ser criados se nenhuma correspondência for encontrada + +Esse comportamento depende das regras de deduplicação configuradas e do tipo de varredura. + +Criar um novo Teste em vez de reimportar em um já existente pode resultar na criação de Achados duplicados em vez de atualizados. + +#### Reimportação vs. Importação + +A Reimportação é normalmente usada quando: + +- Você executa varreduras recorrentes contra o mesmo alvo +- Você rastreia como os Achados evoluem ao longo do tempo +- Você mantém uma visão contínua da postura de segurança da aplicação + +Em contraste, a importação (criação de um novo Teste) é mais adequada para execuções de varredura únicas ou independentes. + +### Reimportando Resultados de Varredura (Interface) + +Para adicionar novos dados a um Teste existente, você pode clicar em **Reenviar Resultados de Varredura** no menu kebab ⋮ ao lado do Teste na visualização do Engajamento pai, ou clicar em **Reenviar Varredura** no menu de configurações dentro da visualização do Teste. + +![image](images/tests_ss27.png) + +![image](images/tests_ss10.png) + +Ao preencher o formulário de Reimportar Varredura, você terá a opção de atualizar os metadados da varredura sendo reimportada, incluindo a versão, a tag de branch, o hash de commit e o ID de build. + +Essas alterações são refletidas na seção Histórico de Importação da Visualização do Teste, que também incluirá os mesmos metadados das importações de varredura anteriores. + +Por exemplo, na captura de tela abaixo, a tag de branch, o ID de build, o hash de commit e a versão foram todos atualizados manualmente entre a importação inicial e a reimportação subsequente. + +![image](images/tests_ss28.png) + +Para editar os metadados da varredura reimportada mais recentemente, siga as instruções anteriores na seção Editar Testes acima e atualize os metadados conforme desejado. Somente os metadados da importação mais recente podem ser editados. + +### Reimportando Resultados de Varredura (API) + +Quando os Testes são criados ou atualizados por meio de um pipeline de CI/CD, você pode incluir metadados da execução do pipeline para que os Testes sejam corretamente vinculados ao código que varreram. Isso permite que você: +- Associe os resultados da varredura a um commit ou branch específico. +- Rastreie como os Achados evoluem entre as alterações de código. +- Melhore a Deduplicação, entendendo quando duas varreduras se aplicam à mesma versão do código ou a versões diferentes. +- Ofereça suporte à auditabilidade, mostrando exatamente qual código foi varrido e quando. + +A API do DefectDojo aceita esses valores durante a importação ou reimportação, para que possam ser armazenados como parte da importação da varredura e refletidos no histórico de importação do Teste. Esses metadados podem ser usados para identificar hashes de commit ou qualquer informação de repositório relevante associada a uma execução de CI/CD. + +#### Campos de Metadados Suportados + +A API suporta um conjunto definido de campos de metadados que podem ser incluídos durante a reimportação. Estes incluem: + +- `tags` +- `version` +- `build_id` +- `branch_tag` +- `commit_hash` +- `scan_date` +- `minimum_severity` +- sinalizadores `active / verified` + +Esses campos representam o principal mecanismo para anexar metadados contextuais durante uma operação de reimportação. + +Em pipelines automatizados, os metadados mais comumente fornecidos incluem: +- build_id (identificador do job de CI) +- commit_hash (referência de controle de versão) +- branch_tag (contexto de branch ou ambiente) +- tags (por exemplo, nightly, staging, production) + +Esses campos fornecem rastreabilidade entre varreduras sem exigir intervenção manual. + +Embora os metadados possam ser atualizados manualmente por meio do formulário Reimportar Varredura, a maioria dos ambientes automatizados trata isso chamando diretamente o endpoint `/api/v2/reimport-scan/`. Essa abordagem permite que o pipeline anexe automaticamente os metadados na reimportação. + +##### Reimportação via API com Metadados + +curl -X POST `"https:///api/v2/reimport-scan/"` \ + -H `"Authorization: Token "` \ + -F `"test=123"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` \ + -F `"tags=nightly,api-scan"` \ + -F `"version=1.4.2"` \ + -F `"build_id=jenkins-842"` \ + -F `"branch_tag=main"` \ + -F `"commit_hash=a1b2c3d4"` + +##### Metadados, Reimportação e Varreduras Agendadas + +As varreduras também podem ser agendadas para serem executadas em intervalos rotineiros, como as acionadas por cron jobs. As varreduras agendadas não estão vinculadas à atividade do repositório, tornando metadados como hashes de commit ou nomes de branch irrelevantes, a menos que sejam explicitamente injetados pelo próprio script. Ainda assim, usar a reimportação pode ser útil se você preferir manter um registro contínuo da sua postura de segurança dentro de um único Teste. diff --git a/docs/content/asset_modelling/engagements_tests/OS__tests.zh-hans.md b/docs/content/asset_modelling/engagements_tests/OS__tests.zh-hans.md new file mode 100644 index 0000000000..595ba29b66 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__tests.zh-hans.md @@ -0,0 +1,274 @@ +--- +title: 测试 +description: 了解 DefectDojo OS 中的测试 +audience: opensource +weight: 4 +--- + +组织 → 资产 → 测试活动 → **测试** → 发现项 + +## 概述 + +测试是一个或多个扫描执行的容器，用于发现产品中的缺陷。测试是 DefectDojo 产品层级结构中最末端、最细粒度的组成部分，作为安全工具执行或人工评估所产生的发现项的容器，同时还添加了发现这些发现项所处的上下文（即报告该发现项的工具、该工具上次运行的时间等）。 + +测试的示例包括： +- 静态应用程序安全测试 +- 动态应用程序安全测试 +- 软件成分分析 +- 容器安全扫描 +- 基础设施/网络扫描 +- 人工渗透测试 +- CI/CD 流水线扫描 + +### 测试类型 + +在 DefectDojo 中创建测试主要有两种方式： +1. **特定厂商解析器**（例如 Burp、OWASP ZAP、Acunetix、Invicti） +2. **通用发现项导入** + +根据配置和去重策略的不同，每种方法都可以创建新测试，或将发现项重新导入到现有测试中。 + +虽然这两种方法的主要区别在于扫描数据的解析和接收方式，但它们最终都会使发现项与某个测试相关联。 + +#### 解析器 + +**解析器**是处理特定扫描输出格式（例如 XML、JSON、CSV）并将其映射到 DefectDojo 内部发现项模型的组件。导入扫描结果时，DefectDojo 会使用所选的解析器提取发现项，并将其附加到新创建的测试或现有测试中。 + +#### 通用发现项导入 + +当某个工具没有原生解析器时，**通用发现项导入**允许您使用标准化的 JSON 或 CSV 模式导入发现项，而无需考虑原始数据来源。 + +DefectDojo 会解析所提供的数据，创建一个新测试（或将数据导入到现有测试中），并附加发现项。系统还会根据报告中可选的 `type` 字段创建相应的测试类型：当省略 `type`（或其值等于扫描类型）时，测试类型为 “Generic Findings Import”；当提供了 `type` 时，测试类型将变为 “{type} Scan (Generic Findings Import)”（如果 `type` 本身已经以 “(Generic Findings Import)” 结尾，则按原样使用）。 + +| | **原生解析器** | **通用发现项导入** | +|----------|---------------|------------------------| +| **主要用途** | 接收受支持工具的输出 | 通过固定模式接收不受支持的/自定义数据 | +| **输入格式** | 特定于工具（例如 ZAP XML、SARIF） | 严格的 JSON/CSV 模式 | +| **由谁处理规范化** | DefectDojo（内置解析器） | 用户（必须符合模式规范） | +| **测试创建触发方式** | 手动上传或 API 导入 | 手动上传或 API 导入 | +| **测试类型** | 预定义（例如 “ZAP Scan”） | 自动创建的 “Generic” 类型 | +| **配置成本** | 低 | 中（需要进行数据转换） | +| **灵活性** | 低（仅限受支持的工具） | 中 | +| **自动化程度** | 低至中 | 低至中 | +| **典型使用场景** | 标准扫描器（SAST、DAST、SCA） | 自定义脚本、不受支持的工具 | + +无论采用哪种接收方式，DefectDojo 中的所有扫描数据最终都会以附加到某个测试上的发现项形式呈现，该测试则作为执行单元和生命周期跟踪的单位。 + +### 测试数据 + +测试会存储各种元数据，以帮助记录每次测试工作的各个组成部分，例如： +- 测试标题/名称 +- 测试类型 +- 测试描述/备注 +- 开始和结束日期 +- 运行测试的环境（例如开发、预发布、准生产、生产等） +- 版本/分支/构建 ID/提交哈希值 +- API 扫描配置 +- 可用于后续审计或重新导入的其他文件 +- 上级测试活动、资产和组织 +- 导入和重新导入的历史记录 + +每个测试都会维护一份导入历史记录，用于记录与该测试相关的所有扫描导入和重新导入操作，其中包括扫描日期、版本、分支、提交哈希值和构建 ID 等元数据。 + +这份历史记录为同一测试内的多次扫描执行提供了可追溯性。 + +### 权限 + +单个测试活动内可以存储多个测试，而测试活动则存储在产品内。因此，对某个产品的访问权限会自动授予对该产品内所有测试（及测试活动）的访问权限。测试没有独立的访问控制列表。 + +### 访问测试 + +尽管测试在 DefectDojo OS 中作为独立对象存在，但界面中并没有专门用于展示测试的特定区域。因此，每个测试主要通过包含它的产品和/或测试活动来访问。 + +### 测试视图 + +测试视图承载了多种表格，包括上级测试活动、导入和重新导入历史记录、测试内包含的发现项列表以及任何发现项分组。 + +此外还有潜在发现项、文件和备注的表格，这些都可以手动添加。 + +#### 测试设置 + +每个测试视图中都提供以下设置： +- **编辑测试** + - 允许编辑测试数据，例如标题、计划安排、环境以及其他各种详细信息。 +- **复制测试** + - 复制某个测试及其所有相关元数据和发现项，并允许将其归属到不同的测试活动。 +- **重新上传扫描** + - 启动重新导入流程。有关重新导入的更多信息，请参阅本文后面的内容。 +- **添加备注** + - 允许用户添加备注。页面底部还有一个备注表格。 + - 备注可以切换为私密状态，此时该备注不会被推送到 Jira、报告以及发现项的导出内容中。 +- **报告** + - 启动生成报告的流程，您可以在其中应用多种筛选条件，从而仅针对筛选后的发现项生成报告。 +- **添加到日历** + - 下载所选测试的 .ics 文件，该文件可添加到您的第三方日历应用程序中。 +- **查看历史记录** + - 打开对该测试所做编辑的历史记录，用于跟踪、报告和审计目的。 + +## 使用测试 + +### 创建测试 + +当扫描数据被直接导入到某个测试活动中时，系统会自动创建测试，从而生成一个包含该扫描数据的新测试。测试也可以为规划未来的测试活动而预先创建，或用于需要跟踪和修复的手动录入安全发现项。 + +#### 手动工作流 + +在 OS 版本中，有多种方式可以创建测试： + +- 选择一个产品，然后在导航栏的“发现项”菜单中点击“导入扫描结果” + - 这将创建一个临时测试活动来包含该测试 + +![image](images/tests_ss5.png) + +- 在产品内选择一个测试活动，点击“测试”子区域中的下拉菜单，然后点击“添加测试”或“导入扫描结果” + - 这将直接在所选的测试活动内创建随之产生的测试 + +![image](images/tests_ss6.png) + +- 在创建测试活动的过程中 + +![image](images/tests_ss7.png) + +使用上述第三种方法，您可以在创建测试活动的同时执行以下操作： + +- 立即导入扫描结果 +- 创建测试外壳（稍后可向其中导入扫描数据） +- 两者都不做，只需点击“完成”来创建测试活动 + +无论是导入扫描数据还是创建测试外壳，您都可以借此机会添加元数据。任何元数据都会反映在测试视图的导入历史记录部分中。 + +#### 自动化工作流 + +在自动化工作流中，测试可以作为扫描导入流程的一部分以编程方式创建，使流水线能够上传结果，而无需事先手动创建测试。 + +使用 API 导入扫描结果时，通过提供 engagement（而非 test）参数，系统可以自动创建一个新测试。 + +##### API + +curl -X POST `"https:///api/v2/import-scan/"` \ + -H `"Authorization: Token "` \ + -F `"engagement=45"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` + +如上所示，系统会在指定的测试活动下创建一个新测试，并将扫描结果附加到该测试中。 + +如果改为提供 `test` ID，则扫描结果将被添加到现有测试中，这在重新导入工作流中很常见。 + +### 编辑测试 + +要编辑测试，可以在上级测试活动视图中的测试表格里点击 ⋮ 竖排菜单中的**编辑测试**，也可以在测试视图内的设置菜单中进行编辑。随后可编辑的所有字段，在创建测试时也同样可用。 + +![image](images/tests_ss24.png) + +![image](images/tests_ss12.png) + +#### 手动向测试添加发现项 + +要将发现项手动添加到测试，可以在上级测试活动视图中，点击测试旁边 ⋮ 竖排菜单中的**将发现项添加到测试**，也可以在测试视图内发现项表格的设置中进行添加。 + +![image](images/tests_ss29.png) + +![image](images/tests_ss30.png) + +### 删除测试 + +要删除测试，可以在上级测试活动视图中，从测试旁边的 ⋮ 竖排菜单中选择**删除测试**，也可以在测试视图内的设置菜单中进行删除。此操作无法撤销。 + +删除测试还会删除该测试内包含的所有发现项。 + +![image](images/tests_ss25.png) + +![image](images/tests_ss26.png) + +## 重新导入 + +在测试内重新导入扫描是实现有效去重的基础。当扫描结果被重新导入到同一测试中时： + +- 现有发现项可能会被更新 +- 重复的发现项可能会被抑制 +- 如果未找到匹配项，则可能会创建新的发现项 + +这一行为取决于所配置的去重规则和扫描类型。 + +创建新测试而非重新导入到现有测试中，可能会导致创建重复的发现项，而不是对其进行更新。 + +#### 重新导入与导入的比较 + +重新导入通常适用于以下情况： + +- 针对同一目标运行周期性扫描 +- 跟踪发现项随时间的变化情况 +- 持续掌握应用程序的安全态势 + +相比之下，导入（创建新测试）更适用于一次性或独立的扫描执行。 + +### 重新导入扫描结果（界面操作） + +要向现有测试添加新数据，可以在上级测试活动视图中，点击测试旁边 ⋮ 竖排菜单中的**重新上传扫描结果**，也可以在测试视图内的设置菜单中点击**重新上传扫描**。 + +![image](images/tests_ss27.png) + +![image](images/tests_ss10.png) + +在填写“重新导入扫描”表单时，您可以选择更新正在重新导入的扫描的元数据，包括版本、分支标签、提交哈希值和构建 ID。 + +这些更改会反映在测试视图的导入历史记录部分中，该部分还会包含之前扫描导入的相同元数据。 + +例如，在下面的屏幕截图中，分支标签、构建 ID、提交哈希值和版本均在首次导入与后续重新导入之间被手动更新。 + +![image](images/tests_ss28.png) + +要编辑最近一次重新导入扫描的元数据，请按照上文“编辑测试”部分中的说明进行操作，并根据需要更新元数据。只有最近一次导入的元数据可以编辑。 + +### 重新导入扫描结果（API） + +当测试通过 CI/CD 流水线创建或更新时，您可以纳入来自该流水线运行的元数据，以便将测试正确关联到其所扫描的代码。这使您能够： +- 将扫描结果与特定的提交或分支相关联。 +- 跟踪发现项随代码变更的演变情况。 +- 通过了解两次扫描是否适用于相同或不同版本的代码，来改进去重效果。 +- 通过准确显示所扫描的代码内容及扫描时间，来支持可审计性。 + +DefectDojo 的 API 在导入或重新导入期间接受这些值，以便将其作为扫描导入的一部分进行存储，并反映在测试的导入历史记录中。此元数据可用于识别提交哈希值，或与 CI/CD 运行相关的任何相关代码仓库信息。 + +#### 支持的元数据字段 + +API 支持一组明确定义的元数据字段，这些字段可以在重新导入期间包含。其中包括： + +- `tags` +- `version` +- `build_id` +- `branch_tag` +- `commit_hash` +- `scan_date` +- `minimum_severity` +- `active / verified` 标志 + +这些字段是在重新导入操作期间附加上下文元数据的主要机制。 + +在自动化流水线中，最常提供的元数据包括： +- build_id（CI 作业标识符） +- commit_hash（源代码控制引用） +- branch_tag（分支或环境上下文） +- tags（例如 nightly、staging、production） + +这些字段无需人工干预即可在各次扫描之间提供可追溯性。 + +尽管可以通过“重新导入扫描”表单手动更新元数据，但大多数自动化环境会通过直接调用 `/api/v2/reimport-scan/` 端点来处理此事。这种方式使流水线能够在重新导入时自动附加元数据。 + +##### 使用元数据进行 API 重新导入 + +curl -X POST `"https:///api/v2/reimport-scan/"` \ + -H `"Authorization: Token "` \ + -F `"test=123"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` \ + -F `"tags=nightly,api-scan"` \ + -F `"version=1.4.2"` \ + -F `"build_id=jenkins-842"` \ + -F `"branch_tag=main"` \ + -F `"commit_hash=a1b2c3d4"` + +##### 元数据、重新导入与计划扫描 + +扫描也可以设置为按固定周期运行，例如由 cron 作业触发的扫描。计划扫描与代码仓库活动无关，因此提交哈希值或分支名称等元数据除非由脚本本身显式注入，否则并不适用。尽管如此，如果您希望在单个测试内保留安全态势的滚动记录，使用重新导入仍然会很有帮助。 diff --git a/docs/content/asset_modelling/engagements_tests/PRO__assets.it.md b/docs/content/asset_modelling/engagements_tests/PRO__assets.it.md new file mode 100644 index 0000000000..aebdc02326 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__assets.it.md @@ -0,0 +1,186 @@ +--- +title: Asset +description: Comprendere gli Asset in DefectDojo Pro +audience: pro +weight: 2 +--- + +Organizzazioni → **ASSET** → Engagement → Test → Riscontri + +## Panoramica + +Gli **Asset** sono al centro del modo in cui il lavoro di sicurezza è organizzato all'interno della gerarchia degli oggetti di DefectDojo. Gli Asset rappresentano qualsiasi progetto, programma, software o bene fisico che il vostro team di sicurezza sta testando, e ospitano tutto il lavoro di sicurezza e la cronologia dei test relativi all'obiettivo del test. Esempi di Asset possono includere: +- Release software +- Software di terze parti +- Macchine virtuali o asset in produzione +- Una singola applicazione +- Un microservizio +- Un'API +- Una piattaforma SaaS +- Un'app mobile +- Un sistema interno +- Un servizio aziendale +- Una piattaforma rivolta ai clienti +- Un ambiente cloud o dominio infrastrutturale + +In generale, un Asset dovrebbe rappresentare la “cosa” di cui volete monitorare la postura di sicurezza nel tempo. Ciò include la cronologia dei test associata, i Riscontri, le metriche, la proprietà, le integrazioni e i workflow di remediation relativi a quella “cosa”. + +### Esempi di Asset + +Gli Asset possono diventare ancora più granulari a seconda delle esigenze della vostra organizzazione. Ad esempio, potreste valutare di creare Asset DefectDojo separati nei seguenti scenari: + +- “ExampleAsset” ha una versione Windows, una versione Mac e una versione Cloud +- “ExampleAsset 1.0” utilizza componenti software completamente diversi da “ExampleAsset 2.0”, ed entrambe le versioni sono attivamente supportate dalla vostra azienda. +- Il team assegnato a lavorare su “ExampleAsset versione A” è diverso dal team Asset assegnato a lavorare su “ExampleAsset versione B”, e di conseguenza necessita di permessi di sicurezza diversi. + +Sebbene possiate anche scegliere di rappresentare queste varianti come Engagement all'interno di un singolo Asset, l'RBAC può essere impostato solo a livello di Asset o Organizzazioni, il che potrebbe limitare l'accesso degli utenti all'Engagement appropriato (nonché ai Test e ai Riscontri all'interno di tali Engagement) se organizzati in questo modo. Per maggiori informazioni su RBAC e permessi in DefectDojo, fate clic [qui](/admin/user_management/about_perms_and_roles/). + +## Dati dell'Asset + +Gli Asset includeranno sempre i seguenti componenti: + +- **Organizzazione** +- **Nome univoco** +- **Descrizione** +- **Configurazione SLA** +- **Motore di prioritizzazione** + +I metadati opzionali dell'Asset includono: + +- **Tag** +- **Criticità aziendale** +- **Record utente** (ossia il numero stimato di record utente nell'Asset) +- **Fatturato** +- **Informazioni sul personale** (ad es. Asset Manager, Team Manager, Contatto Tecnico, ecc.) +- **Normative** (ad es. HIPAA, GLBA, OPPA, ecc.) +- **Piattaforma** (ad es. API, Desktop, IoT, Mobile, Web, ecc.) +- **Ciclo di vita** (ad es. Costruzione, Produzione, Dismissione, ecc.) +- **Origine** (ad es. Libreria di terze parti, Acquistato, Open Source, ecc.) + +Questi metadati migliorano il filtraggio, il reporting e la prioritizzazione in tutto il vostro programma di sicurezza, ma soprattutto, gli Asset contengono anche tutti gli Engagement, i Test e i Riscontri relativi agli sforzi di test riguardanti quell'Asset. Tutti i Riscontri provenienti dai Test confluiscono infine a livello di Asset, consentendo il tracciamento a lungo termine, l'analisi delle tendenze e il reporting. + +## Accesso agli Asset + +Gli Asset sono accessibili tramite la barra laterale. Il sottomenu offre l'accesso alla [Gerarchia degli Asset](/asset_modelling/engagements_tests/pro__assets/#asset-nesting) e a All Assets, oltre all'opzione per creare un nuovo Asset. + +![image](images/assets_ss1.png) + +### Permessi + +Agli Asset è possibile applicare regole di Role-Based Access Control (RBAC), che limitano la capacità dei membri del team di visualizzarli e interagire con essi. + +I permessi si propagano verso il basso, il che significa che l'accesso a un Asset concede automaticamente l'accesso a tutti gli oggetti al suo interno (ad es. Engagement, Test e Riscontri). + +Per maggiori informazioni sui ruoli utente, consultate il nostro articolo [Introduzione ai ruoli](/admin/user_management/set_user_permissions/#introduction-to-permission-types). + +## Vista Asset + +Le viste Asset contengono diverse tabelle e grafici per interpretare lo stato di un Asset a colpo d'occhio. Questi includono: + +- **Open Finding Severity** + - Un elenco dei Riscontri aperti all'interno dell'Asset, raggruppati per gravità +- **Asset Overview** + - Una panoramica delle varie caratteristiche dell'Asset, tra cui Descrizione, Componenti, Contatti, [Gruppi Utenti](/admin/user_management/create_user_group/ +), Membri, Tecnologie e Normative. + - Tecnologie: next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo +- **Metadata** + - Inclusi Asset padre e figli, Organizzazione, criticità aziendale, fatturato e altri dettagli aggiunti dalle impostazioni dell'Asset. +- **Service Level Agreement by Severity** + - Applica la configurazione SLA dell'Asset dalle impostazioni ai Riscontri all'interno dell'Asset. +- **Finding Severity Breakdown** + - Un grafico dei Riscontri all'interno dell'Asset, organizzati per gravità. +- **Finding Distribution** + - Una ripartizione dei Riscontri all'interno dell'Asset, organizzati per stato (ad es. Active, Mitigated, Static e Dynamic) +- **All Engagements** + - Un elenco degli Engagement contenuti nell'Asset. + +## Lavorare con gli Asset + +### Creare Asset + +Esistono due modi per creare Asset: + +- Dall'opzione **New Asset** nel menu laterale +- Dal pulsante **New Asset** in cima all'elenco All Assets + +## Modificare gli Asset + +Gli Asset possono essere modificati facendo clic su **Edit Asset** dal menu a ingranaggio in alto a destra della vista dell'Asset. Lo stesso menu è accessibile anche facendo clic sul menu kebab ⋮ a sinistra dell'Asset nella vista All Assets. + +Tutti i campi modificabili di seguito sono disponibili anche durante la creazione dell'Asset. + +![image](images/assets_ss2.png) + +### Eliminare gli Asset + +È possibile eliminare un Asset selezionando **Delete Asset** dalle impostazioni dell'Asset. Questa azione non può essere annullata. Gli Asset non possono essere chiusi e riaperti in seguito. + +L'eliminazione di un Asset comporta anche l'eliminazione di quanto segue: +- Qualsiasi Engagement e Test contenuto nell'Asset +- Tutta la cronologia di sicurezza associata, inclusi Riscontri e integrazioni +- Eventuali Epic Jira collegate +- Tutte le note e i file caricati associati agli Engagement e ai Test dell'Asset + +## Confini dell'Asset + +### Deduplicazione + +Gli Asset sono “isolati” e non interagiscono con altri Asset. Le Smart Features di DefectDojo, come la Deduplicazione, si applicano solo nel contesto di un singolo Asset. I Riscontri tra Asset diversi non verranno deduplicati automaticamente. + +### Reporting e metriche + +La maggior parte del reporting e delle metriche aggrega i dati a livello di Asset, rendendo gli Asset l'unità principale per misurare e monitorare il rischio. + +Di conseguenza, molte metriche chiave vengono calcolate per Asset, tra cui: + +- Numero totale di Riscontri (per gravità o stato) +- Tempo medio di remediation (MTTR) +- Tassi di conformità e violazione degli SLA +- Tendenze del rischio nel tempo + +Ciò significa che il modo in cui gli Asset sono strutturati influenzerà direttamente l'accuratezza e l'utilità dei report. Ad esempio, raggruppare più sistemi non correlati sotto un unico Asset può oscurare la visibilità del rischio, mentre strutture di Asset eccessivamente granulari possono frammentare il reporting, rendendo difficile individuare tendenze più ampie. + +### Connettori + +In DefectDojo Pro, i Connettori vengono mappati su Asset diversi, rendendoli il punto di integrazione principale tra DefectDojo e il vostro ecosistema di sicurezza più ampio. + +Una volta collegato a un Asset, un Connettore importerà i risultati delle scansioni e creerà o aggiornerà Engagement, Test e Riscontri all'interno di quell'Asset. + +Per maggiori informazioni sui Connettori, fate clic [qui](/connectors/upstream/about/#main-content). + +### Pipeline CI/CD + +Le pipeline CI/CD automatizzano l'importazione dei risultati delle scansioni. Indipendentemente dal metodo di integrazione, tutte le importazioni di scansioni devono essere associate a un Asset, rendendo l'Asset il punto di ancoraggio per i dati di sicurezza generati dalla pipeline. + +Quando una pipeline invia i risultati di una scansione, deve: + +- Specificare un Asset esistente (ed eventualmente un Engagement), oppure +- Essere configurata in modo da mappare in modo coerente i risultati sull'Asset corretto + +Tutti i Riscontri importati erediteranno il contesto dell'Asset, inclusi proprietà, permessi, configurazione di priorità/rischio e ambito di reporting. + +In pratica, gli Asset dovrebbero essere definiti in modo da riflettere come i sistemi vengono costruiti e distribuiti all'interno del CI/CD, per garantire che i risultati di sicurezza siano costantemente associati all'applicazione o al servizio corretto. + +### SLA, Priorità e Rischio + +In DefectDojo Pro, i Riscontri ereditano i propri obiettivi SLA, la Priorità e il Rischio dall'Asset che li contiene. I metadati dell'Asset (ad es. criticità aziendale, fatturato, ecc.) vengono utilizzati per calcolare automaticamente i valori di Priorità e Rischio. + +Ciò significa che la stessa vulnerabilità può ricevere un punteggio di Priorità o Rischio diverso a seconda che riguardi un sistema di sviluppo interno o un asset di produzione a supporto di operazioni aziendali critiche. + +### Relazioni con Jira / Connettori Downstream + +Gli Asset possono essere mappati direttamente su istanze [Jira](/connectors/downstream/pro__jira_guide/#main-content) o [Integrators](/connectors/downstream/downstream_toolreference/#main-content) (ad es. GitHub, GitLab, ServiceNow, ecc.), che inviano i Riscontri dell'Asset verso l'esterno, in sistemi esterni di ticketing/gestione del lavoro. + +Poiché i Riscontri ereditano rischio, priorità e proprietà dal loro Asset principale, l'Asset determina di fatto il contesto di remediation che confluisce nei ticket Jira e nei workflow dei Connettori Downstream. + +È importante notare che gli Asset sono anche il fattore determinante principale per le caratteristiche SLA di un Riscontro. Pertanto, lo SLA di un Riscontro dipende dalla configurazione SLA del suo Asset principale. Maggiori informazioni sulle configurazioni SLA sono disponibili [qui](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas). + +## Nidificazione degli Asset + +DefectDojo supporta relazioni padre-figlio tra due Asset all'interno della stessa Organizzazione. Questa relazione può essere configurata durante la creazione dell'Asset o nelle impostazioni dell'Asset. + +Potete visualizzare la struttura degli Asset in DefectDojo e modificare le relazioni utilizzando l'opzione **Asset Hierarchy** nella barra laterale. + +Dopo aver selezionato dalla tabella corrispondente gli Asset da visualizzare, fate clic su **View Asset Hierarchy** per generare un diagramma di flusso della relazione tra gli Asset scelti, se presente. + +Ulteriori informazioni sull'effetto della nidificazione degli Asset sulla deduplicazione, sull'RBAC e su altri dettagli, oltre a esempi di casi d'uso, sono disponibili [qui](/asset_modelling/pro_hierarchy/asset_hierarchy/#asset-nesting-examples). diff --git a/docs/content/asset_modelling/engagements_tests/PRO__assets.pt-br.md b/docs/content/asset_modelling/engagements_tests/PRO__assets.pt-br.md new file mode 100644 index 0000000000..18e2d8c380 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__assets.pt-br.md @@ -0,0 +1,186 @@ +--- +title: Ativos +description: Entendendo os Ativos no DefectDojo Pro +audience: pro +weight: 2 +--- + +Organizações → **ATIVOS** → Engajamentos → Testes → Achados + +## Visão geral + +**Ativos** estão no centro de como o trabalho de segurança é organizado dentro da hierarquia de objetos do DefectDojo. Os Ativos representam qualquer projeto, programa, software ou ativo físico que sua equipe de segurança esteja testando, e hospedam todo o trabalho de segurança e o histórico de testes relacionados ao objetivo do teste. Exemplos de Ativos podem incluir: +- Versões de software +- Software de terceiros +- Máquinas virtuais ou ativos em produção +- Uma única aplicação +- Um microsserviço +- Uma API +- Uma plataforma SaaS +- Um aplicativo móvel +- Um sistema interno +- Um serviço de negócio +- Uma plataforma voltada para o cliente +- Um ambiente de nuvem ou domínio de infraestrutura + +Em geral, um Ativo deve representar a "coisa" cuja postura de segurança você deseja acompanhar ao longo do tempo. Isso inclui o histórico de testes associado, os Achados, as métricas, a propriedade, as integrações e os fluxos de trabalho de correção relacionados a essa "coisa". + +### Exemplos de Ativos + +Os Ativos podem se tornar ainda mais granulares, dependendo das necessidades da sua organização. Por exemplo, você pode considerar criar Ativos separados no DefectDojo nos seguintes cenários: + +- "AtivoExemplo" tem uma versão para Windows, uma versão para Mac e uma versão para Nuvem +- "AtivoExemplo 1.0" usa componentes de software completamente diferentes de "AtivoExemplo 2.0", e ambas as versões são ativamente suportadas pela sua empresa. +- A equipe designada para trabalhar na "versão A do AtivoExemplo" é diferente da equipe de Ativo designada para trabalhar na "versão B do AtivoExemplo", e, como resultado, precisa ter permissões de segurança diferentes atribuídas. + +Embora você também possa optar por representar essas variações como Engajamentos dentro de um único Ativo, o RBAC só pode ser definido no nível de Ativos ou Organizações, o que pode limitar o acesso dos usuários ao Engajamento apropriado (bem como aos Testes e Achados dentro desses Engajamentos) caso estejam organizados dessa forma. Para mais informações sobre RBAC e permissões no DefectDojo, clique [aqui](/admin/user_management/about_perms_and_roles/). + +## Dados do Ativo + +Os Ativos sempre incluirão os seguintes componentes: + +- **Organização** +- **Nome exclusivo** +- **Descrição** +- **Configuração de SLA** +- **Motor de Priorização** + +Os metadados opcionais do Ativo incluem: + +- **Tags** +- **Criticidade de negócio** +- **Registros de usuários** (ou seja, o número estimado de registros de usuários no Ativo) +- **Receita** +- **Informações de pessoal** (por exemplo, Gerente do Ativo, Gerente da Equipe, Contato Técnico, etc.) +- **Regulamentações** (por exemplo, HIPAA, GLBA, OPPA, etc.) +- **Plataforma** (por exemplo, API, Desktop, IoT, Mobile, Web, etc.) +- **Ciclo de vida** (por exemplo, Construção, Produção, Desativação, etc.) +- **Origem** (por exemplo, Biblioteca de Terceiros, Adquirido, Código Aberto, etc.) + +Esses metadados melhoram a filtragem, os relatórios e a priorização em todo o seu programa de segurança, mas o mais importante é que os Ativos também contêm todos os Engajamentos, Testes e Achados relacionados aos esforços de teste em torno desse Ativo. Todos os Achados dos Testes, em última instância, são consolidados no nível do Ativo, permitindo o acompanhamento de longo prazo, a análise de tendências e a geração de relatórios. + +## Acessando Ativos + +Os Ativos são acessíveis pela barra lateral. O submenu oferece acesso à [Hierarquia de Ativos](/asset_modelling/engagements_tests/pro__assets/#asset-nesting) e a Todos os Ativos, além da opção de criar um novo Ativo. + +![image](images/assets_ss1.png) + +### Permissões + +Os Ativos podem ter regras de Controle de Acesso Baseado em Função (RBAC) aplicadas, que limitam a capacidade dos membros da equipe de visualizá-los e interagir com eles. + +As permissões são propagadas para baixo, o que significa que o acesso a um Ativo concede automaticamente acesso a todos os objetos dentro desse Ativo (por exemplo, Engajamentos, Testes e Achados). + +Para mais informações sobre funções de usuário, consulte nosso artigo [Introdução às Funções](/admin/user_management/set_user_permissions/#introduction-to-permission-types). + +## Visualização do Ativo + +As visualizações de Ativo contêm uma variedade de tabelas e gráficos para interpretar o status de um Ativo rapidamente. Isso inclui: + +- **Severidade dos Achados Abertos** + - Uma lista dos Achados abertos dentro do Ativo, agrupados por severidade +- **Visão Geral do Ativo** + - Um detalhamento de vários recursos do Ativo, incluindo Descrição, Componentes, Contatos, [Grupos de Usuários](/admin/user_management/create_user_group/ +), Membros, Tecnologias e Regulamentações. + - Tecnologias: next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo +- **Metadados** + - Incluindo Ativos pais e filhos, Organização, criticidade de negócio, receita e outros detalhes adicionados nas configurações do Ativo. +- **Acordo de Nível de Serviço por Severidade** + - Aplica a configuração de SLA do Ativo, definida nas configurações, aos Achados dentro do Ativo. +- **Detalhamento de Severidade dos Achados** + - Um gráfico dos Achados dentro do Ativo, organizados por severidade. +- **Distribuição de Achados** + - Um detalhamento dos Achados dentro do Ativo, organizados por status (por exemplo, Ativo, Mitigado, Estático e Dinâmico) +- **Todos os Engajamentos** + - Uma lista dos Engajamentos contidos no Ativo. + +## Trabalhando com Ativos + +### Criar Ativos + +Existem duas maneiras de criar Ativos: + +- Na opção **Novo Ativo** no menu lateral +- No botão **Novo Ativo** no topo da lista Todos os Ativos + +## Editar Ativos + +Os Ativos podem ser editados clicando em **Editar Ativo** no menu de engrenagem no canto superior direito da visualização do Ativo. O mesmo menu também pode ser acessado clicando no menu kebab ⋮ à esquerda do Ativo na visualização Todos os Ativos. + +Todos os campos subsequentes que podem ser editados também estão disponíveis quando o Ativo está sendo criado. + +![image](images/assets_ss2.png) + +### Excluir Ativos + +A exclusão de um Ativo pode ser realizada selecionando **Excluir Ativo** nas configurações do Ativo. Essa ação não pode ser desfeita. Os Ativos não podem ser fechados e reabertos posteriormente. + +A exclusão de um Ativo também excluirá o seguinte: +- Quaisquer Engajamentos e Testes contidos no Ativo +- Todo o histórico de segurança associado, incluindo Achados e integrações +- Quaisquer Epics do Jira vinculados +- Todas as notas e uploads de arquivos associados aos Engajamentos e Testes do Ativo + +## Limites do Ativo + +### Deduplicação + +Os Ativos são "isolados" e não interagem com outros Ativos. Os Recursos Inteligentes do DefectDojo, como a Deduplicação, aplicam-se apenas no contexto de um único Ativo. Os Achados de diferentes Ativos não serão deduplicados automaticamente. + +### Relatórios e Métricas + +A maioria dos relatórios e métricas agrega dados no nível do Ativo, tornando os Ativos a unidade principal para medir e acompanhar o risco. + +Como resultado, muitas métricas importantes são calculadas por Ativo, incluindo: + +- Número total de Achados (por severidade ou status) +- Tempo médio de correção (MTTR) +- Conformidade e taxas de violação de SLA +- Tendências de risco ao longo do tempo + +Isso significa que a forma como os Ativos são estruturados impactará diretamente a precisão e a utilidade dos relatórios. Por exemplo, agrupar vários sistemas não relacionados em um único Ativo pode obscurecer a visibilidade do risco, enquanto estruturas de Ativo excessivamente granulares podem fragmentar os relatórios, dificultando a identificação de tendências mais amplas. + +### Connectors + +No DefectDojo Pro, os Connectors são mapeados para diferentes Ativos, tornando-os o principal ponto de integração entre o DefectDojo e seu ecossistema de segurança mais amplo. + +Depois que um Connector é anexado a um Ativo, ele importará os resultados da varredura e criará ou atualizará Engajamentos, Testes e Achados dentro desse Ativo. + +Para mais informações sobre Connectors, clique [aqui](/connectors/upstream/about/#main-content). + +### Pipelines de CI/CD + +Os pipelines de CI/CD automatizam a importação dos resultados de varredura. Independentemente do método de integração, todas as importações de varredura devem estar associadas a um Ativo, tornando o Ativo o ponto de ancoragem para os dados de segurança orientados por pipeline. + +Quando um pipeline envia resultados de varredura, ele deve: + +- Especificar um Ativo existente (e, opcionalmente, um Engajamento), ou +- Estar configurado de forma a mapear consistentemente os resultados para o Ativo correto + +Todos os Achados importados herdarão o contexto do Ativo, incluindo propriedade, permissões, configuração de prioridade/risco e escopo de relatórios. + +Na prática, os Ativos devem ser definidos de forma a refletir como os sistemas são construídos e implantados dentro do CI/CD, a fim de garantir que os resultados de segurança sejam consistentemente associados à aplicação ou ao serviço correto. + +### SLAs, Prioridade e Risco + +No DefectDojo Pro, os Achados herdam suas metas de SLA, Prioridade e Risco do Ativo que os contém. Os metadados do Ativo (por exemplo, criticidade de negócio, receita, etc.) são usados para calcular automaticamente os valores de Prioridade e Risco. + +Isso significa que a mesma vulnerabilidade pode receber uma pontuação de Prioridade ou Risco diferente, dependendo se ela afeta um sistema de desenvolvimento interno ou um ativo de produção que suporta operações de negócio críticas. + +### Relacionamentos com Jira / Connectors Downstream + +Os Ativos podem ser mapeados diretamente para instâncias do [Jira](/connectors/downstream/pro__jira_guide/#main-content) ou [Integrators](/connectors/downstream/downstream_toolreference/#main-content) (por exemplo, GitHub, GitLab, ServiceNow, etc.), que enviam os Achados do Ativo para fora, rumo a sistemas externos de tickets/gerenciamento de trabalho. + +Como os Achados herdam risco, prioridade e propriedade do Ativo pai, o Ativo efetivamente determina o contexto de correção que flui para os tickets do Jira e para os fluxos de trabalho dos Connectors Downstream. + +É importante destacar que os Ativos também são o principal fator determinante nas características de SLA de um Achado. Portanto, o SLA de um Achado depende da configuração de SLA do seu Ativo pai. Mais informações sobre configurações de SLA podem ser encontradas [aqui](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas). + +## Aninhamento de Ativos + +O DefectDojo oferece suporte a um relacionamento pai-filho entre dois Ativos dentro da mesma Organização. Isso pode ser configurado durante a criação do Ativo ou nas configurações do Ativo. + +Você pode visualizar a estrutura dos Ativos no DefectDojo e alterar relacionamentos usando a opção **Hierarquia de Ativos** na barra lateral. + +Depois de selecionar os Ativos a serem visualizados na tabela correspondente, clique em **Ver Hierarquia de Ativos** para gerar um fluxograma do relacionamento entre os Ativos escolhidos, se houver algum. + +Mais informações sobre o efeito do aninhamento de Ativos na deduplicação, no RBAC e em outros detalhes, bem como exemplos de casos de uso, podem ser encontradas [aqui](/asset_modelling/pro_hierarchy/asset_hierarchy/#asset-nesting-examples). diff --git a/docs/content/asset_modelling/engagements_tests/PRO__assets.zh-hans.md b/docs/content/asset_modelling/engagements_tests/PRO__assets.zh-hans.md new file mode 100644 index 0000000000..f7f99f75a6 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__assets.zh-hans.md @@ -0,0 +1,186 @@ +--- +title: 资产 +description: 了解 DefectDojo Pro 中的资产 +audience: pro +weight: 2 +--- + +组织 → **资产** → 测试活动 → 测试 → 发现项 + +## 概述 + +**资产**是 DefectDojo 对象层级结构中安全工作组织方式的核心。资产代表安全团队正在测试的任何项目、计划、软件或物理资产，并承载与该测试目标相关的所有安全工作和测试历史记录。资产的示例包括： +- 软件发布版本 +- 第三方软件 +- 生产环境中的虚拟机或资产 +- 单个应用程序 +- 微服务 +- API +- SaaS 平台 +- 移动应用 +- 内部系统 +- 业务服务 +- 面向客户的平台 +- 云环境或基础设施域 + +总体而言，资产应代表您希望长期跟踪其安全态势的“对象”，这包括与该“对象”相关的测试历史记录、发现项、指标、归属关系、集成以及修复工作流。 + +### 资产示例 + +根据组织的需求，资产可以变得更加细化。例如，您可以考虑在以下场景中创建单独的 DefectDojo 资产： + +- “示例资产”拥有 Windows 版本、Mac 版本和云版本 +- “示例资产 1.0”使用的软件组件与“示例资产 2.0”完全不同，且贵公司同时积极支持这两个版本。 +- 负责“示例资产版本 A”的团队与负责“示例资产版本 B”的资产团队不同，因此需要分配不同的安全权限。 + +虽然您也可以选择将这些差异表示为单个资产内的多个测试活动，但 RBAC 只能在资产或组织级别进行设置，如果按此方式组织，可能会限制用户对相应测试活动（以及这些测试活动内的测试和发现项）的访问权限。有关 DefectDojo 中 RBAC 和权限的更多信息，请点击[此处](/admin/user_management/about_perms_and_roles/)。 + +## 资产数据 + +资产始终包含以下组成部分： + +- **组织** +- **唯一名称** +- **描述** +- **SLA 配置** +- **优先级排序引擎** + +可选的资产元数据包括： + +- **标签** +- **业务关键性** +- **用户记录**（即资产中用户记录的估计数量） +- **收入** +- **人员信息**（例如资产经理、团队经理、技术联系人等） +- **法规**（例如 HIPAA、GLBA、OPPA 等） +- **平台**（例如 API、桌面端、物联网、移动端、Web 等） +- **生命周期**（例如构建、生产、退役等） +- **来源**（例如第三方库、外购、开源等） + +这些元数据可改进您整个安全计划中的筛选、报告和优先级排序，但更重要的是，资产还包含与该资产相关测试工作相关的所有测试活动、测试和发现项。来自测试的所有发现项最终都会汇总到资产层级，从而实现长期跟踪、趋势分析和报告。 + +## 访问资产 + +资产可通过侧边栏访问。子菜单提供了[资产层级结构](/asset_modelling/engagements_tests/pro__assets/#asset-nesting)和“所有资产”的访问入口，以及创建新资产的选项。 + +![image](images/assets_ss1.png) + +### 权限 + +资产可以应用基于角色的访问控制（RBAC）规则，以限制团队成员查看和操作这些资产的能力。 + +权限会向下级联，这意味着对某个资产的访问权限会自动授予对该资产内所有对象（例如测试活动、测试和发现项）的访问权限。 + +有关用户角色的更多信息，请参阅我们的[角色介绍](/admin/user_management/set_user_permissions/#introduction-to-permission-types)一文。 + +## 资产视图 + +资产视图包含各种表格和图表，可让您一目了然地了解资产的状态。其中包括： + +- **未结发现项严重程度** + - 资产内按严重程度分组的未结发现项列表 +- **资产概览** + - 资产各项特征的细分信息，包括描述、组件、联系人、[用户组](/admin/user_management/create_user_group/ +)、成员、技术栈和法规。 + - 技术栈：next.js、vue.js、npm v.1.2.3、Django、nginx、Hugo +- **元数据** + - 包括父级和子级资产、组织、业务关键性、收入以及在资产设置中添加的其他详细信息。 +- **按严重程度划分的服务级别协议** + - 将设置中资产的 SLA 配置应用于该资产内的发现项。 +- **发现项严重程度细分** + - 按严重程度组织的资产内发现项图表。 +- **发现项分布** + - 按状态（例如活动、已缓解、静态和动态）组织的资产内发现项细分 +- **所有测试活动** + - 资产内包含的测试活动列表。 + +## 使用资产 + +### 创建资产 + +创建资产有两种方式： + +- 通过侧边菜单中的**新建资产**选项 +- 通过“所有资产”列表顶部的**新建资产**按钮 + +## 编辑资产 + +要编辑资产，可在资产视图右上角的齿轮菜单中点击**编辑资产**。也可以通过点击“所有资产”视图中资产左侧的 ⋮ 竖排菜单来访问同一菜单。 + +随后可编辑的所有字段，在创建资产时也同样可用。 + +![image](images/assets_ss2.png) + +### 删除资产 + +要删除资产，可在资产的设置中选择**删除资产**。此操作无法撤销。资产无法先关闭后再重新打开。 + +删除资产还会删除以下内容： +- 资产内包含的所有测试活动和测试 +- 所有相关的安全历史记录，包括发现项和集成 +- 任何关联的 Jira Epic +- 与该资产的测试活动和测试相关联的所有备注和上传文件 + +## 资产边界 + +### 去重 + +资产彼此“隔离”，不会与其他资产产生交互。DefectDojo 的智能功能（例如去重）仅在单个资产的范围内生效。不同资产之间的发现项不会被自动去重。 + +### 报告与指标 + +大多数报告和指标都在资产层级汇总数据，这使资产成为衡量和跟踪风险的主要单位。 + +因此，许多关键指标都是按资产计算的，包括： + +- 发现项总数（按严重程度或状态） +- 平均修复时间（MTTR） +- SLA 合规率和违规率 +- 风险随时间变化的趋势 + +这意味着资产的结构方式将直接影响报告的准确性和实用性。例如，将多个不相关的系统归入单个资产可能会掩盖风险的可见性，而过于细化的资产结构则可能导致报告碎片化，难以识别更宏观的趋势。 + +### 连接器 + +在 DefectDojo Pro 中，连接器会映射到不同的资产，使其成为 DefectDojo 与您更广泛的安全生态系统之间的主要集成点。 + +一旦连接器被附加到某个资产，它就会导入扫描结果，并在该资产内创建或更新测试活动、测试和发现项。 + +有关连接器的更多信息，请点击[此处](/connectors/upstream/about/#main-content)。 + +### CI/CD 流水线 + +CI/CD 流水线可自动导入扫描结果。无论采用何种集成方式，所有扫描导入都必须与某个资产相关联，这使资产成为流水线驱动的安全数据的锚点。 + +当流水线提交扫描结果时，必须执行以下操作之一： + +- 指定一个现有资产（并可选择指定一个测试活动），或者 +- 以某种方式进行配置，从而始终将结果映射到正确的资产 + +所有导入的发现项都会继承资产的上下文，包括归属关系、权限、优先级/风险配置以及报告范围。 + +实际操作中，资产的定义应反映系统在 CI/CD 中的构建和部署方式，以确保安全结果始终与正确的应用程序或服务相关联。 + +### SLA、优先级与风险 + +在 DefectDojo Pro 中，发现项的 SLA 目标、优先级和风险均继承自包含它们的资产。资产元数据（例如业务关键性、收入等）用于自动计算优先级和风险值。 + +这意味着同一个漏洞可能会因其影响的是内部开发系统还是支持关键业务运营的生产资产，而获得不同的优先级或风险评分。 + +### Jira/下游连接器关系 + +资产可以直接映射到 [Jira](/connectors/downstream/pro__jira_guide/#main-content) 或[集成器](/connectors/downstream/downstream_toolreference/#main-content)实例（例如 GitHub、GitLab、ServiceNow 等），从而将资产的发现项向外推送到外部工单/工作管理系统中。 + +由于发现项的风险、优先级和归属关系均继承自其上级资产，资产实际上决定了流入 Jira 工单和下游连接器工作流的修复上下文。 + +重要的是，资产也是决定发现项 SLA 特征的主要因素。因此，发现项的 SLA 取决于其上级资产的 SLA 配置。有关 SLA 配置的更多信息，请参阅[此处](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas)。 + +## 资产嵌套 + +DefectDojo 支持同一组织内两个资产之间的父子关系，该关系可以在创建资产时配置，也可以在资产的设置中配置。 + +您可以使用侧边栏中的**资产层级结构**选项，对 DefectDojo 中资产的结构进行可视化展示，并更改其关系。 + +在相应表格中选择要进行可视化展示的资产后，点击**查看资产层级结构**，即可生成所选资产之间关系（如果存在）的流程图。 + +有关资产嵌套对去重、RBAC 及其他方面影响的更多信息，以及示例使用场景，可参阅[此处](/asset_modelling/pro_hierarchy/asset_hierarchy/#asset-nesting-examples)。 diff --git a/docs/content/asset_modelling/engagements_tests/PRO__calendar.it.md b/docs/content/asset_modelling/engagements_tests/PRO__calendar.it.md new file mode 100644 index 0000000000..4e5fc8ed6c --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__calendar.it.md @@ -0,0 +1,62 @@ +--- +title: Calendario +description: Come utilizzare il Calendario in DefectDojo Pro +audience: pro +weight: 9 +--- + +DefectDojo dispone di un Calendario integrato che consente di monitorare tutti gli Engagement e i Test precedenti e attivi all'interno della propria organizzazione. Ogni volta che un Utente crea un nuovo Engagement o Test e stabilisce le date di inizio e fine, una voce corrispondente viene aggiunta automaticamente al Calendario. + +### Pagina iniziale + +La pagina del Calendario include dei filtri nella parte superiore e un calendario mensile sottostante. I filtri consentono di regolare quali risultati vengono visualizzati nel calendario in base a: +- Engagement e/o Test +- Data di inizio e di fine +- Stato dell'Engagement (ad es. Completed, In Progress, On Hold, ecc.) +- Responsabile dell'Engagement/Test (ovvero, a chi è assegnato l'Engagement/Test?) +- Tipo di Engagement (ad es. Interactive o CI/CD) +- Tipo di Test (ad es. Pen Test, Acunetix Scan, Tenable Scan, ecc.) + +![image](images/calendar1.png) + +Una volta filtrati, i risultati possono essere esportati e condivisi come file ICS. + +È importante notare che il Calendario mostrerà solo gli Engagement e i Test a cui l'Utente che visualizza il calendario ha accesso. Non verranno visualizzati gli Engagement e i Test che l'Utente non ha il permesso di vedere. + +## Funzionalità + +### Vista mensile + +Il calendario mensile mostra un'anteprima di cinque voci per ogni giorno. Le voci aggiuntive che si verificano in quel giorno rimarranno nascoste a meno che non si faccia clic su **"+ [X] events"** all'interno della cella di una determinata data. Una volta cliccato, il calendario passerà dalla vista mensile a quella giornaliera. + +Facendo clic su una voce relativa a un Test o Engagement si aprirà una finestra modale con informazioni aggiuntive su quella voce, tra cui: +- Data di inizio e di fine +- Tipo di Test o Engagement +- Responsabile +- Stato +- Asset +- Engagement +- Test + +Da lì, è possibile accedere all'Asset, all'Engagement o al Test tramite collegamento ipertestuale. + +### Vista giornaliera + +Nella vista giornaliera, tutti gli Engagement e i Test attualmente attivi vengono visualizzati in ordine cronologico decrescente (ovvero, un Engagement o Test appena creato si troverà in fondo alla voce di quel giorno). Gli Engagement appaiono in blu, mentre i Test appaiono in arancione. + +Se impostato all'interno dell'Engagement/Test in questione, il titolo di ciascuna voce nel calendario giornaliero includerà quanto segue: +- Stato +- Prodotto +- Engagement +- Test +- Assegnatario + +#### Frecce + +Le frecce sul lato sinistro e destro di ciascuna voce indicano se quel particolare Test o Engagement è presente nel giorno precedente e/o successivo. + +Ad esempio, un Test creato nello stesso giorno in cui viene visualizzato non avrà frecce a sinistra, perché quel Test non esisteva il giorno precedente. Al contrario, un Test che termina nello stesso giorno in cui viene visualizzato non avrà frecce a destra, perché la voce non esisterà il giorno successivo. + +Ad esempio, poiché l'ultimo Engagement nella schermata seguente (**In Progress** Example Product A ▶ **Sample Engagement** (Unassigned)) viene visualizzato nel giorno in cui è stato creato, e la Data di fine prevista era impostata per il giorno successivo, non sono presenti frecce né a sinistra né a destra. + +![image](images/calendar2.png) diff --git a/docs/content/asset_modelling/engagements_tests/PRO__calendar.pt-br.md b/docs/content/asset_modelling/engagements_tests/PRO__calendar.pt-br.md new file mode 100644 index 0000000000..56c76f908f --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__calendar.pt-br.md @@ -0,0 +1,62 @@ +--- +title: Calendário +description: Como usar o Calendário no DefectDojo Pro +audience: pro +weight: 9 +--- + +O DefectDojo conta com um Calendário integrado para que você possa acompanhar todos os Engajamentos e Testes anteriores e ativos em sua organização. Sempre que um Usuário cria um novo Engajamento ou Teste e define as datas de início e término, uma entrada correspondente é adicionada automaticamente ao Calendário. + +### Página Inicial + +A página do Calendário inclui filtros na parte superior e um calendário mensal abaixo. Os filtros podem ajustar quais resultados aparecem no calendário com base em: +- Engajamento e/ou Teste +- Data de início e término +- Status do Engajamento (por exemplo, Concluído, Em andamento, Em espera, etc.) +- Responsável pelo Engajamento/Teste (ou seja, a quem o Engajamento/Teste está atribuído?) +- Tipo de Engajamento (por exemplo, Interativo ou CI/CD) +- Tipo de Teste (por exemplo, Pen Test, Acunetix Scan, Tenable Scan, etc.) + +![image](images/calendar1.png) + +Depois de filtrados, os resultados podem ser exportados e compartilhados como um arquivo ICS. + +É importante notar que o Calendário exibirá apenas os Engajamentos e Testes aos quais o Usuário que está visualizando o calendário tem acesso. Ele não exibirá Engajamentos e Testes que o Usuário não tem permissão para visualizar. + +## Recursos + +### Visualização Mensal + +O calendário mensal exibe uma prévia de cinco entradas por dia. Entradas adicionais que ocorram naquele dia ficarão ocultas, a menos que **"+ [X] events"** seja clicado dentro da célula de uma determinada data. Uma vez clicado, o calendário mudará da visualização mensal para a visualização diária. + +Clicar em uma entrada de Teste ou Engajamento abrirá uma janela modal com informações adicionais sobre essa entrada, incluindo: +- Data de início e término +- Tipo de Teste ou Engajamento +- Responsável +- Status +- Asset +- Engajamento +- Teste + +A partir daí, o Asset, Engajamento ou Teste pode ser acessado por meio de um hyperlink. + +### Visualização Diária + +Na visualização diária, todos os Engajamentos e Testes atualmente ativos aparecem em ordem cronológica decrescente (ou seja, um Engajamento ou Teste recém-criado aparecerá na parte inferior das entradas daquele dia). Os Engajamentos aparecem em azul, enquanto os Testes aparecem em laranja. + +Se definido dentro do Engajamento/Teste aplicável, o título de cada entrada no calendário diário incluirá o seguinte: +- Status +- Produto +- Engajamento +- Teste +- Responsável + +#### Setas + +As setas nos lados esquerdo e direito de cada entrada indicam se aquele Teste ou Engajamento específico está presente no dia anterior e/ou no dia seguinte. + +Por exemplo, um Teste criado no mesmo dia em que está sendo visualizado não terá setas à esquerda, pois esse Teste não existia no dia anterior. Por outro lado, um Teste que termina no mesmo dia em que está sendo visualizado não terá setas à direita, pois a entrada não existirá no dia seguinte. + +Por exemplo, como o último Engajamento na captura de tela abaixo (**In Progress** Example Product A ▶ **Sample Engagement** (Unassigned)) está sendo visualizado no dia em que foi criado, e a Data de Término Alvo foi definida para o dia seguinte, não há setas presentes em nenhum dos lados. + +![image](images/calendar2.png) diff --git a/docs/content/asset_modelling/engagements_tests/PRO__calendar.zh-hans.md b/docs/content/asset_modelling/engagements_tests/PRO__calendar.zh-hans.md new file mode 100644 index 0000000000..77ef4c3f5a --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__calendar.zh-hans.md @@ -0,0 +1,62 @@ +--- +title: 日历 +description: 如何在 DefectDojo Pro 中使用日历 +audience: pro +weight: 9 +--- + +DefectDojo 内置了日历功能，让您可以跟踪组织内所有过去和正在进行的测试活动与测试。每当用户创建新的测试活动或测试并设置开始和结束日期时，日历中都会自动添加相应的条目。 + +### 起始页面 + +日历页面顶部包含筛选器，下方是月历视图。筛选器可根据以下条件调整日历中显示的结果： +- 测试活动和/或测试 +- 开始和结束日期 +- 测试活动状态（例如已完成、进行中、暂停等） +- 测试活动/测试负责人（即测试活动/测试分配给了谁） +- 测试活动类型（例如交互式或 CI/CD） +- 测试类型（例如渗透测试、Acunetix 扫描、Tenable 扫描等） + +![image](images/calendar1.png) + +筛选完成后，结果可以导出为 ICS 文件并进行分享。 + +需要注意的是，日历只会显示查看日历的用户有权访问的测试活动和测试，不会显示该用户无权查看的测试活动和测试。 + +## 功能 + +### 月视图 + +月历会在每天预览五个条目。当天的其他条目将被隐藏，除非点击某个日期单元格中的 **“+ [X] events”**。点击后，日历会从月视图切换为日视图。 + +点击测试或测试活动的条目会弹出一个模态框，其中包含该条目的更多信息，包括： +- 开始和结束日期 +- 测试或测试活动类型 +- 负责人 +- 状态 +- 资产 +- 测试活动 +- 测试 + +从该模态框中，可以通过超链接访问对应的资产、测试活动或测试。 + +### 日视图 + +在日视图中，所有当前活动的测试活动和测试会按时间倒序排列（即新创建的测试活动或测试会出现在当天条目的底部）。测试活动显示为蓝色，测试显示为橙色。 + +如果在相应的测试活动/测试中进行了设置，日历日视图中每个条目的标题将包含以下信息： +- 状态 +- 产品 +- 测试活动 +- 测试 +- 分配对象 + +#### 箭头 + +每个条目左右两侧的箭头表示该测试或测试活动是否也出现在前一天和/或后一天。 + +例如，如果某个测试是在正在查看的当天创建的，那么它左侧不会显示箭头，因为该测试在前一天并不存在。反之，如果某个测试在正在查看的当天结束，那么它右侧不会显示箭头，因为该条目在第二天将不再存在。 + +例如，下方截图中的最后一个测试活动（**进行中** Example Product A ▶ **Sample Engagement**（未分配））正是在其创建当天被查看的，且其目标结束日期设置为次日，因此左右两侧都没有显示箭头。 + +![image](images/calendar2.png) diff --git a/docs/content/asset_modelling/engagements_tests/PRO__engagements.it.md b/docs/content/asset_modelling/engagements_tests/PRO__engagements.it.md new file mode 100644 index 0000000000..180dbabd57 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__engagements.it.md @@ -0,0 +1,193 @@ +--- +title: Engagement +description: Comprendere gli Engagement in DefectDojo Pro +audience: pro +weight: 3 +--- + +Organizzazioni → Asset → **ENGAGEMENT** → Test → Riscontri + +## Panoramica + +Nella Gerarchia degli Asset di DefectDojo, gli Engagement sono contenitori delimitati nel tempo o legati a una pipeline che rappresentano gruppi di Test correlati all'interno di un Asset specifico. Se si dispone di un'attività di test pianificata, su base ricorrente o una tantum, un Engagement offre un luogo in cui archiviare tutti i risultati correlati. + +Esempi di Engagement includono: +- Penetration test una tantum +- Scansioni mensili o trimestrali ricorrenti +- Periodi di revisione bug bounty +- Esecuzioni di pipeline CI/CD (per i team che trattano ogni pipeline come un proprio Engagement) +- Cicli di rilascio del codice (ad es., "revisione di sicurezza per il rilascio v4.2") + +### Tipi di Engagement + +DefectDojo supporta due tipi di Engagement: **Interactive** e **CI/CD**. Questi tipi determinano come vengono generalmente creati i Test e come vengono importati i risultati delle scansioni. + +Un Engagement Interactive viene tipicamente condotto da un ingegnere. Gli Engagement Interactive si concentrano sul test di un'applicazione mentre è in esecuzione, utilizzando un test automatizzato, un tester umano o qualsiasi attività che "interagisce" con le funzionalità dell'applicazione. + +Un Engagement CI/CD è destinato all'integrazione automatizzata con una pipeline CI/CD. Gli Engagement CI/CD hanno lo scopo di importare i dati come azione automatizzata, attivata da una fase del processo di rilascio. + +| **Categoria** | **Engagement Interactive** | **Engagement CI/CD** | +|------------------------|--------------------------------------------------------------|--------------------------------------------------------------------| +| **Caso d'uso principale** | Test di sicurezza manuali o ad hoc | Test di sicurezza automatizzati e ricorrenti all'interno delle pipeline | +| **Durata** | Delimitata nel tempo e finita | Potenzialmente di durata infinita | +| **Frequenza** | Periodica o una tantum | Continua o per commit | +| **Workflow** | Un tester umano esegue lo strumento → importa manualmente i risultati | La pipeline esegue lo strumento → invia automaticamente i risultati a DefectDojo | +| **Metodo di importazione dei risultati** | Caricamento manuale tramite UI o CLI | Importazione basata su API tramite automazione (ad es. CLI, connettori, cron job, script di pipeline) | +| **Tipo di test tipico** | Penetration test, esercitazioni red team, valutazioni manuali | Analisi statica, scansione delle dipendenze, scansione dei container | + +### Dati dell'Engagement + +In quanto contenitori che organizzano l'attività di test, gli Engagement possono archiviare o tracciare una serie di dati: + +- Date di inizio e fine previste +- Descrizione e note sull'ambito +- Stato (ongoing, planned, completed, ecc.) +- Assegnatario / Responsabile +- Test associati (ad es. scansioni, pen test, test manuali, ecc.) +- Riscontri e tipi di Riscontro (ad es. active, mitigated, risk accepted, duplicate, ecc.) +- Modelli di minaccia o informazioni sull'accettazione del rischio +- Tag +- File e note +- Impostazioni del progetto Jira +- Dettagli sull'ambiente (ad es. staging o produzione) +- ID di build (se collegato a CI/CD) +- Dati storici dei Test precedenti all'interno dell'Engagement + +## Accesso agli Engagement + +Gli Engagement sono accessibili tramite la barra laterale. Il sottomenu offre l'accesso agli Engagement attivi e a tutti gli Engagement, oltre alla possibilità di crearne di nuovi. + +![image](images/engagement_ss13.png) + +In alternativa, è possibile accedere agli Engagement all'interno di un Asset nella finestra in fondo alla vista dell'Asset. + +![image](images/engagement_ss14.png) + +### Permessi + +Gli Engagement si trovano al di sotto degli Asset e al di sopra dei Test nella gerarchia degli oggetti. Di conseguenza, l'accesso a un Asset garantisce automaticamente l'accesso a tutti gli Engagement al suo interno. Gli Engagement non dispongono di elenchi di controllo degli accessi indipendenti. + +## Utilizzo degli Engagement + +### Creazione degli Engagement + +Prima di creare un Engagement, è necessario aver già [creato un Asset](/asset_modelling/engagements_tests/pro__assets/#create-assets) che lo contenga. + +Esistono diversi modi per creare un Engagement: + +- All'interno del menu a tendina Engagement nella sezione Manage della barra laterale + - Sarà necessario selezionare l'Asset a cui attribuire l'Engagement durante la compilazione del modulo New Engagement + +![image](images/engagement_ss1.png) + +- L'icona a forma di ingranaggio situata nell'angolo in alto a destra della vista di un Asset + +![image](images/engagement_ss9.png) + +- Il pulsante "+ New Engagement" presente nell'elenco degli Engagement all'interno di un Asset + +![image](images/engagement_ss2.png) + +- Se non è già stato creato un Engagement all'interno di un Asset, è possibile farlo durante l'importazione di una scansione. + +![image](images/engagement_ss3.png) + +Ogni Engagement deve avere definiti i seguenti campi: +- Tipo (Interactive o CI/CD) +- Un nome univoco +- Date di inizio e fine previste + - Questo determinerà la comparsa dell'Engagement nella sezione Calendario +- Asset +- Stato + +#### Stati dell'Engagement + +Gli Engagement possono essere contrassegnati con stati diversi al momento della creazione. Lo stato può anche essere modificato successivamente nelle impostazioni dell'Engagement. + +Un Engagement può avere uno dei seguenti stati: +- Not Started +- Blocked +- Cancelled +- Completed +- In Progress +- On Hold +- Scheduled +- Waiting for Resource + +Modificare lo stato di un Engagement in "Completed" comporterà che la maggior parte delle operazioni di scrittura (ad es. aggiunta di test, importazione di scansioni) diventino non disponibili o nascoste. Gli altri stati non influiscono in modo sostanziale sulla funzionalità dell'Engagement e servono principalmente a scopi di filtraggio/informativi. + +### Modifica degli Engagement + +Gli Engagement possono essere modificati facendo clic su **Edit Engagement** all'interno del menu a forma di ingranaggio. Lo stesso menu è accessibile anche facendo clic sul menu kebab ⋮ a sinistra dell'Asset nella vista All Assets. + +Tutti i campi successivamente modificabili sono disponibili anche al momento della creazione dell'Engagement. + +![image](images/engagements_ss99.png) + +### Copia degli Engagement + +È possibile duplicare facilmente gli Engagement selezionando "Copy Engagement" all'interno delle impostazioni dell'Engagement. Questo creerà una copia esatta dell'Engagement originale all'interno dell'Asset principale, inclusi i metadati, i Test e i Riscontri al suo interno. + +### Chiusura degli Engagement + +Gli Engagement vengono chiusi selezionando **Close Engagement** all'interno delle impostazioni dell'Engagement. Una volta chiuso, lo stato dell'Engagement verrà modificato in "Completed." Ciononostante, la maggior parte delle operazioni di scrittura (ad es. aggiunta di test, importazione di scansioni) rimarrà disponibile. + +La chiusura di un Engagement non modifica lo stato dei Riscontri all'interno dei Test dell'Engagement. I Riscontri rimangono attivi, mitigati o con rischio accettato in base al proprio ciclo di vita, e restano accessibili per la visualizzazione e la reportistica. + +Se l'Engagement è collegato a un Epic Jira (vedere **[Integrazione Jira: Enable Engagement Epic Mapping](/connectors/downstream/pro__jira_guide/#enable-engagement-epic-mapping)**), la chiusura dell'Engagement attiverà un'attività asincrona che chiude l'Epic Jira associato nel proprio Spazio Jira connesso. + +### Riapertura degli Engagement + +Se un Engagement è chiuso, può essere riaperto selezionando **Reopen Engagement** all'interno delle sue impostazioni. Questo renderà nuovamente attivo l'Engagement e riporterà il suo stato a "In Progress." + +### Engagement scaduti + +Un Engagement scade una volta superata la data di fine prevista. + +Rispetto alla chiusura o all'eliminazione di un Engagement, la scadenza di un Engagement non ha un impatto diretto sulla sua funzionalità, e serve principalmente come meccanismo di monitoraggio/notifica. + +Una volta scaduto, accanto all'Engagement comparirà un tag "Overdue", ma questo non limiterà alcuna funzionalità dell'Engagement. Lo stato dell'Engagement continuerà a essere visualizzato come "In Progress." + +Sebbene non sia abilitata per impostazione predefinita, è disponibile un'opzione nelle impostazioni di sistema per chiudere automaticamente un Engagement una volta scaduto da un determinato numero di giorni. + +![image](images/engagement_ss15.png) + +### Eliminazione degli Engagement + +L'eliminazione di un Engagement può essere effettuata selezionando **Delete Engagement** dalle impostazioni dell'Engagement. Questa azione non può essere annullata. + +L'eliminazione di un Engagement comporterà anche l'eliminazione di quanto segue: +Tutti i Test associati all'Engagement +Tutti i Riscontri all'interno di tali Test +Eventuali mappature di Epic Jira collegate (l'Epic stesso rimarrà in Jira, ma il collegamento tra DefectDojo e Jira verrà rimosso) +Tutte le note e i file caricati associati all'Engagement + +Per finalità di audit, si consiglia di chiudere gli Engagement completati anziché eliminarli. + +| **Operazione** | **Risultati** | **Reversibile** | +|----------|---------|------------| +| **Chiusura** | Contrassegna come inattivo; i dati rimangono; può essere riaperto | Sì (riapertura) | +| **Scadenza** | Solo avviso visivo; chiusura automatica opzionale; notifiche | N/D | +| **Eliminazione** | Rimuove permanentemente l'Engagement, i Test, i Riscontri, le note, i file ed eventuali mappature di Epic Jira (gli Epic rimangono in Jira) | No | + +## Integrazione con Jira + +Gli Engagement possono essere collegati a uno Jira Space connesso, consentendo di inviare i Riscontri all'interno dell'Engagement a Jira come Issue. Per una guida completa alla configurazione di Jira, vedere **[Connessione di DefectDojo a Jira](/connectors/downstream/pro__jira_guide/)**. + +### Mappatura degli Epic per gli Engagement + +Quando l'opzione **Enable Engagement Epic Mapping** è selezionata nelle impostazioni Jira di un Prodotto, gli Engagement verranno inviati a Jira come Epic. I Riscontri all'interno dell'Engagement vengono inviati come Issue figlie sotto l'Epic, rispecchiando la gerarchia Engagement → Riscontri di DefectDojo nella struttura Epic → Issue di Jira. + +Per maggiori informazioni su questa impostazione, vedere **[Enable Engagement Epic Mapping](/connectors/downstream/pro__jira_guide/#enable-engagement-epic-mapping)**. + +### Impostazioni Jira a livello di Engagement + +Per impostazione predefinita, gli Engagement ereditano le impostazioni Jira dal proprio Asset principale (Prodotto). Tuttavia, i singoli Engagement possono sovrascrivere queste impostazioni per utilizzare configurazioni Jira diverse. Le seguenti impostazioni possono essere personalizzate per singolo Engagement: + +- **Project Key** — instrada i Riscontri verso uno Jira Space diverso +- **Issue Template** — utilizza un modello diverso per le Issue create da questo Engagement +- **Custom Fields** — applica mappature di campi personalizzati diverse +- **Jira Labels** — contrassegna le Issue con etichette specifiche dell'Engagement +- **Default Assignee** — assegna le Issue a un membro del team diverso + +Queste impostazioni sono accessibili dalla pagina **Edit Engagement**. Per maggiori dettagli, vedere **[Impostazioni Jira a livello di Engagement](/connectors/downstream/pro__jira_guide/#engagement-level-jira-settings)**. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__engagements.pt-br.md b/docs/content/asset_modelling/engagements_tests/PRO__engagements.pt-br.md new file mode 100644 index 0000000000..11499cd987 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__engagements.pt-br.md @@ -0,0 +1,193 @@ +--- +title: Engajamentos +description: Entendendo Engajamentos no DefectDojo Pro +audience: pro +weight: 3 +--- + +Organizações → Assets → **ENGAJAMENTOS** → Testes → Achados + +## Visão Geral + +Na Hierarquia de Assets do DefectDojo, os Engajamentos são contêineres limitados por tempo ou por pipeline que representam grupos de Testes relacionados dentro de um Asset específico. Se você tem um esforço de teste planejado, seja em uma base rotineira ou pontual, um Engajamento oferece um local para armazenar todos os resultados relacionados. + +Exemplos de Engajamentos incluem: +- Testes de penetração pontuais +- Varreduras recorrentes mensais ou trimestrais +- Períodos de revisão de bug bounty +- Execuções de pipeline de CI/CD (para equipes que tratam cada pipeline como seu próprio Engajamento) +- Ciclos de lançamento de código (por exemplo, "revisão de segurança do lançamento v4.2") + +### Tipos de Engajamento + +O DefectDojo suporta dois tipos de Engajamento: **Interativo** e **CI/CD**. Esses tipos determinam como os Testes são normalmente criados e como os resultados de varredura são importados. + +Um Engajamento Interativo é normalmente executado por um engenheiro. Engajamentos Interativos são focados em testar uma aplicação enquanto ela está em execução, usando um teste automatizado, um testador humano ou qualquer atividade que "interaja" com a funcionalidade da aplicação. + +Um Engajamento de CI/CD é destinado à integração automatizada com um pipeline de CI/CD. Engajamentos de CI/CD têm como objetivo importar dados como uma ação automatizada, acionada por uma etapa do processo de lançamento. + +| **Categoria** | **Engajamentos Interativos** | **Engajamentos de CI/CD** | +|------------------------|--------------------------------------------------------------|--------------------------------------------------------------------| +| **Caso de Uso Principal** | Testes de segurança manuais ou pontuais | Testes de segurança automatizados e recorrentes dentro de pipelines | +| **Duração** | Limitada no tempo e finita | Duração potencialmente infinita | +| **Frequência** | Periódica ou pontual | Contínua ou a cada commit | +| **Fluxo de Trabalho** | Testador humano executa a ferramenta → importa os resultados manualmente | Pipeline executa a ferramenta → envia os resultados automaticamente para o DefectDojo | +| **Método de Importação de Resultados** | Upload manual via UI ou CLI | Importação orientada por API via automação (por exemplo, CLI, conectores, cron jobs, scripts de pipeline) | +| **Tipo de Teste Típico** | Testes de penetração, exercícios de red team, avaliações manuais | Análise estática, varredura de dependências, varredura de contêineres | + +### Dados do Engajamento + +Como os contêineres que organizam a atividade de teste, os Engajamentos podem armazenar ou rastrear uma variedade de dados: + +- Datas de início e término alvo +- Descrição e notas de escopo +- Status (em andamento, planejado, concluído, etc.) +- Responsável / Lead +- Testes associados (por exemplo, varreduras, pen tests, testes manuais, etc.) +- Achados e Tipos de Achado (por exemplo, ativo, mitigado, risco aceito, duplicado, etc.) +- Modelos de ameaça ou informações de aceitação de risco +- Tags +- Arquivos e notas +- Configurações de projeto do Jira +- Detalhes do ambiente (por exemplo, staging vs. produção) +- IDs de build (se vinculado a CI/CD) +- Dados históricos de Testes anteriores dentro do Engajamento + +## Acessando Engajamentos + +Os Engajamentos são acessíveis pela barra lateral. O submenu fornece acesso a Engajamentos Ativos e Todos os Engajamentos, além da opção de criar novos Engajamentos. + +![image](images/engagement_ss13.png) + +Alternativamente, os Engajamentos dentro de um Asset podem ser acessados na janela na parte inferior da visualização do Asset. + +![image](images/engagement_ss14.png) + +### Permissões + +Os Engajamentos ficam abaixo dos Assets e acima dos Testes na hierarquia de objetos. Dessa forma, o acesso a um Asset concede automaticamente acesso a todos os Engajamentos dentro desse Asset. Os Engajamentos não possuem listas de controle de acesso independentes. + +## Trabalhando com Engajamentos + +### Criar Engajamentos + +Antes de criar um Engajamento, você deve primeiro ter [criado um Asset](/asset_modelling/engagements_tests/pro__assets/#create-assets) para contê-lo. + +Existem várias maneiras de criar um Engajamento: + +- No menu suspenso de Engajamentos na seção Gerenciar da barra lateral + - Você precisará selecionar o Asset ao qual atribuir o Engajamento ao preencher o formulário de Novo Engajamento + +![image](images/engagement_ss1.png) + +- O ícone de engrenagem localizado no canto superior direito da visualização de um Asset + +![image](images/engagement_ss9.png) + +- O botão "+ New Engagement" encontrado na lista de Engajamentos dentro de um Asset + +![image](images/engagement_ss2.png) + +- Se você ainda não criou um Engajamento dentro de um Asset, pode fazê-lo durante a importação de uma varredura. + +![image](images/engagement_ss3.png) + +Todo Engajamento deve ter os seguintes campos definidos: +- Tipo (Interativo ou CI/CD) +- Um nome exclusivo +- Datas de início e término alvo + - Isso determinará a aparência do Engajamento na seção Calendário +- Asset +- Status + +#### Status do Engajamento + +Os Engajamentos podem ser marcados com diferentes status no momento da criação. O status também pode ser alterado posteriormente nas configurações do Engajamento. + +Um Engajamento pode ter qualquer um dos seguintes status: +- Não Iniciado +- Bloqueado +- Cancelado +- Concluído +- Em Andamento +- Em Espera +- Agendado +- Aguardando Recurso + +Alterar o status de um Engajamento para "Concluído" significa que a maioria das operações de escrita (por exemplo, adicionar testes, importar varreduras) ficará indisponível ou oculta. Outros status não afetam materialmente a funcionalidade do Engajamento, servindo mais para fins de filtragem/informação. + +### Editar Engajamentos + +Os Engajamentos podem ser editados clicando em **Edit Engagement** no menu de engrenagem. O mesmo menu também pode ser acessado clicando no menu kebab ⋮ à esquerda do Asset na visualização Todos os Assets. + +Todos os campos subsequentes que podem ser editados também estão disponíveis quando o Engajamento está sendo criado. + +![image](images/engagements_ss99.png) + +### Copiar Engajamentos + +Você pode duplicar Engajamentos facilmente selecionando "Copy Engagement" nas configurações do Engajamento. Isso criará uma cópia exata do Engajamento original dentro do Asset pai, incluindo os metadados, Testes e Achados presentes nele. + +### Fechar Engajamentos + +Os Engajamentos são fechados selecionando **Close Engagement** nas configurações do Engajamento. Uma vez fechado, o status do Engajamento será alterado para "Concluído". Ainda assim, a maioria das operações de escrita (por exemplo, adicionar testes, importar varreduras) permanecerá disponível. + +Fechar um Engajamento não altera o status dos Achados em nenhum dos Testes do Engajamento. Os Achados permanecem ativos, mitigados ou com risco aceito de acordo com seu próprio ciclo de vida, e continuam acessíveis para visualização e geração de relatórios. + +Se o Engajamento estiver vinculado a um Épico do Jira (veja **[Integração com o Jira: Habilitar Mapeamento de Épico de Engajamento](/connectors/downstream/pro__jira_guide/#enable-engagement-epic-mapping)**), fechar o Engajamento acionará uma tarefa assíncrona que fecha o Épico do Jira associado em seu Espaço do Jira conectado. + +### Reabrir Engajamentos + +Se um Engajamento estiver fechado, ele pode ser reaberto selecionando **Reopen Engagement** em suas configurações. Isso tornará o Engajamento ativo novamente e retornará seu status para "Em Andamento". + +### Engajamentos Expirados + +Um Engajamento expira assim que sua data de término alvo é ultrapassada. + +Em comparação com fechar ou excluir um Engajamento, a expiração de um Engajamento não tem impacto direto em sua funcionalidade, servindo principalmente como um mecanismo de monitoramento/notificação. + +Uma vez expirado, uma tag "Overdue" aparecerá ao lado do Engajamento, mas isso não restringirá nenhuma de suas funcionalidades. O status do Engajamento continuará aparecendo como "Em Andamento". + +Embora não esteja habilitada por padrão, há uma opção nas configurações do sistema para fechar automaticamente um Engajamento depois que ele tiver expirado por um determinado número de dias. + +![image](images/engagement_ss15.png) + +### Excluir Engajamentos + +A exclusão de um Engajamento pode ser realizada selecionando **Delete Engagement** nas configurações do Engajamento. Essa ação não pode ser desfeita. + +Excluir um Engajamento também excluirá o seguinte: +Qualquer Teste associado ao Engajamento +Todos os Achados dentro desses Testes +Qualquer mapeamento de Épico do Jira vinculado (o Épico em si permanecerá no Jira, mas o vínculo entre o DefectDojo e o Jira será removido) +Todas as notas e uploads de arquivos associados ao Engajamento + +Para fins de auditoria, recomenda-se fechar quaisquer Engajamentos concluídos, em vez de excluí-los. + +| **Operação** | **Resultados** | **Reversível** | +|----------|---------|------------| +| **Fechar** | Marca como inativo; os dados permanecem; pode ser reaberto | Sim (reabrir) | +| **Expirar** | Apenas aviso visual; fechamento automático opcional; notificações | N/A | +| **Excluir** | Remove permanentemente o Engajamento, Testes, Achados, notas, arquivos e quaisquer mapeamentos de Épico do Jira (os Épicos permanecem no Jira) | Não | + +## Integração com o Jira + +Os Engajamentos podem ser vinculados a um Espaço do Jira conectado, permitindo que os Achados dentro do Engajamento sejam enviados ao Jira como Issues. Para obter um guia completo sobre a configuração do Jira, veja **[Conectando o DefectDojo ao Jira](/connectors/downstream/pro__jira_guide/)**. + +### Mapeamento de Épico de Engajamento + +Quando **Enable Engagement Epic Mapping** está marcado nas configurações do Jira de um Produto, os Engajamentos serão enviados ao Jira como Épicos. Os Achados dentro do Engajamento são enviados como Issues filhas do Épico, espelhando a hierarquia Engajamento → Achados do DefectDojo na estrutura Épico → Issue do Jira. + +Para mais informações sobre essa configuração, veja **[Habilitar Mapeamento de Épico de Engajamento](/connectors/downstream/pro__jira_guide/#enable-engagement-epic-mapping)**. + +### Configurações do Jira em Nível de Engajamento + +Por padrão, os Engajamentos herdam suas configurações do Jira do Asset pai (Produto). No entanto, Engajamentos individuais podem sobrepor essas configurações para usar configurações diferentes do Jira. As seguintes configurações podem ser personalizadas por Engajamento: + +- **Project Key** — direciona os Achados para um Espaço do Jira diferente +- **Issue Template** — usa um modelo diferente para Issues criadas a partir deste Engajamento +- **Custom Fields** — aplica mapeamentos de campos personalizados diferentes +- **Jira Labels** — marca Issues com labels específicas do Engajamento +- **Default Assignee** — atribui Issues a um membro diferente da equipe + +Essas configurações são acessíveis na página **Edit Engagement**. Para mais detalhes, veja **[Configurações do Jira em Nível de Engajamento](/connectors/downstream/pro__jira_guide/#engagement-level-jira-settings)**. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__engagements.zh-hans.md b/docs/content/asset_modelling/engagements_tests/PRO__engagements.zh-hans.md new file mode 100644 index 0000000000..8af59a2485 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__engagements.zh-hans.md @@ -0,0 +1,193 @@ +--- +title: 测试活动 +description: 了解 DefectDojo Pro 中的测试活动 +audience: pro +weight: 3 +--- + +组织 → 资产 → **测试活动** → 测试 → 发现项 + +## 概述 + +在 DefectDojo 的资产层级结构中，测试活动是以时间或流水线为边界的容器，用于表示特定资产内一组相关测试。无论您计划的测试工作是例行性的还是一次性的，测试活动都为您提供了一个存储所有相关结果的地方。 + +测试活动的示例包括： +- 一次性渗透测试 +- 每月或每季度的周期性扫描 +- 漏洞赏金评审周期 +- CI/CD 流水线运行（适用于将每次流水线运行视为独立测试活动的团队） +- 代码发布周期（例如“v4.2 发布安全评审”） + +### 测试活动类型 + +DefectDojo 支持两种测试活动类型：**交互式（Interactive）**和 **CI/CD**。这些类型决定了测试通常是如何创建的，以及扫描结果是如何导入的。 + +交互式测试活动通常由工程师执行。交互式测试活动侧重于在应用程序运行期间对其进行测试，测试方式可以是自动化测试、人工测试人员，或任何与应用程序功能进行“交互”的活动。 + +CI/CD 测试活动用于与 CI/CD 流水线进行自动化集成。CI/CD 测试活动旨在通过发布流程中的某个步骤触发自动化操作来导入数据。 + +| **类别** | **交互式测试活动** | **CI/CD 测试活动** | +|------------------------|--------------------------------------------------------------|--------------------------------------------------------------------| +| **主要使用场景** | 人工或临时性的安全测试 | 流水线中自动化、周期性的安全测试 | +| **持续时间** | 有时间限制，时长有限 | 可能持续时间不确定 | +| **频率** | 周期性或一次性 | 持续进行或每次提交触发 | +| **工作流程** | 人工测试人员运行工具 → 手动导入结果 | 流水线运行工具 → 自动将结果推送到 DefectDojo | +| **结果导入方式** | 通过 UI 或 CLI 手动上传 | 通过自动化方式进行 API 驱动的导入（例如 CLI、连接器、定时任务、流水线脚本） | +| **典型测试类型** | 渗透测试、红队演练、人工评估 | 静态分析、依赖扫描、容器扫描 | + +### 测试活动数据 + +作为组织测试活动的容器，测试活动可以存储或跟踪多种数据： + +- 目标开始和结束日期 +- 描述和范围说明 +- 状态（进行中、已计划、已完成等） +- 分配对象/负责人 +- 关联的测试（例如扫描、渗透测试、人工测试等） +- 发现项及发现项类型（例如活动、已缓解、风险已接受、重复等） +- 威胁模型或风险接受信息 +- 标签 +- 文件和备注 +- Jira 项目设置 +- 环境详情（例如预发布环境与生产环境） +- 构建 ID（如果与 CI/CD 关联） +- 该测试活动内以往测试的历史数据 + +## 访问测试活动 + +可以通过侧边栏访问测试活动。子菜单提供了访问“活动中的测试活动”和“所有测试活动”的入口，以及创建新测试活动的选项。 + +![image](images/engagement_ss13.png) + +此外，资产内的测试活动也可以在资产视图底部的窗口中访问。 + +![image](images/engagement_ss14.png) + +### 权限 + +在对象层级结构中，测试活动位于资产之下、测试之上。因此，只要拥有某个资产的访问权限，就会自动获得该资产内所有测试活动的访问权限。测试活动没有独立的访问控制列表。 + +## 操作测试活动 + +### 创建测试活动 + +在创建测试活动之前，您必须先[创建一个资产](/asset_modelling/engagements_tests/pro__assets/#create-assets)来容纳它。 + +创建测试活动有多种方式： + +- 通过侧边栏“管理”部分中的测试活动下拉菜单 + - 在填写“新建测试活动”表单时，您需要选择该测试活动所归属的资产 + +![image](images/engagement_ss1.png) + +- 资产视图右上角的齿轮图标 + +![image](images/engagement_ss9.png) + +- 资产的测试活动列表中的“+ New Engagement”按钮 + +![image](images/engagement_ss2.png) + +- 如果您尚未在某个资产中创建测试活动，也可以在导入扫描的同时创建。 + +![image](images/engagement_ss3.png) + +每个测试活动都必须定义以下字段： +- 类型（交互式或 CI/CD） +- 唯一名称 +- 目标开始和结束日期 + - 这将决定该测试活动在日历部分中的显示情况 +- 资产 +- 状态 + +#### 测试活动状态 + +创建测试活动时可以为其标记不同的状态。之后也可以在测试活动的设置中更改状态。 + +测试活动可以具有以下任意一种状态： +- 未开始 +- 已阻塞 +- 已取消 +- 已完成 +- 进行中 +- 暂停 +- 已计划 +- 等待资源 + +将测试活动的状态更改为“已完成”意味着大多数写操作（例如添加测试、导入扫描）将变得不可用或被隐藏。其他状态不会实质性地影响测试活动的功能，主要用于筛选/信息展示目的。 + +### 编辑测试活动 + +可以通过点击齿轮菜单中的 **Edit Engagement（编辑测试活动）** 来编辑测试活动。也可以通过点击“所有资产”视图中资产左侧的 ⋮ 三点菜单来访问相同的菜单。 + +随后可编辑的所有字段，在创建测试活动时同样可用。 + +![image](images/engagements_ss99.png) + +### 复制测试活动 + +您可以在测试活动的设置中选择“Copy Engagement（复制测试活动）”来轻松复制测试活动。这将在父资产内创建原测试活动的完整副本，包括其中的元数据、测试和发现项。 + +### 关闭测试活动 + +可以在测试活动的设置中选择 **Close Engagement（关闭测试活动）** 来关闭测试活动。关闭后，该测试活动的状态将变更为“已完成”。不过，大多数写操作（例如添加测试、导入扫描）仍然可用。 + +关闭测试活动不会改变该测试活动下任何测试中发现项的状态。发现项会根据其自身的生命周期继续保持活动、已缓解或风险已接受的状态，并仍可用于查看和生成报告。 + +如果该测试活动关联了一个 Jira Epic（参见 **[Jira 集成：启用测试活动 Epic 映射](/connectors/downstream/pro__jira_guide/#enable-engagement-epic-mapping)**），关闭该测试活动将触发一个异步任务，在您所连接的 Jira 空间中关闭相应的 Jira Epic。 + +### 重新打开测试活动 + +如果测试活动已关闭，可以在其设置中选择 **Reopen Engagement（重新打开测试活动）** 将其重新打开。这将使该测试活动重新变为活动状态，并将其状态恢复为“进行中”。 + +### 已过期的测试活动 + +一旦测试活动的目标结束日期已过，该测试活动即视为已过期。 + +与关闭或删除测试活动相比，测试活动过期本身不会直接影响其功能，主要作为一种监控/通知机制。 + +一旦过期，测试活动旁边会出现“Overdue（已逾期）”标签，但不会限制该测试活动的任何功能。该测试活动的状态仍会显示为“进行中”。 + +虽然默认未启用，但系统设置中提供了一个选项，可以在测试活动过期达到一定天数后自动将其关闭。 + +![image](images/engagement_ss15.png) + +### 删除测试活动 + +可以在测试活动的设置中选择 **Delete Engagement（删除测试活动）** 来删除该测试活动。此操作无法撤销。 + +删除测试活动还会删除以下内容： +与该测试活动关联的所有测试 +这些测试中的所有发现项 +任何已关联的 Jira Epic 映射（Epic 本身会保留在 Jira 中，但 DefectDojo 与 Jira 之间的链接会被移除） +与该测试活动相关的所有备注和文件上传 + +出于审计目的，建议对已完成的测试活动进行关闭，而不是删除。 + +| **操作** | **结果** | **是否可逆** | +|----------|---------|------------| +| **关闭** | 标记为非活动；数据保留；可重新打开 | 是（可重新打开） | +| **过期** | 仅显示视觉提示；可选自动关闭；发送通知 | 不适用 | +| **删除** | 永久删除测试活动、测试、发现项、备注、文件以及任何 Jira Epic 映射（Epic 本身保留在 Jira 中） | 否 | + +## Jira 集成 + +测试活动可以关联到已连接的 Jira 空间，从而将该测试活动内的发现项作为 Issue 推送到 Jira。有关设置 Jira 的完整指南，请参见 **[将 DefectDojo 连接到 Jira](/connectors/downstream/pro__jira_guide/)**。 + +### 测试活动 Epic 映射 + +当在产品的 Jira 设置中勾选 **Enable Engagement Epic Mapping（启用测试活动 Epic 映射）** 后，测试活动将作为 Epic 推送到 Jira。该测试活动内的发现项会作为该 Epic 下的子 Issue 推送，从而在 Jira 的 Epic → Issue 结构中映射出 DefectDojo 的测试活动 → 发现项层级关系。 + +有关此设置的更多信息，请参见 **[启用测试活动 Epic 映射](/connectors/downstream/pro__jira_guide/#enable-engagement-epic-mapping)**。 + +### 测试活动级别的 Jira 设置 + +默认情况下，测试活动会继承其父资产（产品）的 Jira 设置。但是，单个测试活动可以覆盖这些设置，以使用不同的 Jira 配置。以下设置可按测试活动单独自定义： + +- **Project Key（项目密钥）** — 将发现项路由到不同的 Jira 空间 +- **Issue Template（Issue 模板）** — 为该测试活动创建的 Issue 使用不同的模板 +- **Custom Fields（自定义字段）** — 应用不同的自定义字段映射 +- **Jira Labels（Jira 标签）** — 为 Issue 添加该测试活动专属的标签 +- **Default Assignee（默认分配对象）** — 将 Issue 分配给不同的团队成员 + +这些设置可以在 **Edit Engagement（编辑测试活动）** 页面中访问。有关更多详情，请参见 **[测试活动级别的 Jira 设置](/connectors/downstream/pro__jira_guide/#engagement-level-jira-settings)**。 diff --git a/docs/content/asset_modelling/engagements_tests/PRO__findings.it.md b/docs/content/asset_modelling/engagements_tests/PRO__findings.it.md new file mode 100644 index 0000000000..390ad0ba62 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__findings.it.md @@ -0,0 +1,275 @@ +--- +title: Riscontri +description: Comprendere i Riscontri in DefectDojo Pro +audience: pro +weight: 5 +--- + +Organizzazioni → Asset → Engagement → Test → **RISCONTRI** + +## Panoramica +I **Riscontri** rappresentano il livello più basso della Gerarchia dei Prodotti, in cui le singole vulnerabilità vengono tracciate e gestite, e costituiscono il modo principale con cui DefectDojo standardizza e guida il processo di segnalazione e correzione dei tuoi strumenti di sicurezza. Indipendentemente dal fatto che una vulnerabilità sia stata segnalata da SonarQube, Acunetix o dallo strumento personalizzato del tuo team, i Riscontri ti permettono di gestire ogni vulnerabilità nello stesso modo. + +Esempi di Riscontri includono: +- **Cookie non contrassegnato come HttpOnly** +- **Versione obsoleta (PHP)** +- **Valutazione del codice Out-of-Band (PHP)** +- **Versione obsoleta (MySQL)** +- **Codice sorgente di backup rilevato** +- **Cross-Site Scripting cieco** + +Oltre a memorizzare i dati sulle vulnerabilità e fornire un framework di correzione, DefectDojo migliora i tuoi Riscontri anche nei seguenti modi: +- Aggiungendo automaticamente i punteggi EPSS correlati a un Riscontro per descriverne la sfruttabilità +- Traducendo automaticamente la metrica di gravità di uno strumento di sicurezza in un punteggio di Gravità per ogni Riscontro, il che conferisce al Riscontro uno SLA in base alla configurazione SLA del tuo Asset. Per maggiori informazioni sulla configurazione degli SLA, clicca [qui](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas). + +Nel complesso, i Riscontri sono progettati per funzionare insieme alla Gerarchia dei Prodotti al fine di standardizzare i tuoi sforzi e applicare un metodo coerente a ciascun Asset. + +## Accesso ai Riscontri +I Riscontri sono accessibili tramite la barra laterale. Il sottomenu offre l'accesso ai Riscontri Attivi e Mitigati, a Tutti i Riscontri (indipendentemente dallo stato Aperto o Chiuso), ai Gruppi di Riscontri, ai Modelli di Riscontro e al flusso di lavoro per un Nuovo Riscontro. I singoli Riscontri sono accessibili anche dal Test che li contiene. + +[Riscontri con Rischio accettato] (/triage_findings/findings_workflows/os__risk_acceptance/) sono accessibili dalla sezione **Accettazioni del rischio** della barra laterale. + +![image](images/profindings_ss1.png) + +### Autorizzazioni +Ogni Riscontro appartiene a un Test, il che consente a DefectDojo di conservare l'informazione su quale scansione o valutazione ha originariamente identificato la vulnerabilità. + +Poiché i Riscontri appartengono ai Test, l'accesso ai Riscontri è determinato dall'accesso di un Utente all'Asset che contiene il Test. I Test non dispongono di liste di controllo degli accessi indipendenti. + +## Vista dei Riscontri +Le viste dei Riscontri contengono una serie di tabelle che aiutano a interpretare a colpo d'occhio lo stato di un Riscontro. + +### Panoramica del Riscontro +- **Descrizione**: la descrizione del Riscontro (aggiunta automaticamente in base al tipo di Riscontro, oppure creata manualmente). +- **Mitigazione**: i passaggi suggeriti per la mitigazione. +- **Policy di mitigazione generale**: la policy di mitigazione standardizzata per il Riscontro selezionato. +Le policy di mitigazione possono essere trovate e modificate nella barra laterale in **Configurazione** → **Policy di mitigazione**. +- **Impatto**: il potenziale impatto derivante dal non risolvere il Riscontro. +- **Riferimenti**: URL per incrociare la descrizione specifica del Riscontro fornita dallo strumento di scansione di terze parti. Ad esempio, i Riferimenti potrebbero essere collegamenti a una voce pertinente in un catalogo di Riscontri, oppure un singolo URL di un advisory. +- **File**: eventuali file aggiunti per contestualizzare il Riscontro. +- **Note**: le note lasciate dagli Utenti relative al Riscontro. Contrassegnare una nota come Privata significa che non verrà inclusa in nessun report generato che includa il Riscontro selezionato. + +### Metadati +- **ID**: l'ID univoco del Riscontro in DefectDojo. +- **Organizzazione, Asset, Engagement e Test**: gli oggetti superiori del Riscontro selezionato. +- **Stato**: lo stato del Riscontro (ad esempio, Attivo, Verificato, Falso positivo, Duplicato, Fuori ambito e In revisione del difetto). +- **Gravità**: la valutazione di gravità di quel Riscontro, applicata automaticamente. + - Come accennato in precedenza, DefectDojo traduce automaticamente la metrica di gravità di uno strumento di sicurezza in un punteggio di Gravità per ogni Riscontro, il che conferisce al Riscontro uno SLA in base alla configurazione SLA del tuo Asset. +- **Rischio**: un sistema di classificazione a 4 livelli che tiene conto della sfruttabilità di un Riscontro e viene applicato automaticamente. + - I dettagli su come vengono calcolati priorità, rischio e SLA sono disponibili [qui](/asset_modelling/pro_hierarchy/priority_sla/#main-content). Ulteriori dettagli sulle definizioni di stato del Riscontro e di livello di rischio sono disponibili [qui](/triage_findings/findings_workflows/finding_status_definitions/). +- **Priorità**: una classificazione numerica calcolata, applicata a tutti i Riscontri, che consente di comprendere rapidamente le vulnerabilità nel loro contesto. +- **Età**: da quanto tempo esiste il Riscontro selezionato. +- **SLA**: la data entro cui il Riscontro dovrebbe essere risolto. +- **Tipo**: indica se il Riscontro è stato rilevato da uno strumento di sicurezza applicativa statico o dinamico (Statico, Dinamico o Statico/Dinamico). +- **Posizione e riga**: il file e il numero di riga in cui è stato trovato il Riscontro selezionato. +- **Nome e versione del componente**: il nome e la versione del componente in cui è stato trovato il Riscontro selezionato. +- **Data di scoperta**: la data in cui è stato scoperto il Riscontro. +- **Data e versione di correzione pianificata**: la data in cui è pianificata la correzione del Riscontro e la versione del componente interessato in cui verrà implementata la correzione. +- **Servizio**: i Servizi connessi (parti di funzionalità autonome all'interno di un Asset) interessati dal Riscontro selezionato. Quando è compilato, questo campo viene incluso nella corrispondenza per la deduplicazione (ossia, i Riscontri con campi Servizio identici verranno deduplicati). +- **Segnalatore**: l'Utente che ha rilevato il Riscontro. +- **CWE**: la classificazione della debolezza CWE del Riscontro. Un Riscontro può avere **più CWE** — un CWE primario, più eventuali CWE aggiuntivi forniti dallo strumento di segnalazione. Il CWE primario è quello utilizzato per la deduplicazione legacy e per il calcolo dell'hash code; l'intero insieme di CWE può inoltre essere utilizzato per la corrispondenza tramite i campi Hash Code basati su insiemi di Pro (vedi [Ottimizzazione della deduplicazione](/triage_findings/finding_deduplication/pro__deduplication_tuning/#set-based-hash-code-fields-vulnerability-ids-and-cwes)). + - Un CWE descrive una *classe* di debolezza (ad esempio, “SQL Injection”), non un'istanza specifica di vulnerabilità — a questo servono gli ID di vulnerabilità. +- **ID di vulnerabilità**: identificatori di vulnerabilità pubblicamente riconosciuti associati al Riscontro, come CVE, GHSA o altri riferimenti standardizzati di advisory. In DefectDojo Pro, vengono utilizzati anche per eseguire ricerche EPSS e KEV. + - Gli ID di vulnerabilità vengono memorizzati come record di prima classe, quindi lo stesso CVE viene tracciato una sola volta e condiviso da ogni Riscontro che vi fa riferimento. Puoi consultarli — insieme ai relativi valori EPSS e KEV — nell'**Esploratore delle vulnerabilità**. Vedi [EPSS / KEV](/triage_findings/finding_scoring/epss_kev/#viewing-kevepss-in-the-vulnerability-explorer). +- **ID univoco dallo strumento**: un identificatore stabile assegnato dallo strumento di origine a una specifica istanza di Riscontro. Gli ID univoci sono pensati per rimanere coerenti tra scansioni ripetute, consentendo allo strumento di riconoscere lo stesso Riscontro nel tempo. + - A differenza degli ID di vulnerabilità, questo valore è proprietario dello strumento di segnalazione e non è un riferimento pubblico di vulnerabilità. + - Esempio: `finding-12345` +- **ID di vulnerabilità dallo strumento**: un identificatore proprietario di vulnerabilità o regola, assegnato dallo strumento di origine per descrivere il tipo di vulnerabilità rilevata. + - A differenza dell'ID univoco dallo strumento, questo identificatore non è univoco per un singolo Riscontro e può comparire in molti Riscontri che corrispondono alla stessa regola di rilevamento. + - A differenza degli ID di vulnerabilità, questi identificatori sono specifici dello strumento di segnalazione e non sono standardizzati pubblicamente. + - Esempio: `semgrep.rule.lang.security.sql-injection` +- **Punteggio EPSS / Percentile**: il punteggio EPSS e il percentile per il CVE. +- **Sfruttamento noto**: indica se esiste conferma che la vulnerabilità sia stata sfruttata. +- **Ransomware utilizzato**: indica se un ransomware è stato coinvolto nello sfruttamento della vulnerabilità. +- **Data KEV**: la data in cui il Riscontro è stato aggiunto al catalogo KEV. +- **Rilevato da**: il tipo di strumento che ha identificato la vulnerabilità. +- **Vettore e punteggio CVSSv3 e CVSSv4**: il vettore e il punteggio CVSS3 e CVSS4 del Riscontro selezionato. +- **Ticket integratore**: i numeri di ticket del sistema di tracciamento problemi di terze parti associati al Riscontro. + +### Endpoint vulnerabili +Questa sezione include una tabella degli Endpoint interessati dal Riscontro selezionato, insieme a eventuali metadati pertinenti. + +### Dettagli aggiuntivi +- **Coppie richiesta/risposta**: una copia del messaggio inviato dal client e della risposta del server alla richiesta. +- **Passaggi per la riproduzione**: i passaggi per riprodurre il Riscontro. +- **Motivazione della gravità**: descrizione scritta del motivo per cui è stata associata al Riscontro una determinata valutazione di Gravità. + +## Dati dei Riscontri +I Riscontri richiedono i seguenti metadati: +- **Nome** +- **Data** +- **Gravità** +- **Descrizione** + +Oltre ai metadati corrispondenti alle tabelle nella vista di un Riscontro, i campi di metadati opzionali includono: +- **Tag**: eventuali tag aggiunti al Riscontro. +- **Proprietari**: il gruppo di utenti responsabile del Riscontro selezionato. +- **Invia a Jira**: invia il Riscontro a Jira a scopo di ticketing. +- **Invia a Integratore**: invia il Riscontro a qualsiasi sistema di tracciamento problemi di terze parti integrato. +- **Impostazioni di rischio e priorità**: offre la possibilità di sovrascrivere il calcolo automatico di DefectDojo del rischio e della priorità del Riscontro. +- **Endpoint da aggiungere**: endpoint vulnerabili che potrebbero essere interessati dal Riscontro selezionato e che non sono riportati nell'elenco precedente di sistemi/endpoint. +- **Revisione del difetto richiesta da**: registra chi ha richiesto una revisione del difetto per il problema in questione. +- **Oggetto sorgente SAST, numero di riga e percorso del file**: l'oggetto sorgente, il numero di riga e il percorso del file del vettore di attacco. +- **Oggetto sink SAST**: l'oggetto sink del vettore di attacco. +- **Numero di occorrenze**: il numero di occorrenze nello strumento di origine quando più vulnerabilità sono state trovate e aggregate dallo scanner. +- **Data di pubblicazione**: la data in cui la vulnerabilità è stata pubblicata. +- **Stima dello sforzo**: il livello di impegno necessario per correggere il Riscontro (ad esempio, Bassa, Media o Alta). + +I metadati esatti disponibili dipendono dal parser/scanner che ha rilevato il Riscontro. Alcuni forniscono solo informazioni di base come titolo e gravità, mentre altri includono vettori CVSS, componenti vulnerabili, endpoint, coppie richiesta/risposta e altri metadati specifici dello scanner. + +Questi metadati migliorano il filtraggio, la reportistica e la definizione delle priorità nell'intero programma di sicurezza, consentendo un tracciamento a lungo termine e l'analisi delle tendenze. Ulteriori dettagli e descrizioni dei metadati sono disponibili [qui](/triage_findings/findings_workflows/intro_to_findings/#a-finding-page). + +### Deduplicazione +DefectDojo include funzionalità di deduplicazione che aiutano a identificare e gestire i Riscontri che rappresentano la stessa vulnerabilità sottostante. Quando i risultati delle scansioni vengono importati da uno o più strumenti, DefectDojo utilizza una logica di corrispondenza configurabile per identificare i Riscontri che rappresentano la stessa vulnerabilità. + +La deduplicazione evita che la stessa vulnerabilità appaia più volte quando viene rilevata ripetutamente dallo stesso scanner o da scanner diversi, permettendo alla cronologia di correzione di rimanere collegata a un unico Riscontro. + +Ulteriori informazioni sulla deduplicazione sono disponibili [qui](/triage_findings/finding_deduplication/about_deduplication/). + +### Reimportazione +La funzione di Reimportazione di DefectDojo consente di aggiornare i Riscontri man mano che vengono importati nuovi risultati di scansione. Quando una scansione viene reimportata, DefectDojo confronta i risultati in arrivo con i Riscontri esistenti e aggiorna i record corrispondenti invece di crearne di completamente nuovi. Questo preserva informazioni contestuali preziose come i cambiamenti di stato, la cronologia di correzione, i commenti e le informazioni di appartenenza, fornendo un registro continuo del ciclo di vita di un Riscontro attraverso più cicli di test. + +Ulteriori informazioni sulla funzione di Reimportazione sono disponibili [qui](/import_data/import_intro/reimport/). + +### Accettazioni del rischio +Le Accettazioni del rischio sono uno stato speciale che può essere applicato ai Riscontri per documentare formalmente e rendere operativa la decisione di riconoscerli senza correggerli immediatamente. + +Ulteriori informazioni sulle Accettazioni del rischio sono disponibili [qui](/triage_findings/findings_workflows/pro__risk_acceptance/). + +### Stati +Ogni Riscontro creato in DefectDojo ha uno Stato che comunica informazioni rilevanti e aiuta il tuo team a tenere traccia dei progressi nella risoluzione dei problemi. + +Ulteriori informazioni sugli Stati sono disponibili [qui](/triage_findings/findings_workflows/finding_status_definitions/). + +## Lavorare con i Riscontri + +### Creazione dei Riscontri +Sebbene la maggior parte dei Riscontri venga generata automaticamente tramite importazioni di scansioni e integrazioni, DefectDojo supporta anche la creazione manuale dei Riscontri. I Riscontri manuali sono utili per tracciare vulnerabilità e problemi di sicurezza identificati tramite penetration test, revisioni dell'architettura, valutazioni di conformità, programmi di bug bounty, incarichi di consulenza o altre attività che non producono un output da scanner. + +I Riscontri possono essere aggiunti manualmente cliccando su **Nuovo Riscontro** all'interno della sezione **Riscontri** della barra laterale, oppure selezionando **Aggiungi Riscontro** nel menu a ingranaggio del Test a cui si desidera aggiungere il Riscontro. + +### Modifica dei Riscontri +Il menu kebab ⋮ accanto ai Riscontri contiene le seguenti funzioni: +- **Modifica Riscontro**: modifica il Riscontro. +- **Copia Riscontro**: crea una copia del Riscontro in un altro Test. La copia può essere salvata in qualsiasi Test all'interno dello stesso Engagement per cui si dispone dell'autorizzazione di modifica. La copia è utile quando la stessa vulnerabilità deve essere tracciata separatamente in più di un contesto di Test. +- **Chiudi Riscontro**: avvia il processo di chiusura del Riscontro. +- **Richiedi revisione**: avvia il processo di Revisione tra pari e modifica lo stato del Riscontro in “In revisione”. Ulteriori informazioni sulle Revisioni tra pari sono disponibili [qui](/triage_findings/findings_workflows/finding_status_definitions/#under-review). +- **Aggiungi Accettazione del rischio**: avvia il processo di Accettazione del rischio. Ulteriori informazioni sono disponibili [qui](/triage_findings/findings_workflows/pro__risk_acceptance/). +- **Aggiungi file**: avvia il processo per aggiungere un file al Riscontro (vedi la sezione seguente). +- **Aggiungi nota**: avvia il processo per aggiungere una nota al Riscontro. +- **Aggiungi campo personalizzato**: apre una finestra pop-up che consente di aggiungere e definire un campo personalizzato da applicare al Riscontro. +- **Invia a Jira**: invia il Riscontro a Jira a scopo di ticketing. +- **Invia a Integratore**: invia il Riscontro a qualsiasi sistema di tracciamento problemi di terze parti integrato. +- **Elimina Riscontro**: elimina il Riscontro selezionato. +- **Cronologia Riscontro**: mostra la cronologia del Riscontro selezionato. + +#### Allegare file ai Riscontri +Puoi allegare file a qualsiasi Riscontro per fornire un contesto aggiuntivo — ad esempio, uno screenshot di una vulnerabilità in azione o un'immagine di proof-of-concept. + +I tipi di file supportati includono: + +``` +.txt .pdf .json .xml .csv .yml .png .jpeg +.sarif .xlsx .doc .html .js .nessus .zip .fpr +``` + +Per allegare un file a un Riscontro, clicca su **Aggiungi file** dal menu kebab ⋮ oppure dal menu a ingranaggio del Riscontro selezionato. Inserisci un Titolo per il file, scegli il file dal tuo computer e clicca su **Invia**. + +Il file comparirà quindi nella sezione File della tabella **Panoramica del Test** all'interno della vista del Riscontro. + +#### Modifica in blocco dei Riscontri +I Riscontri possono essere modificati in blocco da un elenco di Riscontri, come la tabella di Tutti i Riscontri accessibile dalla barra laterale, oppure dalla tabella dei Riscontri all'interno di un Test specifico. + +Ulteriori informazioni su come modificare in blocco i Riscontri sono disponibili [qui](/triage_findings/findings_workflows/editing_findings/#bulk-edit-findings). + +### Chiusura dei Riscontri +Una volta completato il lavoro su un Riscontro, puoi chiuderlo manualmente cliccando su **Chiudi Riscontro** nel menu kebab ⋮ o nel menu a ingranaggio del Riscontro. In alternativa, se una scansione viene reimportata in DefectDojo e non contiene un Riscontro registrato in precedenza, tale Riscontro verrà chiuso automaticamente. + +Se non desideri che nessun Riscontro venga chiuso, puoi disabilitare questo comportamento nel modulo di Reimportazione della scansione: + +- Deseleziona la casella Chiudi Riscontri obsoleti se utilizzi l'interfaccia utente +- Imposta close_old_findings su False se utilizzi l'API ​ + +### Eliminazione dei Riscontri +L'eliminazione di un Riscontro può essere effettuata dal menu kebab ⋮ o dal menu a ingranaggio del Riscontro. Questa azione non può essere annullata. + +Per finalità di audit, si consiglia di chiudere i Riscontri corretti anziché eliminarli. + +## Gruppi di Riscontri +I **Gruppi di Riscontri** ti permettono di trattare più Riscontri correlati come un'unica unità logica ai fini del triage, della reportistica e del coordinamento della correzione. + +Ad esempio, una scansione potrebbe produrre 10 Riscontri di SQL injection su endpoint diversi. Invece di gestirli singolarmente, puoi raggrupparli in un unico Gruppo di Riscontri che rappresenta il problema più ampio di SQL injection. + +Un Gruppo di Riscontri non sostituisce i singoli Riscontri. Ogni Riscontro continua a esistere con la propria gravità, stato, metadati, commenti e cronologia di correzione. Un Gruppo di Riscontri fornisce semplicemente un ulteriore livello organizzativo al di sopra dei Riscontri che contiene. + +### Accesso ai Gruppi di Riscontri +I Gruppi di Riscontri sono accessibili tramite la barra laterale. Il sottomenu offre l'accesso ai Gruppi di Riscontri Aperti e Chiusi, oltre che a Tutti i Gruppi di Riscontri (indipendentemente dallo stato Aperto). + +![image](images/profindings_ss1.png) + +### Creazione dei Gruppi di Riscontri +I Gruppi di Riscontri possono essere creati manualmente o automaticamente. + +È importante notare che i Gruppi di Riscontri possono essere creati solo a partire dai Riscontri contenuti in un singolo Test. I Riscontri provenienti da Test, Engagement o Prodotti diversi non possono essere aggiunti allo stesso Gruppo di Riscontri. + +#### Gruppi di Riscontri manuali +Per eseguire manualmente le azioni sui Gruppi di Riscontri: +1. Vai a un elenco di Riscontri all'interno di un Test. +2. Seleziona il/i Riscontro/i che desideri aggiungere a un Gruppo di Riscontri cliccando sulla casella di controllo corrispondente. +3. Clicca sul pulsante **Gruppo di Riscontri** che appare nella parte superiore dell'elenco dei Riscontri. +4. Clicca sull'azione corrispondente che desideri eseguire. + - **Aggiungi a nuovo Gruppo di Riscontri**: crea un nuovo Gruppo di Riscontri che include i Riscontri selezionati. + - **Aggiungi a Gruppo di Riscontri esistente**: aggiunge i Riscontri selezionati a un Gruppo di Riscontri preesistente. + - **Rimuovi da Gruppo di Riscontri**: rimuove i Riscontri selezionati da qualsiasi Gruppo di Riscontri di cui facevano precedentemente parte. +5. Clicca su **Invia**. + +Nota che il raggruppamento sarà disabilitato a meno che ogni riscontro selezionato non sia modificabile, non raggruppato e nello stesso Test. + +Inoltre, nota che l'unica azione possibile quando si selezionano Riscontri dall'elenco Tutti i Riscontri è rimuoverli da qualsiasi Gruppo di Riscontri. Questo perché, come accennato, i Gruppi di Riscontri possono essere creati solo a partire dai Riscontri contenuti in un singolo Test. + +#### Gruppi di Riscontri automatici +Durante l'importazione di una scansione, la funzione **Raggruppa per** all'interno del menu a scomparsa **Campi opzionali** può creare automaticamente Gruppi di Riscontri in base a un metodo di raggruppamento scelto. Questo è utile quando uno scanner produce molti Riscontri correlati che dovrebbero essere gestiti insieme. + +La casella di controllo adiacente **Crea Gruppi di Riscontri per tutti i Riscontri** svolge due funzioni: +- **Selezionata**: crea un Gruppo di Riscontri per ogni Riscontro importato, anche se quel Riscontro è l'unico membro del gruppo. +- **Deselezionata**: crea Gruppi di Riscontri solo quando ci sono effettivamente più Riscontri da raggruppare insieme. + +![image](images/profindings_ss2.png) + +Se durante l'importazione non viene selezionata alcuna opzione dal menu a discesa Raggruppa per (ad esempio, **Titolo del Riscontro** nello screenshot sopra, ecc.), non avverrà alcun raggruppamento. + +Se i criteri di raggruppamento (ad esempio, nome del componente, ID di vulnerabilità, titolo del Riscontro, ecc.) non sono compilati nel Riscontro, per esso non verrà creato alcun gruppo né verrà aggiunto a un Gruppo di Riscontri preesistente. + +Se viene importata una scansione che rivela 10 Riscontri non raggruppati e la stessa scansione viene successivamente reimportata con i Riscontri raggruppati, i primi 10 Riscontri non verranno aggiunti a quel Gruppo di Riscontri (ossia, il Gruppo di Riscontri includerà solo i 10 Riscontri della reimportazione, non i 10 Riscontri dell'importazione iniziale). + +## Modelli di Riscontro +I **Modelli di Riscontro** consentono agli Utenti di creare modelli riutilizzabili per vulnerabilità e problemi di sicurezza segnalati di frequente. Un modello può includere informazioni standardizzate come titolo, descrizione, impatto, passaggi per la riproduzione, mitigazione, riferimenti e altri metadati del Riscontro. + +I Modelli di Riscontro sono particolarmente utili nelle situazioni in cui gli Utenti devono creare ripetutamente Riscontri manuali e vogliono evitare di reinserire ogni volta le stesse informazioni di supporto. + +### Accesso ai Modelli di Riscontro +I Modelli di Riscontro si trovano nel sottomenu Riscontri della barra laterale. + +![image](images/profindings_ss1.png) + +### Creazione dei Modelli di Riscontro +I Modelli di Riscontro possono essere creati cliccando sul pulsante **Nuovo Modello di Riscontro** in alto a sinistra nella vista Modelli di Riscontro. + +La pagina successiva fornisce una panoramica dei metadati che verranno applicati a un Riscontro quando si utilizza un Modello di Riscontro. + +### Applicazione dei Modelli di Riscontro +I Modelli di Riscontro differiscono tra DefectDojo OS e DefectDojo Pro. In Pro, i Modelli di Riscontro non possono essere applicati a Riscontri preesistenti, né possono essere creati sulla base di Riscontri preesistenti. + +Tuttavia, puoi aggiungere manualmente un Riscontro a un Test basato su un Modello di Riscontro utilizzando il menu kebab ⋮ accanto al Test nella vista dell'Engagement principale, oppure utilizzando il menu a ingranaggio nella vista del Test. + +![image](images/profindings_ss3.png) + +![image](images/profindings_ss4.png) + +## Reportistica +Il generatore di report di DefectDojo ti consente di assemblare un report personalizzato a partire da un insieme di widget di contenuto, eseguirlo ed esportare il risultato (ad esempio, stampandolo in PDF). I report personalizzati possono riassumere i Riscontri o gli Endpoint che desideri condividere con un pubblico esterno e possono includere branding e testo standard. + +Ulteriori informazioni sul Generatore di report di DefectDojo sono disponibili [qui](/metrics_reports/reports/report-builder/). + +### Esportazione dei Riscontri +Le pagine che mostrano un elenco di Riscontri o un elenco di Engagement dispongono di un'opzione di esportazione CSV ed Excel in alto a sinistra. Per i Riscontri, è disponibile anche l'opzione per eseguire un'Esportazione rapida, che aprirà una nuova scheda con tabelle di metadati relativi a ciascun Riscontro. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__findings.pt-br.md b/docs/content/asset_modelling/engagements_tests/PRO__findings.pt-br.md new file mode 100644 index 0000000000..47f2872db7 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__findings.pt-br.md @@ -0,0 +1,275 @@ +--- +title: Achados +description: Entendendo os Achados no DefectDojo Pro +audience: pro +weight: 5 +--- + +Organizations → Assets → Engagements → Tests → **FINDINGS** + +## Overview +**Achados** representam o nível mais baixo da Hierarquia de Produtos, onde vulnerabilidades individuais são rastreadas e gerenciadas, e servem como a principal forma pela qual o DefectDojo padroniza e orienta o processo de reporte e remediação das suas ferramentas de segurança. Independentemente de uma vulnerabilidade ter sido reportada no SonarQube, Acunetix ou na ferramenta personalizada da sua equipe, os Achados oferecem a capacidade de gerenciar cada vulnerabilidade da mesma forma. + +Exemplos de Achados incluem: +- **Cookie Não Marcado como HttpOnly** +- **Versão Desatualizada (PHP)** +- **Avaliação de Código Fora de Banda (PHP)** +- **Versão Desatualizada (MySQL)** +- **Código-Fonte de Backup Detectado** +- **Cross-Site Scripting Cego** + +Além de armazenar os dados da vulnerabilidade e fornecer um framework de remediação, o DefectDojo também aprimora seus Achados das seguintes formas: +- Adicionando automaticamente as pontuações EPSS relacionadas a um Achado para descrever sua explorabilidade +- Traduzindo automaticamente a métrica de severidade de uma ferramenta de segurança em uma pontuação de Severidade para cada Achado, o que atribui um SLA ao Achado de acordo com a configuração de SLA do seu Ativo. Para mais informações sobre a configuração de SLA, clique [aqui](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas). + +No geral, os Achados são projetados para funcionar com a Hierarquia de Produtos, padronizando seus esforços e aplicando um método consistente a cada Ativo. + +## Accessing Findings +Os Achados são acessíveis pela barra lateral. O submenu oferece acesso aos Achados Ativos e Mitigados, Todos os Achados (independentemente do status Aberto ou Fechado), Grupos de Achados, Modelos de Achados e o fluxo de Novo Achado. Achados individuais também são acessíveis a partir do Teste que os contém. + +[Achados com Risco Aceito] (/triage_findings/findings_workflows/os__risk_acceptance/) são acessíveis a partir da seção **Aceitações de Risco** da barra lateral. + +![image](images/profindings_ss1.png) + +### Permissions +Todo Achado pertence a um Teste, o que permite que o DefectDojo preserve qual scan ou avaliação identificou originalmente a vulnerabilidade. + +Como os Achados pertencem a Testes, o acesso aos Achados é determinado pelo acesso do Usuário ao Ativo que contém o Teste. Os Testes não possuem listas de controle de acesso independentes. + +## Findings View +As visualizações de Achado contêm uma variedade de tabelas para ajudar a interpretar o status de um Achado rapidamente. + +### Finding Overview +- **Descrição**: A descrição do Achado (adicionada automaticamente dependendo do tipo de Achado, ou criada manualmente). +- **Mitigação**: Passos sugeridos para mitigar. +- **Política de Mitigação Geral**: A política de mitigação padronizada para o Achado selecionado. +As políticas de mitigação podem ser encontradas e editadas na barra lateral em **Configuration** → **Mitigation Policies**. +- **Impacto**: Impacto potencial de deixar o Achado sem solução. +- **Referências**: URL para referência cruzada com a descrição específica que a ferramenta de scan de terceiros dá ao Achado. Por exemplo, as Referências podem ser links para uma entrada relevante em um catálogo de Achados, ou uma única URL de advisory. +- **Arquivos**: Quaisquer arquivos que tenham sido adicionados para contextualizar o Achado. +- **Notas**: Notas deixadas por Usuários relacionadas ao Achado. Marcar uma nota como Privada significa que ela não será incluída em nenhum relatório gerado que contenha o Achado selecionado. + +### Metadata +- **ID**: O ID exclusivo do Achado no DefectDojo. +- **Organização, Ativo, Engajamento e Teste**: Os objetos pai do Achado selecionado. +- **Status**: O status do Achado (por exemplo, Ativo, Verificado, Falso positivo, Duplicado, Fora do escopo e Em Revisão de Defeito). +- **Severidade**: A classificação de severidade daquele Achado, aplicada automaticamente. + - Como mencionado acima, o DefectDojo traduz automaticamente a métrica de severidade de uma ferramenta de segurança em uma pontuação de Severidade para cada Achado, o que atribui um SLA ao Achado de acordo com a configuração de SLA do seu Ativo. +- **Risco**: Um sistema de classificação de 4 níveis que leva em conta a explorabilidade de um Achado e é aplicado automaticamente. + - Detalhes sobre como a prioridade, o risco e os SLAs são calculados podem ser encontrados [aqui](/asset_modelling/pro_hierarchy/priority_sla/#main-content). Mais detalhes sobre as definições de status e nível de risco do Achado podem ser encontrados [aqui](/triage_findings/findings_workflows/finding_status_definitions/). +- **Prioridade**: Uma classificação numérica calculada, aplicada a todos os Achados, que permite entender rapidamente as vulnerabilidades em contexto. +- **Idade**: Há quanto tempo existe o Achado selecionado. +- **SLA**: A data limite prevista para a resolução do Achado. +- **Tipo**: Se o Achado foi detectado por uma ferramenta de segurança de aplicação estática ou dinâmica (Static, Dynamic ou Static/Dynamic). +- **Localização e Linha**: O arquivo e o número da linha em que o Achado selecionado foi encontrado. +- **Nome e Versão do Componente**: O nome e a versão do componente em que o Achado selecionado foi encontrado. +- **Data de Descoberta**: A data em que o Achado foi descoberto. +- **Data e Versão de Remediação Planejada**: A data em que o Achado deve ser remediado, e a versão do componente afetado na qual a correção será implementada. +- **Serviço**: Serviços Conectados (partes autocontidas de funcionalidade dentro de um Ativo) que são afetados pelo Achado selecionado. Quando preenchido, esse campo é incluído na correspondência de deduplicação (ou seja, Achados com campos de Serviço idênticos serão deduplicados). +- **Relator**: O Usuário que revelou o Achado. +- **CWE**: A classificação de fraqueza CWE do Achado. Um Achado pode ter **múltiplos CWEs** — um CWE primário, mais quaisquer CWEs adicionais fornecidos pela ferramenta de reporte. O CWE primário é o utilizado para deduplicação legada e cálculo de hash code; o conjunto completo de CWEs também pode ser usado para correspondência por meio dos Hash Code Fields baseados em conjunto do Pro (veja [Ajuste de Deduplicação](/triage_findings/finding_deduplication/pro__deduplication_tuning/#set-based-hash-code-fields-vulnerability-ids-and-cwes)). + - Um CWE descreve uma *classe* de fraqueza (por exemplo, "SQL Injection"), não uma instância específica de vulnerabilidade — é para isso que servem os IDs de Vulnerabilidade. +- **IDs de Vulnerabilidade**: Identificadores de vulnerabilidade publicamente reconhecidos associados ao Achado, como CVE, GHSA, ou outras referências de advisory padronizadas. No DefectDojo Pro, eles também são usados para realizar consultas de EPSS e KEV. + - Os IDs de Vulnerabilidade são armazenados como registros de primeira classe, de modo que o mesmo CVE é rastreado uma única vez e compartilhado por todo Achado que o referencia. Você pode revisá-los — junto com seus valores de EPSS e KEV — no **Vulnerability Explorer**. Veja [EPSS / KEV](/triage_findings/finding_scoring/epss_kev/#viewing-kevepss-in-the-vulnerability-explorer). +- **Unique ID From Tool**: Um identificador estável atribuído pela ferramenta de origem a uma instância específica de Achado. Os Unique IDs devem permanecer consistentes entre scans repetidos, permitindo que a ferramenta reconheça o mesmo Achado ao longo do tempo. + - Diferentemente dos IDs de Vulnerabilidade, esse valor é proprietário da ferramenta de reporte e não é uma referência pública de vulnerabilidade. + - Exemplo: `finding-12345` +- **Vulnerability ID From Tool**: Um identificador proprietário de vulnerabilidade ou regra, atribuído pela ferramenta de origem para descrever o tipo de vulnerabilidade detectada. + - Diferentemente do Unique ID From Tool, esse identificador não é exclusivo de um Achado individual e pode aparecer em vários Achados que correspondem à mesma regra de detecção. + - Diferentemente dos IDs de Vulnerabilidade, esses identificadores são específicos da ferramenta de reporte e não são padronizados publicamente. + - Exemplo: `semgrep.rule.lang.security.sql-injection` +- **EPSS Score / Percentile**: A pontuação e o percentil de EPSS para o CVE. +- **Known Exploited**: Se há confirmação de que a vulnerabilidade foi explorada. +- **Ransomware Used**: Se houve uso de ransomware na exploração da vulnerabilidade. +- **KEV Date**: A data em que o Achado foi adicionado ao catálogo KEV. +- **Found By**: O tipo de ferramenta que identificou a vulnerabilidade. +- **CVSSv3 and CVSSv4 Vector and Score**: O vetor e a pontuação CVSS3 e CVSS4 do Achado selecionado. +- **Integrator Tickets**: Números de tickets de rastreadores de issues de terceiros associados ao Achado. + +### Vulnerable Endpoints +Esta seção inclui uma tabela dos Endpoints afetados pelo Achado selecionado, junto com quaisquer metadados relevantes. + +### Additional Details +- **Request/Response Pairs**: Uma cópia da mensagem enviada pelo cliente e da resposta do servidor à requisição. +- **Steps to Reproduce**: Passos para reproduzir o Achado. +- **Severity Justification**: Descrição por escrito de por que uma determinada classificação de Severidade foi associada ao Achado. + +## Findings Data +Os Achados exigem os seguintes metadados: +- **Nome** +- **Data** +- **Severidade** +- **Descrição** + +Além dos metadados correspondentes às tabelas na visualização de um Achado, os campos de metadados opcionais incluem: +- **Tags**: Quaisquer tags que tenham sido adicionadas ao Achado. +- **Owners**: O grupo de usuários que será responsável pelo Achado selecionado. +- **Push to Jira**: Envia o Achado para o Jira para fins de emissão de tickets. +- **Push to Integrator**: Envia o Achado para quaisquer rastreadores de issues de terceiros integrados. +- **Configurações de risco e prioridade**: Oferece a opção de substituir o cálculo automático que o DefectDojo faz do risco e da prioridade do Achado. +- **Endpoints a adicionar**: Endpoints vulneráveis que podem ser afetados pelo Achado selecionado e que não estão refletidos na lista anterior de sistemas/endpoints. +- **Revisão de defeito solicitada por**: Registra quem solicitou uma revisão de defeito para a falha em questão. +- **Objeto de origem SAST, número da linha e caminho do arquivo**: Objeto de origem, número da linha e caminho do arquivo do vetor de ataque. +- **Objeto de destino (sink) SAST**: Objeto de destino do vetor de ataque. +- **Número de ocorrências**: Número de ocorrências na ferramenta de origem quando várias vulnerabilidades foram encontradas e agregadas pelo scanner. +- **Data de publicação**: A data em que a vulnerabilidade foi publicada. +- **Estimativa de esforço**: O nível de esforço envolvido na correção do Achado (por exemplo, Baixo, Médio ou Alto). + +Os metadados exatos disponíveis dependerão do parser/scanner que revelou o Achado. Alguns fornecem apenas informações básicas, como título e severidade, enquanto outros incluem vetores CVSS, componentes vulneráveis, endpoints, pares de requisição/resposta e outros metadados específicos do scanner. + +Esses metadados melhoram a filtragem, os relatórios e a priorização em todo o seu programa de segurança, permitindo o rastreamento de longo prazo e a análise de tendências. Detalhes adicionais e descrições de metadados podem ser encontrados [aqui](/triage_findings/findings_workflows/intro_to_findings/#a-finding-page). + +### Deduplication +O DefectDojo inclui recursos de deduplicação que ajudam a identificar e gerenciar Achados que representam a mesma vulnerabilidade subjacente. À medida que os resultados de scan são importados de uma ou mais ferramentas, o DefectDojo usa uma lógica de correspondência configurável para identificar Achados que representam a mesma vulnerabilidade. + +A deduplicação evita que a mesma vulnerabilidade apareça múltiplas vezes quando descoberta repetidamente pelo mesmo scanner ou por scanners diferentes, permitindo que o histórico de remediação permaneça vinculado a um único Achado. + +Mais informações sobre deduplicação podem ser encontradas [aqui](/triage_findings/finding_deduplication/about_deduplication/). + +### Reimport +A função de Reimportação do DefectDojo permite que os Achados sejam atualizados à medida que novos resultados de scan são importados. Quando um scan é reimportado, o DefectDojo compara os resultados recebidos com os Achados existentes e atualiza os registros correspondentes em vez de criar registros inteiramente novos. Isso preserva contexto valioso, como mudanças de status, histórico de remediação, comentários e informações de propriedade, fornecendo um registro contínuo do ciclo de vida de um Achado ao longo de múltiplos ciclos de teste. + +Mais informações sobre a função de Reimportação podem ser encontradas [aqui](/import_data/import_intro/reimport/). + +### Risk Acceptances +As Aceitações de Risco são um status especial que pode ser aplicado aos Achados para documentar formalmente e operacionalizar a decisão de reconhecê-los sem remediá-los imediatamente. + +Mais informações sobre Aceitações de Risco podem ser encontradas [aqui](/triage_findings/findings_workflows/pro__risk_acceptance/). + +### Statuses +Cada Achado criado no DefectDojo possui um Status que comunica informações relevantes e ajuda sua equipe a acompanhar o progresso na resolução dos problemas. + +Mais informações sobre Status podem ser encontradas [aqui](/triage_findings/findings_workflows/finding_status_definitions/). + +## Working with Findings + +### Creating Findings +Embora a maioria dos Achados seja gerada automaticamente por meio de importações de scan e integrações, o DefectDojo também oferece suporte à criação manual de Achados. Achados manuais são úteis para rastrear vulnerabilidades e questões de segurança identificadas por meio de testes de penetração, revisões de arquitetura, avaliações de conformidade, programas de bug bounty, engajamentos de consultoria ou outras atividades que não produzem saída de scanner. + +Os Achados podem ser adicionados manualmente clicando em **Novo Achado** na seção **Findings** da barra lateral, ou selecionando **Adicionar Achado** no menu de engrenagem do Teste ao qual você deseja adicionar o Achado. + +### Editing Findings +O menu kebab ⋮ ao lado dos Achados contém as seguintes funções: +- **Editar Achado**: Edita o Achado. +- **Copiar Achado**: Cria uma cópia do Achado em outro Teste. A cópia pode ser salva em qualquer Teste dentro do mesmo Engajamento para o qual você tenha permissão de edição. Copiar é útil quando a mesma vulnerabilidade precisa ser rastreada separadamente em mais de um contexto de Teste. +- **Fechar Achado**: Inicia o processo de fechamento do Achado. +- **Solicitar Revisão**: Inicia o processo de Revisão por Pares e altera o status do Achado para "Under Review." Mais informações sobre Revisões por Pares podem ser encontradas [aqui](/triage_findings/findings_workflows/finding_status_definitions/#under-review). +- **Adicionar Aceitação de Risco**: Inicia o processo de Aceitação de Risco. Mais informações podem ser encontradas [aqui](/triage_findings/findings_workflows/pro__risk_acceptance/). +- **Adicionar Arquivo**: Inicia o processo de adicionar um arquivo ao Achado (veja a seção abaixo). +- **Adicionar Nota**: Inicia o processo de adicionar uma nota ao Achado. +- **Adicionar Campo Personalizado**: Abre um pop-up que permite adicionar e definir um campo personalizado para aplicar ao Achado. +- **Push to Jira**: Envia o Achado para o Jira para fins de emissão de tickets. +- **Push to Integrator**: Envia o Achado para quaisquer rastreadores de issues de terceiros integrados. +- **Excluir Achado**: Exclui o Achado selecionado. +- **Histórico do Achado**: Revela o histórico do Achado selecionado. + +#### Attaching Files to Findings +Você pode anexar arquivos a qualquer Achado para fornecer contexto adicional — por exemplo, uma captura de tela de uma vulnerabilidade em ação ou uma imagem de prova de conceito. + +Os tipos de arquivo suportados incluem: + +``` +.txt .pdf .json .xml .csv .yml .png .jpeg +.sarif .xlsx .doc .html .js .nessus .zip .fpr +``` + +Para anexar um arquivo a um Achado, clique em **Adicionar Arquivo** no menu kebab ⋮ ou no menu de engrenagem do Achado selecionado. Digite um Título para o arquivo, escolha o arquivo no seu computador e clique em **Enviar**. + +O arquivo então aparecerá na seção Arquivos da tabela **Test Overview** dentro da visualização do Achado. + +#### Bulk Edit Findings +Os Achados podem ser editados em massa a partir de uma Lista de Achados, como a tabela de Todos os Achados acessível pela barra lateral, ou a partir da tabela de Achados dentro de um Teste específico. + +Mais informações sobre como editar Achados em massa podem ser encontradas [aqui](/triage_findings/findings_workflows/editing_findings/#bulk-edit-findings). + +### Closing Findings +Depois que o trabalho em um Achado for concluído, você pode fechá-lo manualmente clicando em **Fechar Achado** no menu kebab ⋮ ou no menu de engrenagem do Achado. Alternativamente, se um scan for reimportado no DefectDojo e não contiver um Achado registrado anteriormente, esse Achado registrado anteriormente será fechado automaticamente. + +Se você não quiser que nenhum Achado seja fechado, é possível desabilitar esse comportamento no formulário de Reimportação de Scan: + +- Desmarque a caixa de seleção Close Old Findings se estiver usando a UI +- Defina close_old_findings como False se estiver usando a API ​ + +### Deleting Findings +A exclusão de um Achado pode ser feita a partir do menu kebab ⋮ ou do menu de engrenagem do Achado. Essa ação não pode ser desfeita. + +Para fins de auditoria, recomenda-se fechar os Achados remediados em vez de excluí-los. + +## Finding Groups +**Grupos de Achados** permitem tratar múltiplos Achados relacionados como uma única unidade lógica para triagem, relatórios e coordenação de remediação. + +Por exemplo, um scan pode produzir 10 Achados de SQL injection em diferentes endpoints. Em vez de gerenciar cada um independentemente, você pode agrupá-los em um único Grupo de Achados que represente o problema mais amplo de SQL injection. + +Um Grupo de Achados não substitui os Achados individuais. Cada Achado continua existindo com sua própria severidade, status, metadados, comentários e histórico de remediação. Um Grupo de Achados simplesmente fornece uma camada organizacional adicional acima dos Achados que ele contém. + +### Accessing Finding Groups +Os Grupos de Achados podem ser acessados pela barra lateral. O submenu oferece acesso aos Grupos de Achados Abertos e Fechados, bem como a Todos os Grupos de Achados (independentemente do status de Aberto). + +![image](images/profindings_ss1.png) + +### Creating Finding Groups +Os Grupos de Achados podem ser criados manualmente ou automaticamente. + +Vale destacar que os Grupos de Achados só podem ser criados a partir dos Achados contidos em um único Teste. Achados de Testes, Engajamentos ou Produtos diferentes não podem ser adicionados ao mesmo Grupo de Achados. + +#### Manual Finding Groups +Para realizar ações de Grupo de Achados manualmente: +1. Navegue até uma lista de Achados dentro de um Teste. +2. Selecione o(s) Achado(s) que deseja adicionar a um Grupo de Achados clicando na caixa de seleção correspondente do Achado. +3. Clique no botão **Finding Group** que aparece no topo da lista de Achados. +4. Clique na ação correspondente que deseja realizar. + - **Adicionar a Novo Grupo de Achados**: Cria um novo Grupo de Achados que inclui os Achados selecionados. + - **Adicionar a Grupo de Achados Existente**: Adiciona os Achados selecionados a um Grupo de Achados pré-existente. + - **Remover de Grupo de Achados**: Remove os Achados selecionados de quaisquer Grupos de Achados dos quais faziam parte anteriormente. +5. Clique em **Enviar**. + +Observe que o agrupamento ficará desabilitado a menos que todo achado selecionado seja editável, não esteja agrupado e esteja no mesmo Teste. + +Além disso, observe que a única ação possível ao selecionar Achados na lista Todos os Achados é remover os Achados selecionados de qualquer Grupo de Achados. Isso ocorre porque, como mencionado, os Grupos de Achados só podem ser criados a partir dos Achados contidos em um único Teste. + +#### Automatic Finding Groups +Ao importar um scan, o recurso **Group By** dentro do menu recolhível **Optional Fields** pode criar Grupos de Achados automaticamente com base em um método de agrupamento escolhido. Isso é útil quando um scanner produz muitos Achados relacionados que devem ser gerenciados em conjunto. + +A caixa de seleção adjacente **Create Finding Groups for all Findings** desempenha duas funções: +- **Marcada**: Cria um Grupo de Achados para cada Achado importado, mesmo que esse Achado seja o único membro do grupo. +- **Desmarcada**: Cria Grupos de Achados somente quando há de fato múltiplos Achados para agrupar. + +![image](images/profindings_ss2.png) + +Se nenhuma opção for selecionada no menu suspenso Group By durante a importação (por exemplo, **Finding Title** na captura de tela acima, etc.), nenhum agrupamento ocorrerá. + +Se o critério de agrupamento (por exemplo, nome do componente, ID de vulnerabilidade, título do Achado, etc.) não estiver preenchido no Achado, nenhum grupo será criado para ele, nem ele será adicionado a um Grupo de Achados pré-existente. + +Se um scan for importado e revelar 10 Achados que não são agrupados, e o mesmo scan for reimportado com os Achados agrupados, os 10 primeiros Achados não serão adicionados a esse Grupo de Achados (ou seja, o Grupo de Achados incluirá apenas os 10 Achados da reimportação, não os 10 Achados da importação inicial). + +## Finding Templates +**Modelos de Achado** permitem que os Usuários criem modelos reutilizáveis para vulnerabilidades e questões de segurança relatadas com frequência. Um modelo pode incluir informações padronizadas, como título, descrição, impacto, passos para reproduzir, mitigação, referências e outros metadados do Achado. + +Os Modelos de Achado são mais úteis em situações em que os Usuários precisam criar Achados manuais repetidamente e desejam evitar reinserir as mesmas informações de apoio a cada vez. + +### Accessing Finding Templates +Os Modelos de Achado são encontrados no submenu Findings, na barra lateral. + +![image](images/profindings_ss1.png) + +### Creating Finding Templates +Os Modelos de Achado podem ser criados clicando no botão **New Finding Template** no canto superior esquerdo da visualização de Modelos de Achado. + +A página seguinte fornece uma visão geral dos metadados que serão aplicados a um Achado quando um Modelo de Achado for usado. + +### Applying Finding Templates +Os Modelos de Achado diferem entre o DefectDojo OS e o DefectDojo Pro. No Pro, os Modelos de Achado não podem ser aplicados a Achados pré-existentes, nem podem ser criados a partir de Achados pré-existentes. + +No entanto, você pode adicionar manualmente um Achado a um Teste com base em um Modelo de Achado usando o menu kebab ⋮ ao lado do Teste na visualização do Engajamento pai, ou usando o menu de engrenagem na visualização do Teste. + +![image](images/profindings_ss3.png) + +![image](images/profindings_ss4.png) + +## Reporting +O construtor de relatórios do DefectDojo permite montar um relatório personalizado a partir de um conjunto de widgets de conteúdo, executá-lo e exportar o resultado (por exemplo, imprimindo-o em PDF). Relatórios personalizados podem resumir os Achados ou Endpoints que você deseja compartilhar com um público externo, e podem incluir branding e texto padrão. + +Mais informações sobre o Report Builder do DefectDojo podem ser encontradas [aqui](/metrics_reports/reports/report-builder/). + +### Export Findings +Páginas que exibem uma lista de Achados ou uma lista de Engajamentos possuem uma opção de exportação em CSV e Excel no canto superior esquerdo. Para Achados, também há a opção de realizar uma Exportação Rápida, que abrirá uma nova aba com tabelas de metadados referentes a cada Achado. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__findings.zh-hans.md b/docs/content/asset_modelling/engagements_tests/PRO__findings.zh-hans.md new file mode 100644 index 0000000000..5274df674c --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__findings.zh-hans.md @@ -0,0 +1,275 @@ +--- +title: 发现项 +description: 了解 DefectDojo Pro 中的发现项 +audience: pro +weight: 5 +--- + +组织 → 资产 → 测试活动 → 测试 → **发现项** + +## 概述 +**发现项**是产品层级结构中的最底层,用于跟踪和管理各个漏洞,是 DefectDojo 规范并指导安全工具报告与修复流程的主要方式。无论漏洞是由 SonarQube、Acunetix 报告,还是由您团队的自定义工具报告,发现项都能让您以相同的方式管理每一个漏洞。 + +发现项示例包括: +- **Cookie 未标记为 HttpOnly** +- **版本过旧(PHP)** +- **带外代码执行(PHP)** +- **版本过旧(MySQL)** +- **检测到备份源代码** +- **盲跨站脚本** + +除了存储漏洞数据并提供修复框架外,DefectDojo 还通过以下方式增强您的发现项: +- 自动为发现项添加相关的 EPSS 分数,以描述其可利用性 +- 自动将安全工具的严重程度指标转换为每个发现项的严重程度分数,并根据您资产的 SLA 配置为该发现项设定 SLA。有关 SLA 配置的更多信息,请点击[此处](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas)。 + +总体而言,发现项旨在与产品层级结构协同工作,规范您的工作,并对每个资产应用一致的方法。 + +## 访问发现项 +可以通过侧边栏访问发现项。子菜单提供对活动和已缓解发现项、所有发现项(无论开启或关闭状态)、发现项组、发现项模板以及新建发现项工作流程的访问。也可以在包含相应发现项的测试内访问各个发现项。 + +[风险已接受的发现项] (/triage_findings/findings_workflows/os__risk_acceptance/) 可以从侧边栏的**风险接受**部分访问。 + +![image](images/profindings_ss1.png) + +### 权限 +每个发现项都属于某个测试,这使 DefectDojo 能够保留最初发现该漏洞的扫描或评估记录。 + +由于发现项属于测试,对发现项的访问权限由用户对包含该测试的资产的访问权限决定。测试没有独立的访问控制列表。 + +## 发现项视图 +发现项视图包含多种表格,帮助您一目了然地了解发现项的状态。 + +### 发现项概览 +- **描述**:发现项的描述(根据发现项类型自动添加,或手动创建)。 +- **缓解措施**:建议的缓解步骤。 +- **通用缓解策略**:所选发现项的标准化缓解策略。 +缓解策略可以在侧边栏的**配置** → **缓解策略**中查找和编辑。 +- **影响**:未解决该发现项可能造成的潜在影响。 +- **参考资料**:用于交叉引用第三方扫描工具对该发现项具体描述的 URL。例如,参考资料可以是指向发现项目录中相关条目的链接,或单个公告 URL。 +- **文件**:为该发现项添加的用于提供背景信息的任何文件。 +- **备注**:用户就该发现项留下的备注。将备注标记为私密将意味着它不会包含在任何包含所选发现项的生成报告中。 + +### 元数据 +- **ID**:DefectDojo 的唯一发现项 ID。 +- **组织、资产、测试活动和测试**:所选发现项的父级对象。 +- **状态**:发现项的状态(例如,活动、已验证、误报、重复、超出范围和缺陷审查中)。 +- **严重程度**:该发现项的严重程度等级,自动应用。 + - 如上所述,DefectDojo 会自动将安全工具的严重程度指标转换为每个发现项的严重程度分数,并根据您资产的 SLA 配置为该发现项设定 SLA。 +- **风险**:一个考虑发现项可利用性的 4 级排名系统,自动应用。 + - 有关优先级、风险和 SLA 如何计算的详细信息,请参见[此处](/asset_modelling/pro_hierarchy/priority_sla/#main-content)。有关发现项状态和风险等级定义的更多详情,请参见[此处](/triage_findings/findings_workflows/finding_status_definitions/)。 +- **优先级**:应用于所有发现项的计算数值排名,使您能够在上下文中快速了解漏洞情况。 +- **存续时间**:所选发现项存在的时长。 +- **SLA**:发现项计划解决的截止日期。 +- **类型**:发现项是通过静态还是动态应用安全工具检测到的(静态、动态或静态/动态)。 +- **位置和行号**:发现所选发现项的文件和行号。 +- **组件名称和版本**:发现所选发现项的组件的名称和版本。 +- **发现日期**:发现该发现项的日期。 +- **计划修复日期和版本**:计划修复该发现项的日期,以及将实施修复的受影响组件版本。 +- **服务**:受所选发现项影响的关联服务(资产内自成一体的功能单元)。填写该字段后,它将被纳入去重匹配(即服务字段相同的发现项将被去重)。 +- **报告人**:发现该发现项的用户。 +- **CWE**:发现项的 CWE 弱点分类。一个发现项可以携带**多个 CWE**——一个主要 CWE,加上报告工具提供的任何附加 CWE。主要 CWE 用于传统去重和哈希码计算;完整的 CWE 集合还可以通过 Pro 版基于集合的哈希码字段用于匹配(参见[去重调优](/triage_findings/finding_deduplication/pro__deduplication_tuning/#set-based-hash-code-fields-vulnerability-ids-and-cwes))。 + - CWE 描述的是一类*弱点*(例如“SQL 注入”),而不是特定的漏洞实例——后者是漏洞 ID 的作用。 +- **漏洞 ID**:与发现项关联的公开认可的漏洞标识符,例如 CVE、GHSA 或其他标准化公告引用。在 DefectDojo Pro 中,它们还用于执行 EPSS 和 KEV 查询。 + - 漏洞 ID 作为一等记录存储,因此同一个 CVE 只会被跟踪一次,并由引用它的每个发现项共享。您可以在**漏洞浏览器**中查看它们及其 EPSS 和 KEV 值。参见 [EPSS / KEV](/triage_findings/finding_scoring/epss_kev/#viewing-kevepss-in-the-vulnerability-explorer)。 +- **来自工具的唯一 ID**:由来源工具分配给特定发现项实例的稳定标识符。唯一 ID 旨在跨重复扫描保持一致,使工具能够长期识别同一发现项。 + - 与漏洞 ID 不同,该值是报告工具专有的,不是公开的漏洞引用。 + - 示例:`finding-12345` +- **来自工具的漏洞 ID**:由来源工具分配的专有漏洞或规则标识符,用于描述所检测到的漏洞类型。 + - 与来自工具的唯一 ID 不同,该标识符并非某个发现项独有,可能出现在多个匹配同一检测规则的发现项上。 + - 与漏洞 ID 不同,这些标识符特定于报告工具,并未公开标准化。 + - 示例:`semgrep.rule.lang.security.sql-injection` +- **EPSS 分数/百分位**:该 CVE 的 EPSS 分数和百分位。 +- **已知被利用**:是否已确认该漏洞已被利用。 +- **涉及勒索软件**:该漏洞的利用是否涉及勒索软件。 +- **KEV 日期**:该发现项被添加到 KEV 目录的日期。 +- **发现工具**:识别该漏洞的工具类型。 +- **CVSSv3 和 CVSSv4 向量与分数**:所选发现项的 CVSS3 和 CVSS4 向量与分数。 +- **集成器工单**:与发现项关联的第三方问题跟踪系统工单编号。 + +### 易受攻击的端点 +本节包含所选发现项所影响的端点表格,以及任何相关的元数据。 + +### 其他详情 +- **请求/响应对**:客户端发送的消息副本及服务器对该请求的回复。 +- **重现步骤**:重现该发现项的步骤。 +- **严重程度说明**:说明为何该发现项被赋予特定严重程度等级的书面描述。 + +## 发现项数据 +发现项需要以下元数据: +- **名称** +- **日期** +- **严重程度** +- **描述** + +除了与发现项视图中的表格相对应的元数据外,可选元数据字段还包括: +- **标签**:已添加到该发现项的任何标签。 +- **负责人**:将负责所选发现项的用户组。 +- **推送到 Jira**:将发现项推送到 Jira 以创建工单。 +- **推送到集成器**:将发现项推送到任何已集成的第三方问题跟踪系统。 +- **风险和优先级设置**:提供覆盖 DefectDojo 对发现项风险和优先级自动计算结果的选项。 +- **要添加的端点**:可能受所选发现项影响、但未反映在上述系统/端点列表中的易受攻击端点。 +- **缺陷审查请求人**:记录是谁请求对相关缺陷进行审查。 +- **SAST 源对象、行号和文件路径**:攻击向量的源对象、行号和文件路径。 +- **SAST 汇聚对象**:攻击向量的汇聚对象。 +- **出现次数**:当扫描器发现并聚合多个漏洞时,源工具中记录的出现次数。 +- **发布日期**:该漏洞的发布日期。 +- **工作量估计**:修复该发现项所需的工作量级别(例如,低、中或高)。 + +具体可用的元数据取决于揭示该发现项的解析器/扫描器。有些解析器/扫描器只提供标题和严重程度等基本信息,而另一些则包括 CVSS 向量、易受攻击的组件、端点、请求/响应对以及其他特定于扫描器的元数据。 + +这些元数据可改善您整个安全计划中的筛选、报告和优先级排序,并支持长期跟踪和趋势分析。更多详情和元数据说明,请参见[此处](/triage_findings/findings_workflows/intro_to_findings/#a-finding-page)。 + +### 去重 +DefectDojo 具备去重功能,可帮助识别和管理代表同一底层漏洞的发现项。当扫描结果从一个或多个工具导入时,DefectDojo 会使用可配置的匹配逻辑来识别代表同一漏洞的发现项。 + +去重可防止同一漏洞在被相同或不同扫描器反复发现时多次出现,从而使修复历史记录始终附属于单一发现项。 + +有关去重的更多信息,请参见[此处](/triage_findings/finding_deduplication/about_deduplication/)。 + +### 重新导入 +DefectDojo 的重新导入功能允许在导入新扫描结果时更新发现项。当扫描被重新导入时,DefectDojo 会将传入的结果与现有发现项进行比较,并更新匹配的记录,而不是创建全新的记录。这保留了状态变更、修复历史、评论和归属信息等有价值的背景信息,为发现项在多个测试周期中的生命周期提供了连续记录。 + +有关重新导入功能的更多信息,请参见[此处](/import_data/import_intro/reimport/)。 + +### 风险接受 +风险接受是一种可应用于发现项的特殊状态,用于正式记录并落实在不立即修复的情况下确认发现项的决定。 + +有关风险接受的更多信息,请参见[此处](/triage_findings/findings_workflows/pro__risk_acceptance/)。 + +### 状态 +在 DefectDojo 中创建的每个发现项都有一个状态,用于传达相关信息,并帮助您的团队跟踪问题解决的进度。 + +有关状态的更多信息,请参见[此处](/triage_findings/findings_workflows/finding_status_definitions/)。 + +## 使用发现项 + +### 创建发现项 +虽然大多数发现项是通过扫描导入和集成自动生成的,但 DefectDojo 也支持手动创建发现项。手动发现项适用于跟踪通过渗透测试、架构审查、合规评估、漏洞赏金计划、顾问咨询或其他不产生扫描器输出的活动所识别出的漏洞和安全问题。 + +可以通过点击侧边栏**发现项**部分中的**新建发现项**,或在您希望添加发现项的测试的齿轮菜单中选择**添加发现项**来手动添加发现项。 + +### 编辑发现项 +发现项旁边的 ⋮ 竖排菜单包含以下功能: +- **编辑发现项**:编辑该发现项。 +- **复制发现项**:在另一个测试中创建该发现项的副本。副本可以保存到您有编辑权限的同一测试活动内的任何测试。当同一漏洞需要在多个测试环境中分别跟踪时,复制功能很有用。 +- **关闭发现项**:启动关闭该发现项的流程。 +- **请求审查**:启动同行审查流程,并将发现项的状态更改为“审查中”。有关同行审查的更多信息,请参见[此处](/triage_findings/findings_workflows/finding_status_definitions/#under-review)。 +- **添加风险接受**:启动风险接受流程。更多信息请参见[此处](/triage_findings/findings_workflows/pro__risk_acceptance/)。 +- **添加文件**:启动向发现项添加文件的流程(见下文)。 +- **添加备注**:启动向发现项添加备注的流程。 +- **添加自定义字段**:弹出窗口,允许您添加并定义要应用于该发现项的自定义字段。 +- **推送到 Jira**:将发现项推送到 Jira 以创建工单。 +- **推送到集成器**:将发现项推送到任何已集成的第三方问题跟踪系统。 +- **删除发现项**:删除所选发现项。 +- **发现项历史**:显示所选发现项的历史记录。 + +#### 向发现项附加文件 +您可以为任何发现项附加文件,以提供额外的背景信息——例如漏洞实际发生时的截图或概念验证图片。 + +支持的文件类型包括: + +``` +.txt .pdf .json .xml .csv .yml .png .jpeg +.sarif .xlsx .doc .html .js .nessus .zip .fpr +``` + +要向发现项附加文件,请在所选发现项的 ⋮ 竖排菜单或齿轮菜单中点击**添加文件**。为文件输入标题,从您的计算机中选择文件,然后点击**提交**。 + +该文件随后将出现在发现项视图中**测试概览**表格的文件部分。 + +#### 批量编辑发现项 +可以从发现项列表(例如从侧边栏访问的所有发现项表格)或特定测试内的发现项表格中批量编辑发现项。 + +有关如何批量编辑发现项的更多信息,请参见[此处](/triage_findings/findings_workflows/editing_findings/#bulk-edit-findings)。 + +### 关闭发现项 +完成某发现项的相关工作后,您可以在该发现项的 ⋮ 竖排菜单或齿轮菜单中点击**关闭发现项**来手动关闭它。或者,如果重新导入到 DefectDojo 的扫描不包含先前记录的某个发现项,该先前记录的发现项将自动关闭。 + +如果您不希望关闭任何发现项,可以在重新导入扫描表单中禁用此行为: + +- 如果使用界面,请取消勾选“关闭旧发现项”复选框 +- 如果使用 API,请将 close_old_findings 设置为 False ​ + +### 删除发现项 +可以在发现项的 ⋮ 竖排菜单或齿轮菜单中删除该发现项。此操作无法撤消。 + +出于审计目的,建议关闭已修复的发现项,而不是删除它们。 + +## 发现项组 +**发现项组**允许您将多个相关的发现项视为单个逻辑单元,以便进行分诊、报告和修复协调。 + +例如,一次扫描可能会在不同端点上生成 10 个 SQL 注入发现项。您可以将它们归入代表更广泛 SQL 注入问题的单个发现项组,而不必单独管理每一个。 + +发现项组并不会取代各个发现项。每个发现项仍然保留其自身的严重程度、状态、元数据、评论和修复历史。发现项组只是在其包含的发现项之上提供了一层额外的组织结构。 + +### 访问发现项组 +可以通过侧边栏访问发现项组。子菜单提供对开启和关闭发现项组以及所有发现项组(无论开启状态)的访问。 + +![image](images/profindings_ss1.png) + +### 创建发现项组 +发现项组可以手动或自动创建。 + +需要注意的是,发现项组只能由单个测试内所包含的发现项创建。来自不同测试、测试活动或产品的发现项不能添加到同一个发现项组。 + +#### 手动发现项组 +要手动执行发现项组操作: +1. 导航到某个测试内的发现项列表。 +2. 点击相应发现项的复选框,选择您希望添加到发现项组的一个或多个发现项。 +3. 点击发现项列表顶部出现的**发现项组**按钮。 +4. 点击您希望执行的相应操作。 + - **添加到新发现项组**:创建一个包含所选发现项的新发现项组。 + - **添加到现有发现项组**:将所选发现项添加到已存在的发现项组。 + - **从发现项组中移除**:将所选发现项从其先前所属的任何发现项组中移除。 +5. 点击**提交**。 + +请注意,除非所选的每个发现项都是可编辑的、未分组的且属于同一测试,否则分组功能将被禁用。 + +此外,请注意,从所有发现项列表中选择发现项时,唯一可执行的操作是将所选发现项从任何发现项组中移除。这是因为,如前所述,发现项组只能由单个测试内所包含的发现项创建。 + +#### 自动发现项组 +导入扫描时,可折叠的**可选字段**菜单中的**分组依据**功能可以根据所选的分组方式自动创建发现项组。当扫描器生成许多应统一管理的相关发现项时,此功能非常有用。 + +相邻的**为所有发现项创建发现项组**复选框具有两个功能: +- **勾选**:为每个导入的发现项创建一个发现项组,即使该发现项是该组中唯一的成员。 +- **未勾选**:仅在确实有多个发现项需要归为一组时才创建发现项组。 + +![image](images/profindings_ss2.png) + +如果在导入过程中未从“分组依据”下拉菜单中选择选项(例如上方截图中的**发现项标题**等),则不会进行分组。 + +如果发现项中未填写分组标准(例如组件名称、漏洞 ID、发现项标题等),则不会为其创建分组,也不会将其添加到已存在的发现项组中。 + +如果导入的扫描揭示了 10 个未分组的发现项,而随后重新导入同一扫描且发现项被分组,那么最初的 10 个发现项将不会被添加到该发现项组中(即,该发现项组只会包含来自重新导入的 10 个发现项,而不包含来自初始导入的 10 个发现项)。 + +## 发现项模板 +**发现项模板**允许用户为常见的漏洞和安全问题创建可重复使用的模板。模板可以包含标题、描述、影响、重现步骤、缓解措施、参考资料及其他发现项元数据等标准化信息。 + +发现项模板在用户需要反复手动创建发现项、并希望避免每次重新输入相同支持信息的情况下最为有用。 + +### 访问发现项模板 +发现项模板位于侧边栏的发现项子菜单中。 + +![image](images/profindings_ss1.png) + +### 创建发现项模板 +可以通过点击发现项模板视图左上方的**新建发现项模板**按钮来创建发现项模板。 + +随后出现的页面概述了使用发现项模板时将应用于发现项的元数据。 + +### 应用发现项模板 +发现项模板在开源版 DefectDojo 和 DefectDojo Pro 之间有所不同。在 Pro 版中,发现项模板无法应用于已存在的发现项,也无法基于已存在的发现项创建。 + +不过,您可以使用父测试活动视图中测试旁边的 ⋮ 竖排菜单,或测试视图中的齿轮菜单,基于发现项模板手动向测试添加发现项。 + +![image](images/profindings_ss3.png) + +![image](images/profindings_ss4.png) + +## 报告 +DefectDojo 的报告构建器允许您通过一组内容小部件组装自定义报告,运行报告,并导出结果(例如,打印为 PDF)。自定义报告可以汇总您希望与外部受众分享的发现项或端点,并可以包含品牌标识和样板文字。 + +有关 DefectDojo 报告构建器的更多信息,请参见[此处](/metrics_reports/reports/report-builder/)。 + +### 导出发现项 +显示发现项列表或测试活动列表的页面在左上方提供 CSV 和 Excel 导出选项。对于发现项,还可以执行快速导出,该操作将打开一个包含每个发现项相关元数据表格的新标签页。 diff --git a/docs/content/asset_modelling/engagements_tests/PRO__organizations.it.md b/docs/content/asset_modelling/engagements_tests/PRO__organizations.it.md new file mode 100644 index 0000000000..f83fe8f8af --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__organizations.it.md @@ -0,0 +1,140 @@ +--- +title: Organizzazioni +description: Comprendere le Organizzazioni in DefectDojo Pro +audience: pro +weight: 1 +--- + +**ORGANIZZAZIONI** → Asset → Engagement → Test → Riscontri + +## Panoramica + +Le **Organizzazioni** si trovano al vertice della gerarchia dei prodotti di DefectDojo. Le Organizzazioni si distinguono dagli oggetti sottostanti nella gerarchia — Asset, Engagement, Test e Riscontri — perché non sono target tecnici di scansione, ma servono principalmente come astrazioni organizzative che suddividono i tuoi sforzi di sicurezza in base a: +- Dominio aziendale +- Team di sviluppo +- Team di sicurezza +- Applicazioni software +- Famiglia di prodotti generale +- Cliente o filiale +- Struttura di reportistica +- ecc. + +Il filo conduttore degli esempi precedenti esemplifica l'utilità essenziale delle Organizzazioni: esse dovrebbero generalmente rappresentare confini stabili e di lunga durata all'interno del tuo programma di sicurezza. + +## Dati e struttura dell'Organizzazione + +Poiché le Organizzazioni non vengono scansionate direttamente, l'unico campo obbligatorio richiesto per crearle è un nome. Al di là di questo, esse fungono da contenitori per gli Asset e i relativi Engagement, Test e Riscontri sottostanti. + +Quando crei un'Organizzazione, considera come la sua struttura influenzerà la tua reportistica. Hai principalmente bisogno che le Organizzazioni rappresentino i team che lavorano sui progetti (Asset) che le Organizzazioni conterranno? Oppure le Organizzazioni rappresenterebbero meglio progetti generali che contengono diverse iterazioni dei progetti (Asset) al loro interno? + +Se disponi di un'unica Organizzazione che contiene tutte le informazioni rilevanti per un determinato dominio aziendale o team di sviluppo, rappresentarla come un'Organizzazione faciliterà una reportistica più fluida, invece di dover assemblare un report a partire da vari Asset e Organizzazioni. + +Se un particolare progetto software ha molti deployment o versioni distinti, potrebbe valere la pena creare un'unica Organizzazione che copra l'ambito dell'intero progetto e far sì che ogni versione esista come Asset individuale. In alcuni flussi di lavoro, le Organizzazioni possono essere utilizzate anche per separare le fasi del ciclo di vita del software: un'Organizzazione per “In sviluppo”, un'Organizzazione per “In produzione”, ecc. +​ +Le Organizzazioni possono essere utilizzate per determinare l'accesso a filiali, aziende acquisite o altre unità aziendali regolamentate ai fini RBAC. Nelle aziende complesse, dove esistono molti progetti unici con regole di accesso diverse, le Organizzazioni sono particolarmente rilevanti. + +In definitiva, la decisione su come utilizzare Organizzazioni e Asset dipende da come preferisci riflettere la struttura organizzativa unica della tua azienda e le esigenze del tuo team di sicurezza. + +Di seguito sono riportate alcune strutture di esempio per aiutarti a decidere come designare i tuoi oggetti come Organizzazioni o Asset. + +- **Organizzazione**: Divisione Pagamenti + - Asset: Payments API - Produzione + - Asset: Payments API - Staging + - Asset: Billing Worker + +- **Organizzazione**: Prodotto Software A + - Asset: Web Portal + - Asset: Mobile Backend + +Inoltre, la tabella seguente è una guida illustrativa per capire se qualcosa è meglio rappresentato da un'Organizzazione o da un Asset: + +| Organizzazioni | Asset | +|--------------|--------| +| Unità aziendali | Applicazioni individuali | +| Dipartimenti | Deployment/ambienti | +| Domini di proprietà della sicurezza | Componenti infrastrutturali | +| Famiglie di prodotti | Microservizi specifici | +| Reportistica a livello di portfolio | Target di scansione | +| Clienti | Versioni software specifiche | + +Come indicato, la tua struttura potrebbe variare in base alle esigenze di sicurezza specifiche della tua azienda. + +## Accesso alle Organizzazioni + +Le Organizzazioni sono accessibili tramite la barra laterale. Il sottomenu offre l'accesso a Tutte le Organizzazioni, oltre all'opzione per creare una nuova Organizzazione. + +![image](images/org_ss1.png) + +## Vista dell'Organizzazione + +La vista di un'Organizzazione contiene una serie di tabelle e grafici per interpretarne lo stato a colpo d'occhio. Questo include: + +- **Descrizione** +- **Commercio** + - Se l'Organizzazione è stata determinata come Critica o Chiave + - Selezionare Critica o Chiave viene utilizzato esclusivamente a scopo di filtraggio +- **Membri assegnati** (Utenti DefectDojo) +- **Gruppi di utenti assegnati** + - I gruppi di utenti che sono stati assegnati all'Organizzazione per il controllo delle autorizzazioni. Ulteriori informazioni sui gruppi di utenti sono disponibili [qui](/admin/user_management/create_user_group/). +- **Elenco degli Asset all'interno dell'Organizzazione** + +## Lavorare con le Organizzazioni + +### Creazione delle Organizzazioni + +Esistono due modi per creare le Organizzazioni: + +- Dall'opzione **Nuova Organizzazione** nel menu laterale +- Dal pulsante **Nuova Organizzazione** nella parte superiore dell'elenco Tutte le Organizzazioni + +### Modifica delle Organizzazioni + +Le Organizzazioni possono essere modificate cliccando su **Modifica Organizzazione** nel menu a ingranaggio in alto a destra della vista dell'Organizzazione. Lo stesso menu è accessibile anche cliccando sul menu kebab ⋮ a sinistra dell'Organizzazione nella vista Tutte le Organizzazioni. + +Tutti i campi modificabili successivamente sono disponibili anche durante la creazione dell'Organizzazione. + +### Eliminazione delle Organizzazioni + +L'eliminazione di un'Organizzazione può essere effettuata selezionando **Elimina Organizzazione** dalle impostazioni dell'Organizzazione. + +Poiché le Organizzazioni si trovano al vertice della gerarchia, eliminarle rimuove tutta la cronologia di sicurezza, le relazioni e gli oggetti figli a valle, come: +- Qualsiasi Asset, Engagement e Test contenuto nell'Organizzazione +- Tutta la cronologia di sicurezza associata, inclusi Riscontri e integrazioni +- Qualsiasi Epic Jira collegata +- Tutte le note e i file caricati associati agli Asset, Engagement e Test all'interno di quell'Organizzazione + +L'eliminazione di un'Organizzazione non può essere annullata. Se desideri “dismettere” un'organizzazione senza eliminare i dati sottostanti (ad esempio, per conservare i registri di test software legacy a fini di audit), puoi modificare il nome dell'Organizzazione o aggiungere un Tag per indicare che si trova in uno stato deprecato. + +## Organizzazioni vs. Metadati + +Le Organizzazioni sono pensate per rappresentare la proprietà strutturale o i confini di reportistica, piuttosto che classificazioni leggere. Attributi come lo stato di deployment, le etichette interne o gli stati temporanei dei flussi di lavoro potrebbero essere meglio rappresentati tramite tag o metadati piuttosto che tramite Organizzazioni separate. + +## Confini dell'Organizzazione + +Le Organizzazioni stabiliscono sia i confini di reportistica sia quelli di accesso all'interno di DefectDojo. Poiché le integrazioni, le autorizzazioni RBAC, la proprietà, le metriche e i modelli di deduplicazione ereditano spesso la struttura delle Organizzazioni, progettare confini chiari fin dall'inizio aiuta a evitare in seguito una proliferazione incontrollata della gerarchia e la frammentazione della reportistica. + +### Riscontri e automazione + +Sebbene le integrazioni siano tipicamente configurate su oggetti di livello inferiore come Asset, Engagement o Riscontri, le Organizzazioni definiscono comunque i confini di proprietà, reportistica e accesso all'interno dei quali tali integrazioni operano. + +Le autorizzazioni si propagano verso il basso, il che significa che l'accesso a un'Organizzazione garantisce automaticamente l'accesso a tutti gli oggetti all'interno di quell'Organizzazione (ad esempio, Asset, Engagement, Test e Riscontri). + +Il modello RBAC di DefectDojo può essere utilizzato per regolamentare l'accesso degli utenti umani, ma può anche limitare l'accesso dei token API a particolari Organizzazioni. + +Per maggiori informazioni sui ruoli utente, consulta il nostro articolo [Introduzione ai tipi di autorizzazione](/admin/user_management/set_user_permissions/#introduction-to-permission-types). + +### Proprietà + +In quanto oggetti di primo livello, le Organizzazioni implicano anche la proprietà sugli oggetti figli al loro interno. Il tracciamento degli SLA, i flussi di lavoro di correzione, l'instradamento dei ticket e la governance generale procedono in modo più fluido quando le Organizzazioni sono state configurate per riflettere accuratamente le persone responsabili. + +### Metriche/Reportistica + +Le dashboard, i riquadri e le viste delle metriche possono essere filtrati per Organizzazione, rendendoli una componente fondamentale del modo in cui i tuoi dati di sicurezza vengono calcolati, visualizzati e infine esportati. + +Ai fini della reportistica, è generalmente più semplice combinare più Organizzazioni in un unico documento piuttosto che suddividere una singola Organizzazione in documenti separati. Pertanto, consigliamo di impostare le Organizzazioni al livello di granularità più adatto ai report del tuo team. Ad esempio, non è necessario rappresentare una grande divisione aziendale come un'Organizzazione se prevedi di produrre report principalmente per i singoli dipartimenti all'interno di quella divisione. + +Strutturare efficacemente le tue Organizzazioni in modo che riflettano le tue esigenze di reportistica è fondamentale per valutare accuratamente la tua postura di sicurezza. Per maggiori informazioni sulle Metriche, clicca [qui](/metrics_reports/pro_metrics/pro__overview/). + +### Deduplicazione + +La deduplicazione in DefectDojo avviene a livello di Asset e non è influenzata dall'Organizzazione principale. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__organizations.pt-br.md b/docs/content/asset_modelling/engagements_tests/PRO__organizations.pt-br.md new file mode 100644 index 0000000000..16be9bff65 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__organizations.pt-br.md @@ -0,0 +1,140 @@ +--- +title: Organizações +description: Entendendo as Organizações no DefectDojo Pro +audience: pro +weight: 1 +--- + +**ORGANIZAÇÕES** → Assets → Engagements → Tests → Findings + +## Overview + +**Organizações** ficam no topo da hierarquia de produtos do DefectDojo. As Organizações são distintas dos objetos descendentes na hierarquia — Ativos, Engajamentos, Testes e Achados — porque não são alvos técnicos de scan, mas sim servem principalmente como abstrações organizacionais que compartimentam seus esforços de segurança de acordo com: +- Domínio de negócio +- Equipe de desenvolvimento +- Equipe de segurança +- Aplicações de software +- Família de produtos abrangente +- Cliente ou subsidiária +- Estrutura de relatórios +- etc. + +O tema dos exemplos acima ilustra a utilidade essencial das Organizações: elas devem, de modo geral, representar limites estáveis e duradouros dentro do seu programa de segurança. + +## Organization Data and Structure + +Como as Organizações não são escaneadas diretamente, o único campo obrigatório para criá-las é um nome. Além disso, elas atuam como contêineres para Ativos e seus Engajamentos, Testes e Achados descendentes. + +Ao criar uma Organização, considere como sua estrutura vai influenciar seus relatórios. Você precisa principalmente que as Organizações representem as equipes que trabalham nos projetos (Ativos) que as Organizações conterão? Ou as Organizações representariam melhor projetos abrangentes que contêm diferentes iterações dos projetos (Ativos) dentro deles? + +Se você tiver uma única Organização que contenha todas as informações relevantes para um determinado domínio de negócio ou equipe de desenvolvimento, representar isso como uma Organização facilitará relatórios mais fluidos, em vez de precisar reunir um relatório a partir de vários Ativos e Organizações. + +Se um projeto de software específico tiver muitos deployments ou versões distintas, pode valer a pena criar uma única Organização que cubra o escopo de todo o projeto, com cada versão existindo como Ativos individuais. Em alguns fluxos de trabalho, as Organizações também podem ser usadas para separar estágios do ciclo de vida do software: uma Organização para “Em Desenvolvimento”, uma Organização para “Em Produção”, etc. +​ +As Organizações podem ser usadas para determinar o acesso a subsidiárias, empresas adquiridas ou outras unidades de negócio regulamentadas para fins de RBAC. Em empresas complexas, onde há muitos projetos exclusivos com diferentes regras de acesso, as Organizações são particularmente relevantes. + +Em última análise, a decisão de como usar Organizações e Ativos depende de como você deseja refletir melhor sua estrutura organizacional exclusiva e as necessidades da sua equipe de segurança. + +Abaixo estão algumas estruturas de exemplo para orientar como você designa seus objetos como Organizações ou Ativos. + +- **Organização**: Divisão de Pagamentos + - Ativo: Payments API - Production + - Ativo: Payments API - Staging + - Ativo: Billing Worker + +- **Organização**: Software Product A + - Ativo: Web Portal + - Ativo: Mobile Backend + +Além disso, o guia a seguir ilustra se algo é melhor representado por uma Organização ou por um Ativo: + +| Organizações | Ativos | +|--------------|--------| +| Unidades de negócio | Aplicações individuais | +| Departamentos | Deployments/ambientes | +| Domínios de propriedade de segurança | Componentes de infraestrutura | +| Famílias de produtos | Microsserviços específicos | +| Relatórios em nível de portfólio | Alvos de scan | +| Clientes | Versões específicas de software | + +Como observado, sua estrutura pode variar de acordo com as necessidades exclusivas de segurança da sua equipe. + +## Accessing Organizations + +As Organizações são acessíveis pela barra lateral. O submenu oferece acesso a Todas as Organizações, bem como a opção de criar uma nova Organização. + +![image](images/org_ss1.png) + +## Organization View + +A visualização de uma Organização contém uma variedade de tabelas e gráficos para interpretar seu status rapidamente. Isso inclui: + +- **Descrição** +- **Commerce** + - Se a Organização foi determinada como Crítica ou Chave + - Marcar Crítica ou Chave é usado exclusivamente para fins de filtragem +- **Membros Atribuídos** (Usuários do DefectDojo) +- **Grupos de Usuários Atribuídos** + - Grupos de usuários que foram atribuídos à Organização para controle de permissões. Mais informações sobre grupos de usuários podem ser encontradas [aqui](/admin/user_management/create_user_group/). +- **Lista de Ativos dentro da Organização** + +## Working with Organizations + +### Create Organizations + +Existem duas formas de criar Organizações: + +- Pela opção **Nova Organização** no menu lateral +- Pelo botão **Nova Organização** no topo da lista de Todas as Organizações + +### Edit Organizations + +As Organizações podem ser editadas clicando em **Editar Organização** no menu de engrenagem no canto superior direito da visualização da Organização. O mesmo menu também pode ser acessado clicando no menu kebab ⋮ à esquerda da Organização na visualização de Todas as Organizações. + +Todos os campos subsequentes que podem ser editados também estão disponíveis quando a Organização está sendo criada. + +### Delete Organizations + +A exclusão de uma Organização pode ser realizada selecionando **Excluir Organização** nas configurações da Organização. + +Como as Organizações ficam no topo da hierarquia, excluí-las remove todo o histórico de segurança, relacionamentos e objetos filhos posteriores, tais como: +- Quaisquer Ativos, Engajamentos e Testes contidos na Organização +- Todo o histórico de segurança associado, incluindo Achados e integrações +- Quaisquer Jira Epics vinculados +- Todas as notas e uploads de arquivos associados aos Ativos, Engajamentos e Testes dentro dessa Organização + +A exclusão de uma Organização não pode ser desfeita. Se você quiser “desativar” uma organização sem excluir os dados subjacentes (por exemplo, preservando registros legados de testes de software para fins de auditoria), você pode alterar o nome da Organização ou adicionar uma Tag para indicar que ela está em um estado obsoleto. + +## Organiations vs. Metadata + +As Organizações têm como objetivo representar limites estruturais de propriedade ou de relatório, e não classificações leves. Atributos como status de deployment, rótulos internos ou estados temporários de fluxo de trabalho podem ser melhor representados por meio de tags ou metadados, em vez de Organizações separadas. + +## Organization Boundaries + +As Organizações estabelecem limites de relatório e de acesso dentro do DefectDojo. Como integrações, permissões de RBAC, propriedade, métricas e modelos de deduplicação frequentemente herdam a estrutura das Organizações, projetar limites claros desde o início ajuda a evitar a expansão descontrolada da hierarquia e a fragmentação de relatórios mais tarde. + +### Findings and Automation + +Embora as integrações geralmente sejam configuradas em objetos de nível inferior, como Ativos, Engajamentos ou Achados, as Organizações ainda definem os limites de propriedade, relatório e acesso dentro dos quais essas integrações operam. + +As permissões são propagadas em cascata para baixo, o que significa que o acesso a uma Organização concede automaticamente acesso a todos os objetos dentro dessa Organização (por exemplo, Ativos, Engajamentos, Testes e Achados). + +O modelo de RBAC do DefectDojo pode ser usado para controlar o acesso de usuários humanos, mas também pode restringir o acesso de tokens de API a Organizações específicas. + +Para mais informações sobre papéis de usuário, veja nosso artigo [Introdução aos Tipos de Permissão](/admin/user_management/set_user_permissions/#introduction-to-permission-types). + +### Ownership + +Como objetos de nível superior, as Organizações também implicam a propriedade sobre os objetos filhos que contêm. O rastreamento de SLA, os fluxos de trabalho de remediação, o roteamento de tickets e a governança geral fluem de forma mais tranquila quando as Organizações são configuradas para refletir com precisão os indivíduos responsáveis por elas. + +### Metrics/Reporting + +Painéis, tiles e visualizações de métricas podem ser filtrados por Organização, o que os torna um componente crítico na forma como seus dados de segurança são calculados, visualizados e, por fim, exportados. + +Para fins de relatório, geralmente é mais fácil combinar várias Organizações em um único documento do que subdividir uma única Organização em documentos separados. Por isso, recomendamos configurar as Organizações no nível de granularidade que fizer mais sentido para os relatórios da sua equipe. Por exemplo, não há necessidade de representar uma grande divisão de negócios como uma Organização se você for reportar principalmente para departamentos individuais dentro dessa divisão. + +Estruturar efetivamente suas Organizações para refletir suas necessidades de relatório é fundamental para avaliar com precisão sua postura de segurança. Para mais informações sobre Métricas, clique [aqui](/metrics_reports/pro_metrics/pro__overview/). + +### Deduplication + +A deduplicação no DefectDojo ocorre no nível do Ativo, e não é afetada pela Organização pai. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__organizations.zh-hans.md b/docs/content/asset_modelling/engagements_tests/PRO__organizations.zh-hans.md new file mode 100644 index 0000000000..eb0b9064ab --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__organizations.zh-hans.md @@ -0,0 +1,140 @@ +--- +title: 组织 +description: 了解 DefectDojo Pro 中的组织 +audience: pro +weight: 1 +--- + +**组织** → 资产 → 测试活动 → 测试 → 发现项 + +## 概述 + +**组织**位于 DefectDojo 产品层级结构的最顶层。组织与层级结构中下级的对象——资产、测试活动、测试和发现项——不同,因为它们并非技术性的扫描目标,而是主要作为组织抽象概念,用于按照以下方式划分您的安全工作: +- 业务领域 +- 开发团队 +- 安全团队 +- 软件应用程序 +- 总体产品系列 +- 客户或子公司 +- 报告结构 +- 等等。 + +上述示例的主旨体现了组织的核心作用:它们通常应代表您安全计划中稳定、长期存在的边界。 + +## 组织数据与结构 + +由于组织不会被直接扫描,创建组织时唯一必填的字段是名称。除此之外,组织充当资产及其下级测试活动、测试和发现项的容器。 + +创建组织时,请考虑其结构将如何影响您的报告。您是主要需要用组织来代表负责组织所包含项目(资产)的团队,还是用组织来更好地代表包含其内不同项目迭代版本(资产)的总体项目? + +如果您有一个包含特定业务领域或开发团队所有相关信息的单一组织,将其表示为一个组织将有助于更顺畅地生成报告,而不必从各种资产和组织中拼凑出一份报告。 + +如果某个特定软件项目有许多不同的部署或版本,则可能值得创建一个涵盖整个项目范围的单一组织,并将每个版本作为单独的资产。在某些工作流程中,组织也可用于区分软件生命周期阶段:一个组织用于“开发中”,一个组织用于“生产中”,等等。 +​ +组织可用于确定出于 RBAC 目的对子公司、被收购公司或其他受监管业务单元的访问权限。在拥有大量具有不同访问规则的独特项目的复杂业务中,组织尤其重要。 + +最终,如何使用组织和资产取决于您希望如何最好地反映您独特的组织架构以及安全团队的需求。 + +以下是一些示例结构,可帮助您了解如何将对象指定为组织或资产。 + +- **组织**:支付部门 + - 资产:支付 API - 生产环境 + - 资产:支付 API - 预发布环境 + - 资产:计费工作进程 + +- **组织**:软件产品 A + - 资产:Web 门户 + - 资产:移动端后台 + +此外,以下是一份说明性指南,用于判断某事物更适合用组织还是资产来表示: + +| 组织 | 资产 | +|--------------|--------| +| 业务单元 | 单个应用程序 | +| 部门 | 部署/环境 | +| 安全归属域 | 基础设施组件 | +| 产品系列 | 特定微服务 | +| 组合层面的报告 | 扫描目标 | +| 客户 | 特定软件版本 | + +如前所述,您的结构可能会因您独特的安全需求而有所不同。 + +## 访问组织 + +可以通过侧边栏访问组织。子菜单提供对所有组织的访问,以及创建新组织的选项。 + +![image](images/org_ss1.png) + +## 组织视图 + +组织视图包含多种表格和图表,帮助您一目了然地了解其状态。包括: + +- **描述** +- **商业属性** + - 该组织是否被确定为关键或重要 + - 勾选“关键”或“重要”仅用于筛选目的 +- **已分配成员**(DefectDojo 用户) +- **已分配用户组** + - 已分配给该组织用于权限控制的用户组。有关用户组的更多信息,请参见[此处](/admin/user_management/create_user_group/)。 +- **组织内的资产列表** + +## 使用组织 + +### 创建组织 + +创建组织有两种方式: + +- 从侧边菜单中的**新建组织**选项 +- 从所有组织列表顶部的**新建组织**按钮 + +### 编辑组织 + +可以通过点击组织视图右上方齿轮菜单中的**编辑组织**来编辑组织。也可以通过点击所有组织视图中组织左侧的 ⋮ 竖排菜单来访问相同的菜单。 + +随后所有可编辑的字段在创建组织时同样可用。 + +### 删除组织 + +可以通过在组织的设置中选择**删除组织**来删除组织。 + +由于组织位于层级结构的顶层,删除组织将移除所有下游的安全历史记录、关联关系和子对象,例如: +- 该组织内包含的任何资产、测试活动和测试 +- 所有相关的安全历史记录,包括发现项和集成 +- 任何关联的 Jira 史诗(Epic) +- 与该组织内资产、测试活动和测试相关联的所有备注和上传文件 + +删除组织无法撤消。如果您希望在不删除底层数据的情况下“停用”某个组织(例如出于审计目的保留旧版软件测试记录),可以更改该组织的名称,或添加标签以表明其处于已弃用状态。 + +## 组织与元数据的对比 + +组织旨在表示结构性归属或报告边界,而非轻量级分类。诸如部署状态、内部标签或临时工作流状态等属性,可能更适合通过标签或元数据来表示,而不是通过单独的组织。 + +## 组织边界 + +组织在 DefectDojo 中同时建立了报告边界和访问边界。由于集成、RBAC 权限、归属关系、指标和去重模型经常继承组织的结构,及早设计清晰的边界有助于避免日后出现层级结构蔓延和报告碎片化的问题。 + +### 发现项与自动化 + +尽管集成通常配置在资产、测试活动或发现项等较低层级的对象上,但组织仍然定义了这些集成运作所在的归属、报告和访问边界。 + +权限会向下级联,这意味着对某个组织的访问权限会自动授予对该组织内所有对象(例如资产、测试活动、测试和发现项)的访问权限。 + +DefectDojo 的 RBAC 模型既可用于控制人工用户的访问权限,也可用于限制 API 令牌对特定组织的访问权限。 + +有关用户角色的更多信息,请参阅我们的[权限类型简介](/admin/user_management/set_user_permissions/#introduction-to-permission-types)一文。 + +### 归属关系 + +作为顶层对象,组织也隐含着对其内部子对象的归属关系。当组织的设置能够准确反映对其负责的个人时,SLA 跟踪、修复工作流、工单路由和整体治理都会更加顺畅。 + +### 指标/报告 + +指标仪表板、磁贴和视图可以按组织进行筛选,这使组织成为您的安全数据如何计算、可视化并最终导出的关键组成部分。 + +出于报告目的,将多个组织合并为一份文档通常比将单个组织细分为多份文档更容易。因此,我们建议按照适合您团队报告需求的粒度来设置组织。例如,如果您主要向某个业务部门内的各个分部进行报告,则无需将该大型业务部门整体表示为一个组织。 + +有效地构建组织结构以反映您的报告需求,对于准确评估您的安全态势至关重要。有关指标的更多信息,请点击[此处](/metrics_reports/pro_metrics/pro__overview/)。 + +### 去重 + +DefectDojo 中的去重发生在资产层级,不受父级组织的影响。 diff --git a/docs/content/asset_modelling/engagements_tests/PRO__tests.it.md b/docs/content/asset_modelling/engagements_tests/PRO__tests.it.md new file mode 100644 index 0000000000..c1dc1ebd9c --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__tests.it.md @@ -0,0 +1,275 @@ +--- +title: Test +description: Informazioni sui Test in DefectDojo Pro +audience: pro +weight: 4 +--- + +Organizzazioni → Asset → Engagement → **TEST** → Riscontri + +## Panoramica + +Un Test è un contenitore per una o più esecuzioni di scansione, utilizzate per individuare le falle in un Asset. I Test sono il componente finale e più granulare della gerarchia degli oggetti di DefectDojo, e fungono da contenitore per i Riscontri risultanti dall'esecuzione di uno strumento di sicurezza o di una valutazione manuale, aggiungendo anche il contesto in cui tali Riscontri sono stati individuati (ovvero quale strumento li ha segnalati, quando è stato eseguito l'ultima volta, ecc.). + +Esempi di Test includono: +- Test di sicurezza delle applicazioni statiche +- Test di sicurezza delle applicazioni dinamiche +- Analisi della composizione del software +- Scansioni di sicurezza dei container +- Scansioni di infrastruttura/rete +- Penetration test manuali +- Scansioni della pipeline CI/CD + +### Tipi di Test + +Esistono diversi modi per creare Test in DefectDojo, tra cui i **parser specifici per fornitore** (ad es. Burp, OWASP ZAP, Acunetix, Invicti), il **Generic Findings Import**, l'**Universal Parser** e i **Connectors**. + +Questi metodi possono creare nuovi Test o reimportare i Riscontri in Test esistenti, a seconda della configurazione e della strategia di deduplicazione. + +Sebbene ciascun metodo differisca principalmente nel modo in cui i dati di scansione vengono analizzati e importati, tutti si traducono infine nell'associazione dei Riscontri a un Test. + +#### Parser + +I **parser** sono componenti che elaborano formati di output di scansione specifici (ad es. XML, JSON, CSV) e li mappano nel modello di Riscontro interno di DefectDojo. Quando i risultati della scansione vengono importati, DefectDojo utilizza il parser selezionato per estrarre i Riscontri e collegarli a un Test appena creato o già esistente. + +#### Generic Findings Import + +Quando non esiste un parser nativo per un determinato strumento, [**Generic Findings Import**](/supported_tools/parsers/generic_findings_import) consente di importare i riscontri utilizzando uno schema JSON o CSV standardizzato, indipendentemente dalla fonte originale. + +DefectDojo analizza i dati forniti, crea un nuovo Test (o li importa in uno esistente) e collega i Riscontri. Viene inoltre creato un Tipo di Test corrispondente in base al campo opzionale `type` del report: quando `type` viene omesso (o è uguale al tipo di scansione) il Tipo di Test è “Generic Findings Import”; quando `type` viene fornito diventa “`{type}` Scan (Generic Findings Import)” (un `type` che termina già con il suffisso “(Generic Findings Import)” viene utilizzato così com'è). + +#### Universal Parser + +[**Universal Parser**](/supported_tools/parsers/universal_parser) consente agli utenti di definire come i dati di input arbitrari vengono mappati nel modello di Riscontro di DefectDojo. Dopo aver configurato il parser e caricato i dati di scansione, DefectDojo applica le regole di mappatura per estrarre i Riscontri, crea un Test (o ne aggiorna uno esistente) e associa i Riscontri a quel Test. + +#### Connectors + +I [**Connectors**](/connectors/upstream/about/) possono essere utilizzati per acquisire e organizzare automaticamente i dati sulle vulnerabilità provenienti da strumenti esterni tramite chiamate API. Una volta configurato, un Connector recupera i risultati della scansione, analizza i dati e crea nuovi Test o aggiorna quelli esistenti a seconda della sua configurazione. I Riscontri vengono quindi collegati al Test corrispondente. + +#### Confronto dei meccanismi di creazione dei Test + +| | **Parser nativi** | **Generic Findings Import** | **Universal Parser (Pro)** | **Connectors** | +|----------|---------------|------------------------|------------------------|------------| +| **Scopo principale** | Importa gli output degli strumenti supportati | Importa dati personalizzati/non supportati tramite uno schema fisso | Importa formati arbitrari tramite mappature configurabili | Sincronizza continuamente i sistemi esterni | +| **Formato di input** | Specifico per strumento (ad es. ZAP XML, SARIF) | Schema JSON/CSV rigoroso | Arbitrario (JSON, XML, ecc.) | Risposte API esterne | +| **Chi gestisce la normalizzazione** | DefectDojo (parser integrato) | Utente (deve conformarsi allo schema) | DefectDojo (tramite configurazione del parser) | Strumento esterno + DefectDojo | +| **Trigger di creazione del Test** | Caricamento manuale o importazione via API | Caricamento manuale o importazione via API | Caricamento manuale o importazione via API | Sincronizzazione automatica (pianificata o basata su eventi) | +| **Tipo di Test** | Predefinito (ad es. "ZAP Scan") | Tipo "Generic" creato automaticamente | Derivato dalla configurazione del parser | Dipende dal connector / parser sottostante | +| **Impegno di configurazione** | Basso | Moderato (richiede trasformazione dei dati) | Alto (configurazione del parser) | Da moderato ad alto (configurazione dell'integrazione) | +| **Flessibilità** | Bassa (solo strumenti supportati) | Media | Alta | Da media ad alta | +| **Livello di automazione** | Da basso a moderato | Da basso a moderato | Da basso a moderato | Alto | +| **Caso d'uso tipico** | Scanner standard (SAST, DAST, SCA) | Script personalizzati, strumenti non supportati | Formati complessi/personalizzati su larga scala | Integrazioni CI/CD, SCM o piattaforma | + +Indipendentemente dal metodo di importazione, tutti i dati di scansione in DefectDojo sono infine rappresentati come Riscontri collegati a un Test, che funge da unità di esecuzione e di tracciamento del ciclo di vita. + +### Dati del Test + +I Test memorizzano una serie di metadati che aiutano a documentare i vari componenti di ogni sforzo di test, come: +- Titolo / nome del Test +- Tipo di Test +- Descrizione / note del Test +- Data di inizio e fine +- L'Ambiente in cui è stato eseguito il Test (ad es. Development, Staging, Pre-Production, Production, ecc.) +- Versione / Branch / Build ID / Commit Hash +- Configurazione della scansione API +- Personale associato al Test +- File aggiuntivi che possono essere utilizzati per controlli successivi o reimportazioni +- L'Engagement, l'Asset e l'Organizzazione principali +- Cronologia di importazione e reimportazione + +Ogni Test mantiene una cronologia delle importazioni, che registra tutte le importazioni e reimportazioni di scansione associate al Test. Ogni voce della cronologia include metadati come data della scansione, versione, branch, commit hash e build ID. + +Questa cronologia garantisce la tracciabilità tra più esecuzioni di scansione all'interno dello stesso Test. + +### Autorizzazioni + +È possibile memorizzare più Test all'interno di un singolo Engagement, e gli Engagement sono memorizzati all'interno degli Asset. Di conseguenza, l'accesso a un Asset garantisce automaticamente l'accesso a tutti i Test (ed Engagement) contenuti in quell'Asset. I Test non dispongono di elenchi di controllo degli accessi indipendenti. + +## Accedere ai Test + +È possibile accedere ai Test da varie sezioni dell'interfaccia utente di DefectDojo. + +- La barra laterale + +![image](images/tests_ss13.png) + +- All'interno di un Engagement + +![image](images/tests_ss14.png) + +- La barra superiore di un Asset + +![image](images/tests_ss15.png) + +- La tabella dei metadati all'interno della visualizzazione di un Riscontro + +![image](images/tests_ss16.png) + +## Utilizzo dei Test + +### Creare Test + +I Test possono essere creati automaticamente quando i dati di scansione vengono importati direttamente in un Engagement, generando un nuovo Test contenente tali dati. I Test possono anche essere creati in previsione della pianificazione di futuri Engagement, oppure per riscontri di sicurezza inseriti manualmente che richiedono tracciamento e correzione. + +#### Flussi di lavoro manuali + +Per creare un Test, è necessario prima creare un Engagement che lo contenga, oltre a un Asset che conterrà quell'Engagement. Successivamente, esistono diversi modi per creare un Test: + +- Nella barra laterale, sotto Test, all'interno della sottosezione **Manage** + - Sarà necessario selezionare l'Engagement preesistente a cui attribuire il Test durante la compilazione del modulo Nuovo Test. + +![image](images/tests_ss1.png) + +- Il menu a discesa delle impostazioni nell'angolo in alto a destra della visualizzazione di un Asset + - **Import Scan** creerà automaticamente un Test una volta aggiunto un file di scansione al modulo Import Scan. Avrai la possibilità di attribuire il Test a un Engagement preesistente oppure creare e denominare un nuovo Engagement per contenere il nuovo Test. + - Durante la compilazione del modulo Import Scan, puoi aggiungere metadati come versione, branch tag, commit hash e build ID. Questo si rifletterà nella sezione Import History della visualizzazione del Test. + +![image](images/tests_ss2.png) + +- Il menu a discesa delle impostazioni in alto a destra della visualizzazione di un Engagement + - **Import Scan** seguirà lo stesso flusso di lavoro degli Asset, ma posizionerà automaticamente l'oggetto Test all'interno dell'Engagement in cui hai fatto clic su Import Scan. + - **Add Test** creerà un oggetto Test ma non richiede il caricamento di una scansione nel Test stesso, il che è utile in previsione della pianificazione di Test futuri o per riscontri di sicurezza inseriti manualmente che richiedono tracciamento e correzione. + +![image](images/tests_ss3.png) + +Se selezioni Add Test e desideri successivamente importare manualmente i risultati di una scansione in un Test, puoi farlo aprendo il Test e facendo clic sul pulsante Reimport Findings nelle impostazioni del Test oppure sul pulsante Reimport Scan nella tabella dei Riscontri. + +![image](images/tests_ss21.png) + +#### Flussi di lavoro automatizzati + +Nei flussi di lavoro automatizzati, i Test possono essere creati a livello di codice come parte del processo di importazione della scansione, consentendo alle pipeline di caricare i risultati senza dover creare manualmente un Test in anticipo. + +Quando si utilizza l'API o la CLI per importare i risultati della scansione, è possibile creare automaticamente un nuovo Test fornendo un `engagement` invece di un `test`. + +##### API +curl -X POST `"https:///api/v2/import-scan/"` \ + -H `"Authorization: Token "` \ + -F `"engagement=45"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` +In base a quanto sopra, viene creato un nuovo Test nell'Engagement specificato e i risultati della scansione vengono collegati a quel Test. + +Se viene invece fornito un ID `test`, i risultati della scansione verranno aggiunti a un Test esistente, il che è comune nei flussi di lavoro di reimportazione. + +##### CLI +defectdojo-cli import \ + --engagement-id 45 \ + --scan-type `"ZAP Scan"` \ +GOog --file report.xml +In base a quanto sopra, fornire un `engagement-id` crea un nuovo Test, mentre fornire un `test-id` riutilizza un Test esistente e reimporta i risultati della scansione in quel Test. + +Consulta [DefectDojo-CLI](/import_data/pro/specialized_import/external_tools/#defectdojo-cli) per maggiori dettagli sui flag richiesti. + +### Modificare i Test + +I Test possono essere modificati facendo clic su **Edit Test** all'interno del menu a ingranaggio. Tutti i campi modificabili successivamente sono disponibili anche durante la creazione del Test. + +### Eliminare i Test + +È possibile eliminare un Test selezionando **Delete Test** dalle impostazioni del Test. Questa azione non può essere annullata. + +L'eliminazione di un Test comporterà anche l'eliminazione di tutti i Riscontri contenuti al suo interno. + +### Reimportazione dei risultati della scansione (UI) + +Per aggiungere nuovi dati a un Test esistente, apri il Test a cui vuoi aggiungere i nuovi dati e fai clic sul pulsante Reimport Findings nelle impostazioni del Test oppure sul pulsante Reimport Scan nella tabella dei Riscontri. + +![image](images/tests_ss21.png) + +Durante la compilazione del modulo Reimport Scan, avrai la possibilità di aggiornare i metadati per la scansione in fase di reimportazione, tra cui versione, branch tag, commit hash e build ID. Queste modifiche si riflettono nella sezione Import History della visualizzazione del Test, che includerà anche gli stessi metadati delle importazioni di scansione precedenti. + +Ad esempio, nello screenshot seguente, il branch tag, il build ID, il commit hash e la versione sono stati tutti aggiornati manualmente tra l'importazione iniziale e la reimportazione successiva. + +![image](images/tests_ss23.png) + +Per modificare i metadati della scansione reimportata più di recente, fai clic sull'icona a ingranaggio situata nell'angolo in alto a destra di una visualizzazione dell'Engagement e seleziona “Edit Test.” È possibile modificare solo i metadati dell'importazione più recente. + +### Reimportazione dei risultati della scansione (API/CLI) + +Quando i Test vengono creati o aggiornati tramite una pipeline CI/CD, è possibile includere i metadati dell'esecuzione della pipeline in modo che i Test possano essere correttamente collegati al codice che hanno scansionato. Questo ti consente di: +- Associare i risultati della scansione a un commit o branch specifico. +- Monitorare come i Riscontri evolvono nel corso delle modifiche al codice. +- Migliorare la Deduplicazione comprendendo quando due scansioni si riferiscono alla stessa versione del codice o a versioni diverse. +- Supportare la verificabilità mostrando esattamente quale codice è stato scansionato e quando. + +La CLI e l'API di DefectDojo accettano questi valori durante l'importazione o la reimportazione, in modo che possano essere memorizzati come parte dell'importazione della scansione e riflessi nella cronologia delle importazioni del Test. Questi metadati possono essere utilizzati per identificare i commit hash o qualsiasi informazione pertinente sul repository associata a un'esecuzione CI/CD. + +#### Campi di metadati supportati + +L'API e la CLI supportano un insieme definito di campi di metadati che possono essere inclusi durante la reimportazione. Questi includono: + +- `tags` +- `version` +- `build_id` +- `branch_tag` +- `commit_hash` +- `scan_date` +- `minimum_severity` +- flag `active / verified` + +Questi campi rappresentano il meccanismo principale per allegare metadati contestuali durante un'operazione di reimportazione. + +Nelle pipeline automatizzate, i metadati più comunemente forniti includono: +- `build_id` (identificatore del job CI) +- `commit_hash` (riferimento al controllo di versione) +- `branch_tag` (contesto di branch o ambiente) +- `tags` (ad es. `nightly`, `staging`, `production`) + +Questi campi garantiscono la tracciabilità tra le scansioni senza richiedere interventi manuali. + +Sebbene i metadati possano essere aggiornati manualmente tramite il modulo Reimport Scan, la maggior parte degli ambienti automatizzati gestisce questa operazione chiamando direttamente l'endpoint `/api/v2/reimport-scan/` oppure utilizzando la CLI di DefectDojo (`defectdojo-cli reimport`) come parte del processo di build. Questo approccio consente alla pipeline di allegare automaticamente i metadati al momento della reimportazione. + +##### Reimportazione API con metadati +curl -X POST `"https:///api/v2/reimport-scan/"` \ + -H `"Authorization: Token "` \ + -F `"test=123"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` \ + -F `"tags=nightly,api-scan"` \ + -F `"version=1.4.2"` \ + -F `"build_id=jenkins-842"` \ + -F `"branch_tag=main"` \ + -F `"commit_hash=a1b2c3d4"` +##### Reimportazione CLI con metadati +defectdojo-cli import \ + --test-id 123 \ + --scan-type "ZAP Scan" \ + --file report.xml \ + --tag nightly \ + --tag api \ + --build-id jenkins-842 \ + --branch main \ + --commit a1b2c3d4 +La CLI si associa direttamente allo stesso endpoint API e supporta lo stesso insieme di campi di metadati. + +Ci sono alcune limitazioni di cui tenere conto quando si lavora con i metadati durante la reimportazione: +- L'API/CLI supporta solo parametri predefiniti. Non è possibile aggiungere metadati chiave-valore personalizzati durante la reimportazione +- Metadati aggiuntivi possono essere estratti direttamente dal file di scansione, a seconda del tipo di scansione e del parser. +- I metadati forniti durante la reimportazione non si comportano come un aggiornamento diretto dell'oggetto Test, a differenza delle modifiche manuali effettuate nell'interfaccia utente. + +##### Metadati, reimportazione e scansioni pianificate + +Le scansioni possono anche essere pianificate per essere eseguite a intervalli regolari, ad esempio tramite cron job. Le scansioni pianificate non sono legate all'attività del repository, il che rende irrilevanti metadati come i commit hash o i nomi dei branch, a meno che non vengano iniettati esplicitamente dallo script stesso. Ciò nonostante, l'uso della reimportazione può essere comunque utile se si preferisce mantenere un registro continuo della propria postura di sicurezza all'interno di un singolo Test. + +## Reimportazione e Deduplicazione + +La reimportazione delle scansioni all'interno dei Test è fondamentale per una deduplicazione efficace. Quando i risultati della scansione vengono reimportati nello stesso Test: + +- I Riscontri esistenti possono essere aggiornati +- I Riscontri duplicati possono essere soppressi +- Nuovi Riscontri possono essere creati se non viene trovata alcuna corrispondenza + +Questo comportamento dipende dalle regole di deduplicazione configurate e dal tipo di scansione. + +La creazione di un nuovo Test anziché la reimportazione in uno esistente può comportare la creazione di Riscontri duplicati anziché il loro aggiornamento. + +### Reimportazione vs. Importazione + +La reimportazione viene generalmente utilizzata quando: + +- Si eseguono scansioni ricorrenti sullo stesso target +- Si monitora come i Riscontri evolvono nel tempo +- Si mantiene una visione continua della postura di sicurezza dell'applicazione + +Al contrario, l'importazione (creazione di un nuovo Test) è più adatta per esecuzioni di scansione una tantum o indipendenti. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__tests.pt-br.md b/docs/content/asset_modelling/engagements_tests/PRO__tests.pt-br.md new file mode 100644 index 0000000000..03d245b9ce --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__tests.pt-br.md @@ -0,0 +1,285 @@ +--- +title: Testes +description: Entendendo os Testes no DefectDojo Pro +audience: pro +weight: 4 +--- + +Organizações → Ativos → Engajamentos → **TESTES** → Achados + +## Visão geral + +Um Teste é um contêiner para uma ou mais execuções de scan, usadas para descobrir falhas em um Ativo. Os Testes são o componente final e mais granular da hierarquia de objetos do DefectDojo, servindo como o contêiner para os Achados resultantes da execução de uma ferramenta de segurança ou de uma avaliação manual, além de adicionar o contexto no qual esses Achados foram encontrados (ou seja, qual ferramenta os reportou, quando essa ferramenta foi executada pela última vez, etc.). + +Exemplos de Testes incluem: +- Teste Estático de Segurança de Aplicações +- Teste Dinâmico de Segurança de Aplicações +- Análise de Composição de Software +- Varreduras de Segurança de Contêineres +- Varreduras de Infraestrutura / Rede +- Testes de Penetração Manuais +- Varreduras de Pipeline de CI/CD + +### Tipos de Teste + +Existem várias maneiras de criar Testes no DefectDojo, incluindo **parsers específicos de fornecedor** (por exemplo, Burp, OWASP ZAP, Acunetix, Invicti), **Generic Findings Import**, **Universal Parser** e **Connectors**. + +Esses métodos podem criar novos Testes ou reimportar Achados em Testes existentes, dependendo da configuração e da estratégia de deduplicação. + +Embora cada método difira principalmente na forma como os dados de scan são analisados e ingeridos, todos eles resultam, em última instância, na associação de Achados a um Teste. + +#### Parsers + +**Parsers** são componentes que processam formatos específicos de saída de scan (por exemplo, XML, JSON, CSV) e os mapeiam para o modelo interno de Achado do DefectDojo. Quando os resultados de um scan são importados, o DefectDojo usa o parser selecionado para extrair os Achados e anexá-los a um Teste recém-criado ou existente. + +#### Generic Findings Import + +Quando não existe um parser nativo para uma determinada ferramenta, o [**Generic Findings Import**](/supported_tools/parsers/generic_findings_import) permite importar achados usando um schema padronizado em JSON ou CSV, independentemente da origem original. + +O DefectDojo analisa os dados fornecidos, cria um novo Teste (ou importa para um já existente) e anexa os Achados. Um Tipo de Teste correspondente também é criado com base no campo opcional `type` do relatório: quando `type` é omitido (ou é igual ao tipo de scan) o Tipo de Teste é "Generic Findings Import"; quando `type` é fornecido, ele se torna "`{type}` Scan (Generic Findings Import)" (um `type` que já termina com o sufixo "(Generic Findings Import)" é usado literalmente). + +#### Universal Parser + +O [**Universal Parser**](/supported_tools/parsers/universal_parser) permite que os usuários definam como dados de entrada arbitrários são mapeados para o modelo de Achado do DefectDojo. Depois de configurar o parser e enviar os dados do scan, o DefectDojo aplica as regras de mapeamento para extrair os Achados, cria um Teste (ou atualiza um já existente) e associa os Achados a esse Teste. + +#### Connectors + +Os [**Connectors**](/connectors/upstream/about/) podem ser usados para ingerir e organizar automaticamente dados de vulnerabilidades de ferramentas externas por meio de chamadas de API. Uma vez configurado, um Connector busca os resultados do scan, analisa os dados e cria novos Testes ou atualiza Testes existentes, dependendo de sua configuração. Os Achados são então anexados ao Teste correspondente. + +#### Comparação dos Mecanismos de Criação de Teste + +| | **Parsers Nativos** | **Generic Findings Import** | **Universal Parser (Pro)** | **Connectors** | +|----------|---------------|------------------------|------------------------|------------| +| **Finalidade principal** | Ingerir saídas de ferramentas suportadas | Ingerir dados não suportados/personalizados por meio de um schema fixo | Ingerir formatos arbitrários por meio de mapeamentos configuráveis | Sincronizar continuamente sistemas externos | +| **Formato de entrada** | Específico da ferramenta (por exemplo, ZAP XML, SARIF) | Schema JSON/CSV rígido | Arbitrário (JSON, XML etc.) | Respostas de API externas | +| **Quem realiza a normalização** | DefectDojo (parser integrado) | Usuário (deve seguir o schema) | DefectDojo (via configuração do parser) | Ferramenta externa + DefectDojo | +| **Gatilho de criação do Teste** | Upload manual ou importação via API | Upload manual ou importação via API | Upload manual ou importação via API | Sincronização automatizada (agendada ou orientada por evento) | +| **Tipo de Teste** | Predefinido (por exemplo, "ZAP Scan") | Tipo "Generic" criado automaticamente | Derivado da configuração do parser | Depende do connector / parser subjacente | +| **Esforço de configuração** | Baixo | Moderado (requer transformação de dados) | Alto (configuração do parser) | Moderado–Alto (configuração da integração) | +| **Flexibilidade** | Baixa (apenas ferramentas suportadas) | Média | Alta | Média–Alta | +| **Nível de automação** | Baixo–Moderado | Baixo–Moderado | Baixo–Moderado | Alto | +| **Caso de uso típico** | Scanners padrão (SAST, DAST, SCA) | Scripts personalizados, ferramentas não suportadas | Formatos complexos/personalizados em escala | Integrações de CI/CD, SCM ou plataforma | + +Independentemente do método de ingestão, todos os dados de scan no DefectDojo são, em última instância, representados como Achados anexados a um Teste, que serve como a unidade de execução e de acompanhamento do ciclo de vida. + +### Dados do Teste + +Os Testes armazenam uma variedade de metadados que ajudam a documentar vários componentes de cada esforço de teste, como: +- Título / nome do Teste +- Tipo de Teste +- Descrição / notas do Teste +- Data de início e término +- O Ambiente em que o Teste foi executado (por exemplo, Development, Staging, Pre-Production, Production, etc.) +- Versão / Branch / Build ID / Commit Hash +- Configuração de scan de API +- Pessoal associado ao Teste +- Arquivos adicionais que podem ser usados para auditorias ou reimportações futuras +- O Engajamento, o Ativo e a Organização pai +- Histórico de importação e reimportação + +Cada Teste mantém um histórico de importação, que registra todas as importações e reimportações de scan associadas ao Teste. Cada item do histórico inclui metadados como data do scan, versão, branch, commit hash e build ID. + +Esse histórico proporciona rastreabilidade entre múltiplas execuções de scan dentro do mesmo Teste. + +### Permissões + +Vários Testes podem ser armazenados dentro de um único Engajamento, e os Engajamentos são armazenados dentro de Ativos. Assim, o acesso a um Ativo concede automaticamente acesso a todos os Testes (e Engajamentos) dentro desse Ativo. Os Testes não possuem listas de controle de acesso independentes. + +## Acessando Testes + +Os Testes podem ser acessados em várias seções da interface do DefectDojo. + +- A barra lateral + +![image](images/tests_ss13.png) + +- Dentro de um Engajamento + +![image](images/tests_ss14.png) + +- A barra superior de um Ativo + +![image](images/tests_ss15.png) + +- A tabela de Metadados na visualização de um Achado + +![image](images/tests_ss16.png) + +## Trabalhando com Testes + +### Criar Testes + +Os Testes podem ser criados automaticamente quando os dados de um scan são importados diretamente em um Engajamento, resultando em um novo Teste contendo os dados do scan. Os Testes também podem ser criados antecipadamente, para planejar futuros Engajamentos, ou para achados de segurança inseridos manualmente que exijam acompanhamento e remediação. + +#### Fluxos de Trabalho Manuais + +Para criar um Teste, é necessário que exista um Engajamento para contê-lo, bem como um Ativo que conterá esse Engajamento. Depois disso, há várias maneiras de criar um Teste: + +- Na barra lateral, em Testes, dentro da subseção **Manage** + - Você precisará selecionar o Engajamento pré-existente ao qual atribuir o Teste ao preencher o formulário de Novo Teste. + +![image](images/tests_ss1.png) + +- O menu suspenso de configurações no canto superior direito da visualização de um Ativo + - **Import Scan** criará automaticamente um Teste assim que um arquivo de scan for adicionado ao formulário de Import Scan. Você terá a opção de atribuir o Teste a um Engajamento pré-existente ou criar e nomear um novo Engajamento para conter o novo Teste. + - Ao preencher o formulário de Import Scan, você pode adicionar metadados como a versão, a branch tag, o commit hash e o build ID. Isso será refletido na seção de Histórico de Importação da visualização do Teste. + +![image](images/tests_ss2.png) + +- O menu suspenso de configurações no canto superior direito da visualização de um Engajamento + - **Import Scan** seguirá o mesmo fluxo de trabalho dos Ativos, mas colocará automaticamente o objeto Teste dentro do Engajamento no qual você clicou em Import Scan. + - **Add Test** criará um objeto Teste, mas não exige que um scan seja enviado para o próprio Teste, o que é útil para planejar futuros Testes antecipadamente ou para achados de segurança inseridos manualmente que exijam acompanhamento e remediação. + +![image](images/tests_ss3.png) + +Se você selecionar Add Test e mais tarde desejar importar manualmente os resultados de um scan para um Teste, você pode fazer isso abrindo o Teste e clicando no botão Reimport Findings nas configurações do Teste ou no botão Reimport Scan na tabela de Achados. + +![image](images/tests_ss21.png) + +#### Fluxos de Trabalho Automatizados + +Em fluxos de trabalho automatizados, os Testes podem ser criados programaticamente como parte do processo de importação de scan, permitindo que os pipelines enviem resultados sem exigir que um Teste seja criado manualmente com antecedência. + +Ao usar a API ou a CLI para importar resultados de scan, um novo Teste pode ser criado automaticamente fornecendo um `engagement` em vez de um `test`. + +##### API + +curl -X POST `"https:///api/v2/import-scan/"` \ + -H `"Authorization: Token "` \ + -F `"engagement=45"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` + +Diante do exemplo acima, um novo Teste é criado dentro do Engajamento especificado, e os resultados do scan são anexados a esse Teste. + +Se um ID de `test` for fornecido em vez disso, os resultados do scan serão adicionados a um Teste existente, o que é comum em fluxos de trabalho de reimportação. + +##### CLI + +Usando a CLI do DefectDojo, esse comportamento é tratado automaticamente com base nos argumentos fornecidos. + +defectdojo-cli import \ + --engagement-id 45 \ + --scan-type `"ZAP Scan"` \ +GOog --file report.xml + +Diante do exemplo acima, fornecer um `engagement-id` cria um novo Teste, e fornecer um `test-id` reutiliza um Teste existente e reimporta os resultados do scan nesse Teste. + +Consulte [DefectDojo-CLI](/import_data/pro/specialized_import/external_tools/#defectdojo-cli) para mais detalhes sobre as flags necessárias. + +### Editar Testes + +Os Testes podem ser editados clicando em **Edit Test** no menu de engrenagem. Todos os campos subsequentes que podem ser editados também estão disponíveis quando o Teste está sendo criado. + +### Excluir Testes + +A exclusão de um Teste pode ser realizada selecionando **Delete Test** nas configurações do Teste. Essa ação não pode ser desfeita. + +Excluir um Teste também excluirá todos os Achados contidos nesse Teste. + +### Reimportando Resultados de Scan (UI) + +Para adicionar novos dados a um Teste existente, abra o Teste ao qual deseja adicionar novos dados e clique no botão Reimport Findings nas configurações do Teste ou no botão Reimport Scan na tabela de Achados. + +![image](images/tests_ss21.png) + +Ao preencher o formulário de Reimport Scan, você terá a opção de atualizar os metadados do scan sendo reimportado, incluindo a versão, a branch tag, o commit hash e o build ID. Essas alterações são refletidas na seção de Histórico de Importação da visualização do Teste, que também incluirá os mesmos metadados das importações de scan anteriores. + +Por exemplo, na captura de tela abaixo, a branch tag, o build ID, o commit hash e a versão foram todos atualizados manualmente entre a importação inicial e a reimportação subsequente. + +![image](images/tests_ss23.png) + +Para editar os metadados do scan reimportado mais recentemente, clique no ícone de engrenagem localizado no canto superior direito da visualização de um Engajamento e selecione "Edit Test". Apenas os metadados da importação mais recente podem ser editados. + +### Reimportando Resultados de Scan (API/CLI) + +Quando os Testes são criados ou atualizados por meio de um pipeline de CI/CD, é possível incluir metadados da execução do pipeline para que os Testes possam ser corretamente vinculados ao código que analisaram. Isso permite que você: +- Associe os resultados do scan a um commit ou branch específico. +- Acompanhe como os Achados evoluem ao longo das alterações de código. +- Melhore a Deduplicação entendendo quando dois scans se aplicam à mesma versão do código ou a versões diferentes. +- Dê suporte à auditabilidade, mostrando exatamente qual código foi analisado e quando. + +A CLI e a API do DefectDojo aceitam esses valores durante a importação ou reimportação, para que possam ser armazenados como parte da importação do scan e refletidos no histórico de importação do Teste. Esses metadados podem ser usados para identificar commit hashes ou qualquer informação relevante de repositório associada a uma execução de CI/CD. + +#### Campos de Metadados Suportados + +A API e a CLI oferecem suporte a um conjunto definido de campos de metadados que podem ser incluídos durante a reimportação. Estes incluem: + +- `tags` +- `version` +- `build_id` +- `branch_tag` +- `commit_hash` +- `scan_date` +- `minimum_severity` +- flags `active / verified` + +Esses campos representam o mecanismo principal para anexar metadados contextuais durante uma operação de reimportação. + +Em pipelines automatizados, os metadados mais comumente fornecidos incluem: +- `build_id` (identificador do job de CI) +- `commit_hash` (referência de controle de versão) +- `branch_tag` (contexto de branch ou ambiente) +- `tags` (por exemplo, `nightly`, `staging`, `production`) + +Esses campos fornecem rastreabilidade entre os scans sem exigir intervenção manual. + +Embora os metadados possam ser atualizados manualmente por meio do formulário de Reimport Scan, a maioria dos ambientes automatizados fará isso chamando diretamente o endpoint `/api/v2/reimport-scan/` ou usando a CLI do DefectDojo (`defectdojo-cli reimport`) como parte do processo de build. Essa abordagem permite que o pipeline anexe automaticamente os metadados durante a reimportação. + +##### Reimportação via API com Metadados + +curl -X POST `"https:///api/v2/reimport-scan/"` \ + -H `"Authorization: Token "` \ + -F `"test=123"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` \ + -F `"tags=nightly,api-scan"` \ + -F `"version=1.4.2"` \ + -F `"build_id=jenkins-842"` \ + -F `"branch_tag=main"` \ + -F `"commit_hash=a1b2c3d4"` + +##### Reimportação via CLI com Metadados + +defectdojo-cli import \ + --test-id 123 \ + --scan-type "ZAP Scan" \ + --file report.xml \ + --tag nightly \ + --tag api \ + --build-id jenkins-842 \ + --branch main \ + --commit a1b2c3d4 + +A CLI mapeia diretamente para o mesmo endpoint da API e oferece suporte ao mesmo conjunto de campos de metadados. + +Há algumas limitações a serem consideradas ao trabalhar com metadados durante a reimportação: +- A API/CLI oferece suporte apenas a parâmetros predefinidos. Metadados personalizados no formato chave-valor não podem ser adicionados durante a reimportação +- Metadados adicionais podem ser extraídos do próprio arquivo de scan, dependendo do tipo de scan e do parser. +- Os metadados fornecidos durante a reimportação não se comportam como uma atualização direta do objeto Teste, da mesma forma que as edições manuais feitas na UI. + +##### Metadados, Reimportação e Scans Agendados + +Os scans também podem ser agendados para serem executados em intervalos rotineiros, como os disparados por cron jobs. Scans agendados não estão vinculados à atividade do repositório, o que torna metadados como commit hashes ou nomes de branch irrelevantes, a menos que sejam explicitamente injetados pelo próprio script. Ainda assim, usar a reimportação pode ser útil se você preferir manter um registro contínuo da sua postura de segurança dentro de um único Teste. + +## Reimportação e Deduplicação + +Reimportar scans dentro dos Testes é fundamental para uma deduplicação eficaz. Quando os resultados de um scan são reimportados no mesmo Teste: + +- Achados existentes podem ser atualizados +- Achados duplicados podem ser suprimidos +- Novos Achados podem ser criados se nenhuma correspondência for encontrada + +Esse comportamento depende das regras de deduplicação configuradas e do tipo de scan. + +Criar um novo Teste em vez de reimportar em um já existente pode resultar na criação de Achados duplicados em vez de sua atualização. + +### Reimportação vs. Importação + +A reimportação é normalmente usada quando: + +- Executando scans recorrentes contra o mesmo alvo +- Acompanhando como os Achados evoluem ao longo do tempo +- Mantendo uma visão contínua da postura de segurança da aplicação + +Em contraste, a importação (criação de um novo Teste) é mais adequada para execuções de scan únicas ou independentes. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__tests.zh-hans.md b/docs/content/asset_modelling/engagements_tests/PRO__tests.zh-hans.md new file mode 100644 index 0000000000..dbffcc8b49 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__tests.zh-hans.md @@ -0,0 +1,285 @@ +--- +title: 测试 +description: 了解 DefectDojo Pro 中的测试 +audience: pro +weight: 4 +--- + +Organizations → Assets → Engagements → **TESTS** → Findings + +## 概述 + +测试是一个或多个扫描执行的容器，用于发现资产中的缺陷。测试是 DefectDojo 对象层级中最终、最细粒度的组成部分，它是安全工具执行或人工评估所产生发现项的容器，同时也添加了发现这些发现项时的上下文（即报告该发现项的工具是什么、该工具最近一次运行是什么时候等）。 + +测试的示例包括： +- 静态应用程序安全测试 +- 动态应用程序安全测试 +- 软件成分分析 +- 容器安全扫描 +- 基础设施/网络扫描 +- 手动渗透测试 +- CI/CD 流水线扫描 + +### 测试类型 + +在 DefectDojo 中创建测试的方法有多种，包括**特定厂商解析器**（例如 Burp、OWASP ZAP、Acunetix、Invicti）、**通用发现项导入**、**通用解析器**以及**连接器**。 + +这些方法可以创建新测试，也可以根据配置和去重策略将发现项重新导入到现有测试中。 + +虽然这些方法在解析和摄取扫描数据的方式上各不相同，但最终都会将发现项关联到某个测试。 + +#### 解析器 + +**解析器**是处理特定扫描输出格式（例如 XML、JSON、CSV）并将其映射到 DefectDojo 内部发现项模型的组件。导入扫描结果时，DefectDojo 会使用所选解析器提取发现项，并将其附加到新创建或现有的测试中。 + +#### 通用发现项导入 + +当某个工具没有原生解析器时，[**通用发现项导入**](/supported_tools/parsers/generic_findings_import) 允许您使用标准化的 JSON 或 CSV 架构导入发现项，无论其原始来源是什么。 + +DefectDojo 会解析提供的数据，创建新测试（或导入到现有测试中），并附加发现项。系统还会根据报告中可选的 `type` 字段创建相应的测试类型：当省略 `type`（或其值等于扫描类型）时，测试类型为 "Generic Findings Import"；当提供了 `type` 时，测试类型变为 "`{type}` Scan (Generic Findings Import)"（如果 `type` 值已经以 "(Generic Findings Import)" 后缀结尾，则按原样使用）。 + +#### 通用解析器 + +[**通用解析器**](/supported_tools/parsers/universal_parser) 允许用户定义任意输入数据如何映射到 DefectDojo 的发现项模型。配置解析器并上传扫描数据后，DefectDojo 会应用映射规则提取发现项，创建测试（或更新现有测试），并将发现项与该测试关联。 + +#### 连接器 + +[**连接器**](/connectors/upstream/about/) 可用于通过 API 调用自动摄取和整理来自外部工具的漏洞数据。配置完成后，连接器会获取扫描结果、解析数据，并根据其配置创建新测试或更新现有测试。随后，发现项会被附加到相应的测试中。 + +#### 测试创建机制对比 + +| | **原生解析器** | **通用发现项导入** | **通用解析器（Pro）** | **连接器** | +|----------|---------------|------------------------|------------------------|------------| +| **主要用途** | 摄取受支持工具的输出 | 通过固定架构摄取不受支持/自定义的数据 | 通过可配置映射摄取任意格式 | 持续同步外部系统 | +| **输入格式** | 特定工具格式（例如 ZAP XML、SARIF） | 严格的 JSON/CSV 架构 | 任意格式（JSON、XML 等） | 外部 API 响应 | +| **由谁负责规范化** | DefectDojo（内置解析器） | 用户（必须符合架构要求） | DefectDojo（通过解析器配置） | 外部工具 + DefectDojo | +| **测试创建触发方式** | 手动上传或 API 导入 | 手动上传或 API 导入 | 手动上传或 API 导入 | 自动同步（定时或事件驱动） | +| **测试类型** | 预定义（例如 "ZAP Scan"） | 自动创建 "Generic" 类型 | 来自解析器配置 | 取决于连接器/底层解析器 | +| **配置工作量** | 低 | 中等（需要数据转换） | 高（需要解析器配置） | 中到高（需要集成配置） | +| **灵活性** | 低（仅限受支持工具） | 中 | 高 | 中到高 | +| **自动化程度** | 低到中等 | 低到中等 | 低到中等 | 高 | +| **典型使用场景** | 标准扫描器（SAST、DAST、SCA） | 自定义脚本、不受支持的工具 | 大规模复杂/自定义格式 | CI/CD、SCM 或平台集成 | + +无论采用哪种摄取方式，DefectDojo 中的所有扫描数据最终都会以附加到某个测试的发现项形式呈现，该测试即为执行与生命周期跟踪的基本单元。 + +### 测试数据 + +测试会存储多种元数据，用于记录每次测试工作的各个组成部分，例如： +- 测试标题/名称 +- 测试类型 +- 测试描述/备注 +- 开始和结束日期 +- 运行测试所在的环境（例如开发、预发布、生产前、生产等） +- 版本/分支/构建 ID/提交哈希 +- API 扫描配置 +- 与该测试相关的人员 +- 可用于后续审计或重新导入的其他文件 +- 上级测试活动、资产和组织 +- 导入和重新导入历史 + +每个测试都会维护一份导入历史记录，记录与该测试相关的所有扫描导入和重新导入操作。每条历史记录都包含扫描日期、版本、分支、提交哈希和构建 ID 等元数据。 + +该历史记录为同一测试内的多次扫描执行提供了可追溯性。 + +### 权限 + +一个测试活动中可以存储多个测试，而测试活动又存储在资产中。因此，对某个资产的访问权限会自动授予该资产内所有测试（及测试活动）的访问权限。测试没有独立的访问控制列表。 + +## 访问测试 + +可以从 DefectDojo 界面的多个位置访问测试。 + +- 侧边栏 + +![image](images/tests_ss13.png) + +- 测试活动内部 + +![image](images/tests_ss14.png) + +- 资产的顶部栏 + +![image](images/tests_ss15.png) + +- 发现项视图中的元数据表 + +![image](images/tests_ss16.png) + +## 使用测试 + +### 创建测试 + +当扫描数据直接导入到某个测试活动时，可以自动创建测试，其中包含该扫描数据。也可以为规划未来的测试活动提前创建测试，或者为需要跟踪和修复的手动录入安全发现项创建测试。 + +#### 手动工作流 + +要创建一个测试，必须先创建一个用于容纳它的测试活动，以及一个用于容纳该测试活动的资产。之后，有以下几种方式可以创建测试： + +- 在侧边栏的**管理**子部分下的“测试”中 + - 在填写新建测试表单时，您需要选择一个已存在的测试活动，将该测试归属于其中。 + +![image](images/tests_ss1.png) + +- 资产视图右上角的设置下拉菜单 + - **导入扫描**会在扫描文件添加到导入扫描表单后自动创建一个测试。您可以选择将该测试归属于一个已存在的测试活动，或创建并命名一个新的测试活动来容纳该测试。 + - 在填写导入扫描表单时，您可以添加版本、分支标记、提交哈希和构建 ID 等元数据。这些信息会体现在测试视图的导入历史部分中。 + +![image](images/tests_ss2.png) + +- 测试活动视图右上角的设置下拉菜单 + - **导入扫描**遵循与资产相同的工作流程，但会自动将该测试对象放置在您点击导入扫描时所在的测试活动内。 + - **添加测试**会创建一个测试对象，但不要求为该测试本身上传扫描文件，这在提前规划未来的测试，或需要跟踪和修复的手动录入安全发现项时非常有用。 + +![image](images/tests_ss3.png) + +如果您选择了添加测试，之后又想手动将扫描结果导入该测试，可以打开该测试，然后点击测试设置中的“重新导入发现项”按钮，或发现项表格中的“重新导入扫描”按钮。 + +![image](images/tests_ss21.png) + +#### 自动化工作流 + +在自动化工作流中，可以在扫描导入过程中以编程方式创建测试，从而使流水线能够上传结果，而无需事先手动创建测试。 + +使用 API 或 CLI 导入扫描结果时，只需提供 `engagement` 而非 `test`，即可自动创建一个新测试。 + +##### API + +curl -X POST `"https:///api/v2/import-scan/"` \ + -H `"Authorization: Token "` \ + -F `"engagement=45"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` + +通过以上命令，会在指定的测试活动下创建一个新测试，并将扫描结果附加到该测试中。 + +如果改为提供 `test` ID，扫描结果将被添加到现有测试中，这在重新导入工作流中很常见。 + +##### CLI + +使用 DefectDojo CLI 时，该行为会根据所提供的参数自动处理。 + +defectdojo-cli import \ + --engagement-id 45 \ + --scan-type `"ZAP Scan"` \ +GOog --file report.xml + +通过以上命令，提供 `engagement-id` 会创建一个新测试，而提供 `test-id` 则会复用现有测试，并将扫描结果重新导入该测试。 + +有关所需标志的更多详细信息，请参阅 [DefectDojo-CLI](/import_data/pro/specialized_import/external_tools/#defectdojo-cli)。 + +### 编辑测试 + +点击齿轮菜单中的**编辑测试**即可编辑测试。所有可编辑的字段在创建测试时同样可用。 + +### 删除测试 + +可以通过在测试的设置中选择**删除测试**来删除测试。此操作无法撤销。 + +删除测试还会删除该测试中包含的所有发现项。 + +### 重新导入扫描结果（界面） + +要向现有测试添加新数据，请打开要添加数据的测试，然后点击测试设置中的“重新导入发现项”按钮，或发现项表格中的“重新导入扫描”按钮。 + +![image](images/tests_ss21.png) + +在填写重新导入扫描表单时，您可以选择更新正在重新导入的扫描的元数据，包括版本、分支标记、提交哈希和构建 ID。这些更改会体现在测试视图的导入历史部分中，其中也会包含之前扫描导入的相同元数据。 + +例如，在下方截图中，分支标记、构建 ID、提交哈希和版本在初次导入和后续重新导入之间都被手动更新过。 + +![image](images/tests_ss23.png) + +要编辑最近一次重新导入扫描的元数据，请点击测试活动视图右上角的齿轮图标，然后选择“编辑测试”。只能编辑最近一次导入的元数据。 + +### 重新导入扫描结果（API/CLI） + +当通过 CI/CD 流水线创建或更新测试时，您可以包含来自流水线运行的元数据，以便将测试正确关联到其所扫描的代码。这使您能够： +- 将扫描结果与特定提交或分支关联。 +- 跟踪发现项在代码变更过程中的演变情况。 +- 通过了解两次扫描是否适用于相同或不同版本的代码来改进去重。 +- 通过准确显示扫描了哪些代码以及扫描时间来支持可审计性。 + +DefectDojo 的 CLI 和 API 在导入或重新导入期间接受这些值，以便将其作为扫描导入的一部分存储，并体现在测试的导入历史中。此元数据可用于识别提交哈希，或与 CI/CD 运行相关的任何相关代码仓库信息。 + +#### 支持的元数据字段 + +API 和 CLI 支持一组预定义的元数据字段，可在重新导入期间包含这些字段。包括： + +- `tags` +- `version` +- `build_id` +- `branch_tag` +- `commit_hash` +- `scan_date` +- `minimum_severity` +- `active / verified` 标志 + +这些字段是在重新导入操作期间附加上下文元数据的主要机制。 + +在自动化流水线中，最常提供的元数据包括： +- `build_id`（CI 作业标识符） +- `commit_hash`（源代码控制引用） +- `branch_tag`（分支或环境上下文） +- `tags`（例如 `nightly`、`staging`、`production`） + +这些字段无需人工干预即可提供跨扫描的可追溯性。 + +虽然可以通过重新导入扫描表单手动更新元数据，但大多数自动化环境会直接调用 `/api/v2/reimport-scan/` 端点，或在构建过程中使用 DefectDojo CLI（`defectdojo-cli reimport`）来处理这一操作。这种方式可以让流水线在重新导入时自动附加元数据。 + +##### 带元数据的 API 重新导入 + +curl -X POST `"https:///api/v2/reimport-scan/"` \ + -H `"Authorization: Token "` \ + -F `"test=123"` \ + -F `"scan_type=ZAP Scan"` \ + -F `"file=@report.xml"` \ + -F `"tags=nightly,api-scan"` \ + -F `"version=1.4.2"` \ + -F `"build_id=jenkins-842"` \ + -F `"branch_tag=main"` \ + -F `"commit_hash=a1b2c3d4"` + +##### 带元数据的 CLI 重新导入 + +defectdojo-cli import \ + --test-id 123 \ + --scan-type "ZAP Scan" \ + --file report.xml \ + --tag nightly \ + --tag api \ + --build-id jenkins-842 \ + --branch main \ + --commit a1b2c3d4 + +CLI 直接映射到相同的 API 端点，并支持相同的一组元数据字段。 + +在重新导入期间处理元数据时，需要注意以下一些限制： +- API/CLI 仅支持预定义参数。重新导入期间无法添加自定义键值元数据 +- 根据扫描类型和解析器的不同，可能会从扫描文件本身提取其他元数据。 +- 重新导入期间提供的元数据不会像在界面中手动编辑那样直接更新测试对象。 + +##### 元数据、重新导入与计划扫描 + +扫描也可以设置为按固定间隔运行，例如由 cron 作业触发的扫描。计划扫描与代码仓库活动无关，因此除非脚本本身显式注入，否则提交哈希或分支名称等元数据并不适用。不过，如果您希望在单个测试中保留安全态势的滚动记录，使用重新导入仍然会很有用。 + +## 重新导入与去重 + +在测试中重新导入扫描是实现有效去重的基础。当扫描结果被重新导入到同一测试中时： + +- 现有发现项可能会被更新 +- 重复的发现项可能会被抑制 +- 如果未找到匹配项，可能会创建新的发现项 + +此行为取决于所配置的去重规则和扫描类型。 + +创建新测试而不是重新导入到现有测试中，可能会导致创建重复的发现项，而不是更新它们。 + +### 重新导入与导入的对比 + +通常在以下情况下使用重新导入： + +- 对同一目标运行重复性扫描 +- 跟踪发现项随时间的演变情况 +- 维护应用程序安全态势的连续视图 + +相比之下，导入（创建新测试）更适合一次性或独立的扫描执行。 diff --git a/docs/content/asset_modelling/engagements_tests/_index.it.md b/docs/content/asset_modelling/engagements_tests/_index.it.md new file mode 100644 index 0000000000..86a03d841d --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/_index.it.md @@ -0,0 +1,8 @@ +--- +title: Engagement e Test +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +--- diff --git a/docs/content/asset_modelling/engagements_tests/_index.pt-br.md b/docs/content/asset_modelling/engagements_tests/_index.pt-br.md new file mode 100644 index 0000000000..3b19d8d713 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/_index.pt-br.md @@ -0,0 +1,8 @@ +--- +title: Engajamentos e Testes +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +--- diff --git a/docs/content/asset_modelling/engagements_tests/_index.zh-hans.md b/docs/content/asset_modelling/engagements_tests/_index.zh-hans.md new file mode 100644 index 0000000000..b859c6b3c5 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/_index.zh-hans.md @@ -0,0 +1,8 @@ +--- +title: 测试活动与测试 +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +--- diff --git a/docs/content/asset_modelling/locations/PRO__locations_overview.it.md b/docs/content/asset_modelling/locations/PRO__locations_overview.it.md new file mode 100644 index 0000000000..dac1c132d8 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__locations_overview.it.md @@ -0,0 +1,80 @@ +--- +title: Panoramica delle Posizioni +description: Cosa sono le Posizioni e perché sostituiscono gli Endpoint +audience: pro +weight: 1 +--- + +Le **Posizioni** sono un nuovo strumento di modellazione degli asset in DefectDojo Pro. Sostituiscono il modello legacy degli **Endpoint** e assorbono i precedenti dati dei **Componenti** (librerie), offrendo a DefectDojo un modo unico e polimorfico per descrivere *dove* si trova un Riscontro — che si tratti di un URL, di una dipendenza software proveniente da una **SBOM**, oppure, in futuro, di un **ID di risorsa cloud**, di un'**immagine container** o di un **repository di codice**. + +Le Posizioni devono essere abilitate sulla tua istanza prima di poterle utilizzare. Puoi abilitare autonomamente le Posizioni dalla [pagina dei Feature Flag](/admin/feature_flags/pro__feature_flags/) — non è richiesta alcuna richiesta al Supporto. Tieni presente che, una volta abilitate, le Posizioni non possono più essere disattivate. + +## Perché sostituire gli Endpoint? + +Il modello originale degli Endpoint era costruito attorno a URL e indirizzi IP — includeva campi tipici delle applicazioni web come `protocol`, `host`, `port`, `path`, e una tabella di stato fissa strettamente accoppiata ai Riscontri. Ne derivavano tre problemi: + +1. **Fedeltà limitata.** Gli Endpoint non potevano descrivere in modo pulito asset non-URL come librerie di terze parti, immagini container o risorse cloud, nonostante gli scanner producano sempre più spesso riscontri relativi a questi elementi. +2. **Limite di prestazioni.** Le righe Endpoint_Status per ciascun Riscontro e lo schema modellato sugli URL non scalavano bene con grandi volumi di clienti. +3. **I Componenti erano di seconda classe.** Le librerie software esistevano solo come campi denormalizzati su un Riscontro, quindi una libreria non poteva esistere indipendentemente da una vulnerabilità — rendendo impossibile una vera gestione delle SBOM. + +Le Posizioni risolvono tutti e tre i problemi introducendo un **oggetto `Location` di base** con un payload tipizzato, oltre a **sottotipi** dedicati per ciascuna forma di asset: + +- **Posizioni URL** — equivalente funzionale dei vecchi Endpoint, con gli stessi campi protocol/host/port/path/query/fragment. +- **Posizioni Dipendenza** — librerie software identificate tramite [Package URL (pURL)](https://github.com/package-url/purl-spec), utilizzate per modellare il contenuto delle SBOM. +- **[Posizioni Codice Sorgente](/asset_modelling/locations/pro__source_code_locations/)** — dove risiede nel codice sorgente un riscontro di analisi statica, identificato da percorso file e numero di riga. Gestite dalla scansione, e sono il substrato per [il tracciamento dei riscontri al variare del codice](/triage_findings/finding_deduplication/pro__location_drift_matching/). + +Tra i futuri tipi di Posizione in fase di valutazione figurano gli ID di risorsa dei cloud provider (AWS ARN, Azure Resource ID, GCP Full Resource Name) e le immagini container (registry/repository:tag e impronte SHA256). + +## Concetti chiave + +### Posizioni e sottotipi + +Una **Location** è il genitore condiviso. Contiene: + +- Un `Location Type` (ad es. `"url"`, `"dependency"`) +- Una stringa `Location Value` canonica, utilizzata per la visualizzazione, la ricerca e la deduplicazione +- `Tags` e i tag ereditati dall'Asset padre +- Metadati (coppie chiave/valore personalizzate) + +Un **sottotipo** (URL o Dependency) contiene i campi strutturati specifici per quel tipo di posizione. Gli URL e le Dependency vivono sempre accanto a un oggetto Location padre; il `Location Value` del sottotipo viene generato a partire dai suoi campi strutturati. + +### Riferimenti + +Le Posizioni non sono collegate direttamente a Prodotti o Riscontri. Sono invece due oggetti **Reference** a collegarle: + +- **Asset Reference** — le relazioni che la Posizione ha con gli Asset (ad es. `libFoo` è *di proprietà di* Asset 6, *utilizzata da* Asset 9). Ogni riferimento ha uno stato (`Active` o `Mitigated`) e una **relazione** opzionale ("Used By" o "Owned By"). +- **Finding Reference** — le relazioni che la Posizione ha con i Riscontri. Ogni riferimento ha uno stato più articolato (`Active`, `Mitigated`, `False Positive`, `Risk Accepted`, `Out of Scope`) oltre all'auditor e all'orario di audit. + +Questa separazione è ciò che consente a una libreria di esistere su un Prodotto *senza* richiedere un Riscontro — una funzionalità mancante nel vecchio modello dei Componenti. + +### Associazione automatica al momento dell'importazione + +Quando un parser produce un Riscontro che fa riferimento a un URL o a una libreria, l'importer: + +1. Cerca una Posizione esistente corrispondente all'URL o al pURL; se non ne esiste una, la crea. +2. Crea un Finding Reference che collega il Riscontro alla Posizione con stato `Active`. +3. Crea (o riutilizza) un Asset Reference in modo che la Posizione risieda anche sull'Asset padre. + +I parser esistenti sono stati aggiornati per generare dati di Location quando il feature flag è attivo, e per ricadere sul vecchio modello Endpoint quando è disattivato. Non è necessaria alcuna riconfigurazione quando le Posizioni sono abilitate — la prossima importazione passerà automaticamente attraverso la pipeline delle Posizioni. + +## Cosa include l'MVP + +| Funzionalità | Stato | +| --- | --- | +| Modelli fondamentali `Location`, `URL`, `Dependency` | Rilasciato | +| API REST per Location e Reference | Rilasciato (`Location` in sola lettura, CRUD completo su Reference) | +| Shim di compatibilità in lettura per l'API Endpoint | Rilasciato | +| Comando di migrazione monodirezionale Endpoint → URL | Rilasciato | +| Aggiornamenti dei parser (URL e dipendenze) | Rilasciato per i parser principali | +| Caricamento SBOM (CycloneDX, SPDX v2/v3) | Rilasciato tramite `/api/v2/sbom-import/` | +| UI Pro per Location, URL, Dependency | Rilasciato | +| Ricerca/filtro pURL | Rilasciato | +| Tracciamento delle licenze sulle dipendenze | Parziale (campo `license_expression`) | +| Formato SBOM SWID Tag | Non incluso nell'MVP | + +## Prossimi passi + +- **Abilita la funzionalità** — contatta [support@defectdojo.com](mailto:support@defectdojo.com) per attivare le Posizioni sulla tua istanza. +- **Esegui la migrazione dagli Endpoint** — consulta [Migrazione dagli Endpoint](../pro__migrating_from_endpoints) per sapere cosa preserva la migrazione e come si comporta successivamente la vecchia API Endpoint. +- **Flussi di lavoro quotidiani con gli URL** — consulta [Utilizzo degli URL](../pro__working_with_urls). +- **SBOM e dipendenze** — consulta [Utilizzo delle SBOM](../pro__working_with_sboms). diff --git a/docs/content/asset_modelling/locations/PRO__locations_overview.pt-br.md b/docs/content/asset_modelling/locations/PRO__locations_overview.pt-br.md new file mode 100644 index 0000000000..d04db72c3d --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__locations_overview.pt-br.md @@ -0,0 +1,80 @@ +--- +title: Visão Geral das Locations +description: O que são as Locations e por que elas substituem os Endpoints +audience: pro +weight: 1 +--- + +**Locations** são uma nova ferramenta de modelagem de ativos no DefectDojo Pro. Elas substituem o modelo legado de **Endpoints** e absorvem os dados anteriores de **Components** (biblioteca), dando ao DefectDojo uma forma única e polimórfica de descrever *onde* um Achado vive — seja isso uma URL, uma dependência de software de um **SBOM**, ou, no futuro, um **ID de recurso em nuvem**, uma **imagem de contêiner** ou um **repositório de código**. + +As Locations precisam estar habilitadas na sua instância antes que você possa usá-las. Você mesmo pode ativar as Locations na [página de Feature Flags](/admin/feature_flags/pro__feature_flags/) — não é necessário abrir uma solicitação de Suporte. Observe que as Locations não podem ser desativadas novamente depois de habilitadas. + +## Por que Substituir os Endpoints? + +O modelo original de Endpoints foi construído em torno de URLs e endereços IP — ele carregava campos de aplicação web como `protocol`, `host`, `port`, `path`, e uma tabela de status fixa que estava fortemente acoplada aos Achados. Três problemas surgiram a partir disso: + +1. **Fidelidade limitada.** Os Endpoints não conseguiam descrever de forma clara ativos que não fossem URLs, como bibliotecas de terceiros, imagens de contêiner ou recursos em nuvem, mesmo com os scanners produzindo cada vez mais achados sobre essas coisas. +2. **Teto de desempenho.** As linhas de Endpoint_Status por Achado e o schema com formato de URL não escalavam bem em grandes volumes de clientes. +3. **Components eram cidadãos de segunda classe.** As bibliotecas de software existiam apenas como campos desnormalizados em um Achado, de modo que uma biblioteca não podia existir independentemente de uma vulnerabilidade — o que tornava impossível uma verdadeira gestão de SBOM. + +As Locations resolvem os três problemas ao introduzir um **objeto `Location` base** com um payload tipado, além de **subtipos** dedicados para cada formato de ativo: + +- **URL Locations** — equivalente funcional aos antigos Endpoints, com os mesmos campos de protocol/host/port/path/query/fragment. +- **Dependency Locations** — bibliotecas de software identificadas por [Package URL (pURL)](https://github.com/package-url/purl-spec), usadas para modelar o conteúdo de SBOMs. +- **[Source Code Locations](/asset_modelling/locations/pro__source_code_locations/)** — onde um achado de análise estática vive no código-fonte, identificado por caminho de arquivo e número de linha. Gerenciado pelo scan, e a base para [rastrear achados à medida que seu código se move](/triage_findings/finding_deduplication/pro__location_drift_matching/). + +Entre os futuros tipos de Location em consideração estão IDs de recursos de provedores de nuvem (AWS ARN, Azure Resource ID, GCP Full Resource Name) e imagens de contêiner (registry/repository:tag e impressões digitais SHA256). + +## Conceitos-Chave + +### Locations e Subtipos + +Uma **Location** é o pai compartilhado. Ela carrega: + +- Um `Location Type` (por exemplo, `"url"`, `"dependency"`) +- Uma string canônica `Location Value` usada para exibição, busca e deduplicação +- `Tags` e tags herdadas do Ativo pai +- Metadados (pares personalizados de chave/valor) + +Um **subtipo** (URL ou Dependency) contém os campos estruturados específicos daquele tipo de location. URLs e Dependencies sempre existem junto a um objeto Location pai; o `Location Value` do subtipo é gerado a partir de seus campos estruturados. + +### References + +As Locations não são anexadas diretamente a Produtos ou Achados. Em vez disso, dois objetos **Reference** as conectam: + +- **Asset References** — relações que a Location tem com Ativos (por exemplo, `libFoo` é *de propriedade de* (owned by) o Ativo 6, *usada por* (used by) o Ativo 9). Cada referência carrega um status (`Active` ou `Mitigated`) e um **relacionamento** opcional ("Used By" ou "Owned By"). +- **Finding References** — relações que a Location tem com Achados. Cada referência carrega um status mais detalhado (`Active`, `Mitigated`, `False Positive`, `Risk Accepted`, `Out of Scope`), além do auditor e do horário da auditoria. + +Essa separação é o que permite que uma biblioteca exista em um Produto *sem* precisar de um Achado — uma capacidade que faltava no antigo modelo de Components. + +### Associação Automática no Momento da Importação + +Quando um parser produz um Achado que referencia uma URL ou biblioteca, o importador: + +1. Procura uma Location existente que corresponda à URL ou ao pURL; se nenhuma existir, cria uma. +2. Cria uma Finding Reference vinculando o Achado à Location com status `Active`. +3. Cria (ou reutiliza) uma Asset Reference para que a Location também exista no Ativo pai. + +Os parsers existentes foram atualizados para emitir dados de Location quando a feature flag está ativada, e para retornar ao modelo legado de Endpoint quando ela está desativada. Nenhuma reconfiguração é necessária quando as Locations estão habilitadas — a próxima importação será automaticamente roteada pelo pipeline de Locations. + +## O que Está no MVP + +| Capability | Status | +| --- | --- | +| Foundational `Location`, `URL`, `Dependency` models | Shipped | +| REST API for Locations and References | Shipped (read-only `Location`, full CRUD on References) | +| Endpoint API read-compatibility shim | Shipped | +| Endpoint → URL one-way migration command | Shipped | +| Parser updates (URLs and dependencies) | Shipped for the major parsers | +| SBOM upload (CycloneDX, SPDX v2/v3) | Shipped via `/api/v2/sbom-import/` | +| Pro UI for Locations, URLs, Dependencies | Shipped | +| pURL search/filter | Shipped | +| License tracking on dependencies | Partial (`license_expression` field) | +| SWID Tag SBOM format | Not in MVP | + +## Para Onde Ir a Seguir + +- **Habilite o recurso** — entre em contato com [support@defectdojo.com](mailto:support@defectdojo.com) para ativar as Locations na sua instância. +- **Migre a partir dos Endpoints** — veja [Migrando dos Endpoints](../pro__migrating_from_endpoints) para saber o que a migração preserva e como a API legada de Endpoint se comporta depois. +- **Fluxos de trabalho do dia a dia com URLs** — veja [Trabalhando com URLs](../pro__working_with_urls). +- **SBOMs e dependências** — veja [Trabalhando com SBOMs](../pro__working_with_sboms). diff --git a/docs/content/asset_modelling/locations/PRO__locations_overview.zh-hans.md b/docs/content/asset_modelling/locations/PRO__locations_overview.zh-hans.md new file mode 100644 index 0000000000..c66b045f04 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__locations_overview.zh-hans.md @@ -0,0 +1,80 @@ +--- +title: 位置概览 +description: 位置是什么,以及它们为何取代端点 +audience: pro +weight: 1 +--- + +**位置(Locations)** 是 DefectDojo Pro 中一项全新的资产建模工具。它们取代了旧有的 **端点(Endpoints)** 模型,并吸收了此前的 **组件(Components)**(库)数据,使 DefectDojo 拥有了一种统一的多态方式来描述发现项 *位于何处* ——无论是一个 URL、来自 **SBOM** 的软件依赖项,还是未来可能支持的 **云资源 ID**、**容器镜像** 或 **代码仓库**。 + +在使用位置功能之前,必须先在您的实例上启用它。您可以自行通过[功能开关页面](/admin/feature_flags/pro__feature_flags/)启用位置功能——无需提交支持请求。请注意,位置功能一旦启用,便无法再关闭。 + +## 为什么要取代端点? + +最初的端点模型是围绕 URL 和 IP 地址构建的——它包含 `protocol`、`host`、`port`、`path` 等 Web 应用字段,以及一个与发现项紧密耦合的固定状态表。由此产生了三个问题: + +1. **保真度有限。** 端点无法清晰地描述非 URL 类资产,例如第三方库、容器镜像或云资源,即便扫描器越来越多地针对这些内容生成发现项。 +2. **性能上限。** 每个发现项对应的 Endpoint_Status 行,以及 URL 形态的模式设计,在大型客户体量下的扩展性不佳。 +3. **组件处于次等地位。** 软件库仅作为发现项上的非规范化字段存在,因此一个库无法独立于漏洞而存在——这使得真正的 SBOM 管理无法实现。 + +位置功能通过引入一个带有类型化载荷的 **基础 `Location` 对象**,以及针对每种资产形态的专用 **子类型**,解决了这三个问题: + +- **URL 位置** — 在功能上等同于旧有的端点,拥有相同的 protocol/host/port/path/query/fragment 字段。 +- **依赖项位置** — 由 [Package URL(pURL)](https://github.com/package-url/purl-spec) 标识的软件库,用于建模 SBOM 内容。 +- **[源代码位置](/asset_modelling/locations/pro__source_code_locations/)** — 静态分析发现项在源代码中的所在位置,通过文件路径和行号标识。由扫描管理,并作为[随代码变动跟踪发现项](/triage_findings/finding_deduplication/pro__location_drift_matching/)的基础。 + +正在考虑中的未来位置类型包括云提供商资源 ID(AWS ARN、Azure 资源 ID、GCP 完整资源名称)和容器镜像(registry/repository:tag 及 SHA256 指纹)。 + +## 关键概念 + +### 位置与子类型 + +**位置(Location)** 是共享的父对象,它包含: + +- 一个 `Location Type`(例如 `"url"`、`"dependency"`) +- 一个用于显示、搜索和去重的规范化 `Location Value` 字符串 +- `Tags`,以及从父资产继承的标签 +- 元数据(自定义键/值对) + +**子类型**(URL 或依赖项)保存该类位置特有的结构化字段。URL 和依赖项始终与一个父位置对象共存;子类型的 `Location Value` 是根据其结构化字段生成的。 + +### 引用 + +位置不会直接关联到产品或发现项,而是通过两种 **引用(Reference)** 对象进行关联: + +- **资产引用(Asset References)** — 位置与资产之间的关系(例如,`libFoo` *归属于(owned by)* 资产 6,*被使用于(used by)* 资产 9)。每个引用都带有一个状态(`Active` 或 `Mitigated`),以及一个可选的 **关系(relationship)**(“Used By” 或 “Owned By”)。 +- **发现项引用(Finding References)** — 位置与发现项之间的关系。每个引用都带有更丰富的状态(`Active`、`Mitigated`、`False Positive`、`Risk Accepted`、`Out of Scope`),以及审核人和审核时间。 + +正是这种分离,使得一个库可以存在于某个产品上而 *无需* 依赖发现项——这是旧有组件模型所缺失的能力。 + +### 导入时的自动关联 + +当解析器生成一个引用了 URL 或库的发现项时,导入程序会: + +1. 查找与该 URL 或 pURL 匹配的现有位置;如果不存在,则创建一个新位置。 +2. 创建一个发现项引用,将该发现项与位置以 `Active` 状态关联。 +3. 创建(或复用)一个资产引用,使该位置也存在于父资产上。 + +现有的解析器已经过更新,在功能开关开启时会生成位置数据,在功能开关关闭时则会回退到旧有的端点模型。启用位置功能后无需进行任何重新配置——下一次导入将自动经由位置处理流程进行路由。 + +## MVP 中包含的内容 + +| Capability | Status | +| --- | --- | +| 基础 `Location`、`URL`、`Dependency` 模型 | 已发布 | +| 面向位置和引用的 REST API | 已发布(`Location` 只读,引用支持完整 CRUD) | +| 端点 API 只读兼容层 | 已发布 | +| 端点 → URL 单向迁移命令 | 已发布 | +| 解析器更新(URL 和依赖项) | 已针对主要解析器发布 | +| SBOM 上传(CycloneDX、SPDX v2/v3) | 已通过 `/api/v2/sbom-import/` 发布 | +| 面向位置、URL、依赖项的 Pro 界面 | 已发布 | +| pURL 搜索/筛选 | 已发布 | +| 依赖项许可证跟踪 | 部分支持(`license_expression` 字段) | +| SWID Tag SBOM 格式 | 未纳入 MVP | + +## 后续步骤 + +- **启用该功能** — 联系 [support@defectdojo.com](mailto:support@defectdojo.com) 为您的实例开启位置功能。 +- **从端点迁移** — 请参阅[从端点迁移](../pro__migrating_from_endpoints),了解迁移会保留哪些内容,以及迁移后旧有端点 API 的行为方式。 +- **日常 URL 工作流程** — 请参阅[使用 URL](../pro__working_with_urls)。 +- **SBOM 与依赖项** — 请参阅[使用 SBOM](../pro__working_with_sboms)。 diff --git a/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.it.md b/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.it.md new file mode 100644 index 0000000000..2bf57b2736 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.it.md @@ -0,0 +1,70 @@ +--- +title: Migrazione dagli Endpoint +description: Cosa succede quando si migrano i dati Endpoint esistenti verso Location +audience: pro +weight: 3 +--- + +Quando si abilita Location su un'istanza DefectDojo Pro esistente, i dati già memorizzati come Endpoint devono essere riportati nel nuovo modello Location. Questa pagina descrive la migrazione, cosa viene preservato e come si comporta l'API Endpoint legacy una volta eseguita la migrazione. + +Nota che la migrazione è **a senso unico**. Non esiste un percorso di rollback automatizzato che ricrei gli Endpoint a partire dalle Location. + +## Cosa fa la migrazione + +Per ogni Endpoint esistente, la migrazione: + +1. **Crea una URL Location** (o ne riutilizza una esistente) usando i campi `protocol`, `userinfo`, `host`, `port`, `path`, `query` e `fragment` dell'Endpoint. Il nuovo URL viene collegato automaticamente a un oggetto `Location` padre. +2. **Riporta i tag.** Ogni tag presente sull'Endpoint viene aggiunto all'insieme di tag della Location. +3. **Riporta i metadati.** Ogni riga `DojoMeta` collegata all'Endpoint viene ricollegata alla nuova Location. +4. **Crea una `LocationProductReference`** in modo che l'URL compaia sotto l'Asset (Product) corretto. +5. **Crea una `LocationFindingReference` per ogni `Endpoint_Status`**: + + | Flag Endpoint_Status | Stato Location risultante | + | --- | --- | + | `risk_accepted=True` | **Rischio accettato** | + | `false_positive=True` | **Falso positivo** | + | `out_of_scope=True` | **Fuori ambito** | + | `mitigated=True` | **Mitigato** | + | (nessuno dei precedenti) | **Attivo** | + + La mappatura dipende dall'ordine: vince il *primo* flag corrispondente. Questo comprime intenzionalmente le vecchie combinazioni multi-flag in un unico stato canonico usato dalle Location. + + +## Cosa non fa la migrazione + +- **Non** crea Dependency Location. I dati SBOM e delle librerie non sono mai esistiti come Endpoint, quindi non c'è nulla da convertire per la migrazione. Per popolare le Dependency, caricare gli SBOM (vedi [Utilizzo degli SBOM](../pro__working_with_sboms)) oppure rieseguire le scansioni con parser che generano dati sulle dipendenze. +- **Non** elimina le righe originali di Endpoint o Endpoint_Status. Rimangono nel database a supporto dell'API legacy in sola lettura. Non vengono utilizzate dalla nuova interfaccia né dagli import dopo l'abilitazione della funzionalità. + +## API Endpoint dopo la migrazione + +Una volta abilitata Location, l'API Endpoint legacy entra in una modalità di **compatibilità in lettura** pensata per mantenere funzionanti le automazioni esistenti senza modifiche al codice, ma solo per il traffico in lettura. + +### Cosa continua a funzionare + +- `GET /api/v2/endpoints/` — Restituisce righe che *sembrano* Endpoint ma sono in realtà proiettate dalle righe Location Product Reference unite alle URL Location. I campi consueti (`protocol`, `host`, `port`, `path`, `query`, `fragment`, `tags`, `product`, `active_finding_count`) sono tutti presenti. +- `GET /api/v2/endpoints/{id}/` — Il recupero di un singolo Endpoint funziona allo stesso modo. L'`id` è l'ID Endpoint originale e viene preservato durante la migrazione tramite la mappatura Asset Reference. +- `GET /api/v2/endpoint_status/` e `GET /api/v2/endpoint_status/{id}/` — Restituiscono righe proiettate da `LocationFindingReference`. I campi booleani legacy `mitigated`, `false_positive`, `out_of_scope` e `risk_accepted` vengono ricostruiti. +- Il filtraggio per `protocol`, `host`, `port`, `path`, `query`, `fragment`, `product` e `tag(s)` continua a funzionare. +- L'azione `generate_report` sui singoli Endpoint continua a funzionare. + +### Cosa restituisce 403 + +- `POST`, `PUT`, `PATCH` e `DELETE` su `/api/v2/endpoints/` e `/api/v2/endpoint_status/` restituiscono tutti `HTTP 403` con il seguente corpo: + + > Writes to this endpoint are deprecated when V3_FEATURE_LOCATIONS is enabled + + I client che scrivono dati Endpoint devono passare ai nuovi endpoint Reference (`POST /api/v2/location_findings/`, `POST /api/v2/location_products/`) e all'endpoint URL (`POST /api/v2/urls/`). + +### Differenze di comportamento da tenere presenti + +Alcuni aspetti si comportano diversamente rispetto all'API Endpoint originale: + +- **Stato singolo invece di flag.** Le Location hanno un solo stato alla volta. Se il codice si basava su un Finding con *sia* `mitigated=True` *sia* `false_positive=True` contemporaneamente su un Endpoint_Status, questo non è più rappresentabile — la migrazione sceglie il flag con priorità più alta (l'ordine mostrato nella tabella sopra). +- **Campo `endpoint` su Endpoint_Status.** Il campo legacy `endpoint` viene ricostruito cercando l'Asset Reference corrispondente. Nei rari casi in cui l'Asset di un Finding non corrisponde più agli Asset Reference della sua Location, questo campo può essere nullo. +- **Paginazione e ordinamento.** I campi di ordinamento disponibili sullo shim di compatibilità in lettura sono `host`, `product`, `id` e `active_finding_count`. Se il client ordina per un altro campo, passare a uno di questi o migrare ai nuovi endpoint Location. + +## Tag e metadati + +I tag applicati agli Endpoint diventano tag sull'oggetto Location (non sul sottotipo URL). I filtri basati su tag nell'API legacy continuano a funzionare correttamente. + +I metadati Endpoint vengono ricollegati alla Location durante la migrazione. Le automazioni esistenti che leggono i metadati tramite `/api/v2/endpoint_meta/` dovrebbero continuare a funzionare; i nuovi metadati vanno scritti attraverso gli endpoint Location. diff --git a/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.pt-br.md b/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.pt-br.md new file mode 100644 index 0000000000..c9861dcf52 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.pt-br.md @@ -0,0 +1,70 @@ +--- +title: Migração a partir de Endpoints +description: O que acontece quando você migra dados existentes de Endpoint para Localizações +audience: pro +weight: 3 +--- + +Quando você habilita as Localizações em uma instância existente do DefectDojo Pro, os dados já armazenados como Endpoints precisam ser transportados para o novo modelo de Localizações. Esta página descreve a migração, o que ela preserva e como a API legada de Endpoint se comporta depois que a migração é executada. + +Observe que a migração é **de mão única**. Não existe um caminho de rollback automatizado que recrie Endpoints a partir de Localizações. + +## O Que a Migração Faz + +Para cada Endpoint existente, a migração vai: + +1. **Criar uma Localização de URL** (ou reutilizar uma existente) usando os campos `protocol`, `userinfo`, `host`, `port`, `path`, `query` e `fragment` do Endpoint. A nova URL é automaticamente anexada a um objeto `Location` pai. +2. **Transferir as tags.** Cada tag do Endpoint é adicionada ao conjunto de tags da Localização. +3. **Transferir os metadados.** Cada linha `DojoMeta` anexada ao Endpoint é redirecionada para a nova Localização. +4. **Criar uma `LocationProductReference`** para que a URL apareça sob o Ativo (Produto) correto. +5. **Criar uma `LocationFindingReference` para cada `Endpoint_Status`**: + + | Flag do Endpoint_Status | Status resultante da Localização | + | --- | --- | + | `risk_accepted=True` | **Risco aceito** | + | `false_positive=True` | **Falso positivo** | + | `out_of_scope=True` | **Fora do escopo** | + | `mitigated=True` | **Mitigado** | + | (nenhum dos anteriores) | **Ativo** | + + O mapeamento é sensível à ordem: a *primeira* flag correspondente prevalece. Isso reduz intencionalmente as antigas combinações de múltiplas flags a um único status canônico usado pelas Localizações. + + +## O Que a Migração Não Faz + +- Ela **não** cria Localizações de Dependência. Dados de SBOM e de bibliotecas nunca existiram como Endpoints, então não há nada para a migração converter. Para popular Dependências, faça upload de SBOMs (veja [Trabalhando com SBOMs](../pro__working_with_sboms)) ou execute novamente as varreduras com parsers que emitam dados de dependência. +- Ela **não** exclui as linhas originais de Endpoint ou Endpoint_Status. Elas permanecem no banco de dados para sustentar a API legada somente leitura. Não são usadas pela nova interface nem pelas importações após o recurso ser habilitado. + +## API de Endpoint Após a Migração + +Depois que as Localizações são habilitadas, a API legada de Endpoint entra em um modo de **compatibilidade de leitura**, projetado para manter as automações existentes funcionando sem alterações de código — mas apenas para tráfego de leitura. + +### O Que Ainda Funciona + +- `GET /api/v2/endpoints/` — Retorna linhas que *parecem* Endpoints, mas na verdade são projetadas a partir de linhas de Location Product Reference unidas a Localizações de URL. Os campos conhecidos (`protocol`, `host`, `port`, `path`, `query`, `fragment`, `tags`, `product`, `active_finding_count`) estão todos presentes. +- `GET /api/v2/endpoints/{id}/` — A busca de um único Endpoint funciona da mesma forma. O `id` é o ID original do Endpoint e é preservado ao longo da migração por meio do mapeamento de Asset Reference. +- `GET /api/v2/endpoint_status/` e `GET /api/v2/endpoint_status/{id}/` — Retornam linhas projetadas a partir de `LocationFindingReference`. Os campos booleanos legados `mitigated`, `false_positive`, `out_of_scope` e `risk_accepted` são reconstruídos. +- A filtragem por `protocol`, `host`, `port`, `path`, `query`, `fragment`, `product` e `tag(s)` continua funcionando. +- A ação `generate_report` em Endpoints individuais continua funcionando. + +### O Que Retorna 403 + +- `POST`, `PUT`, `PATCH` e `DELETE` em `/api/v2/endpoints/` e `/api/v2/endpoint_status/` retornam todos `HTTP 403` com o corpo: + + > Writes to this endpoint are deprecated when V3_FEATURE_LOCATIONS is enabled + + Os clientes que gravam dados de Endpoint devem migrar para os novos endpoints de referência (`POST /api/v2/location_findings/`, `POST /api/v2/location_products/`) e para o endpoint de URL (`POST /api/v2/urls/`). + +### Diferenças de Comportamento a Observar + +Algumas coisas se comportam de maneira diferente em relação à API original de Endpoint: + +- **Status único em vez de flags.** As Localizações têm apenas um status por vez. Se o seu código dependia de um Achado ser *ao mesmo tempo* `mitigated=True` *e* `false_positive=True` em um Endpoint_Status, isso deixa de ser representável — a migração escolhe a flag de maior prioridade (a ordem mostrada na tabela acima). +- **Campo `endpoint` no Endpoint_Status.** O campo legado `endpoint` é reconstruído buscando a Asset Reference correspondente. Em casos raros, quando o Ativo de um Achado não corresponde mais às referências de Ativo de sua Localização, esse campo pode ser nulo. +- **Paginação e ordenação.** Os campos de ordenação disponíveis na camada de compatibilidade de leitura são `host`, `product`, `id` e `active_finding_count`. Se o seu cliente ordena por outro campo, mude para um destes ou migre para os novos endpoints de Localizações. + +## Tags e Metadados + +As tags aplicadas a Endpoints se tornam tags no objeto Localização (não no subtipo URL). Os filtros baseados em tags na API legada continuam funcionando. + +Os metadados de Endpoint são redirecionados para a Localização durante a migração. As automações existentes que leem metadados por meio de `/api/v2/endpoint_meta/` devem continuar funcionando; novos metadados devem ser gravados por meio dos endpoints de Localização. diff --git a/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.zh-hans.md b/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.zh-hans.md new file mode 100644 index 0000000000..533285a77e --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.zh-hans.md @@ -0,0 +1,70 @@ +--- +title: 从端点迁移 +description: 将现有端点数据迁移到位置时会发生什么 +audience: pro +weight: 3 +--- + +当您在现有的 DefectDojo Pro 实例上启用位置功能后，已存储为端点的数据需要迁移到新的位置模型中。本页介绍迁移过程、迁移会保留哪些内容，以及迁移完成后旧版端点 API 的行为方式。 + +请注意，迁移是**单向的**。目前没有自动化的回滚路径可以从位置反向重新创建端点。 + +## 迁移会执行哪些操作 + +对于每个现有端点，迁移会： + +1. **创建一个 URL 位置**（或复用已有的），使用该端点的 `protocol`、`userinfo`、`host`、`port`、`path`、`query` 和 `fragment` 字段。新的 URL 会自动关联到一个父级 `Location` 对象。 +2. **保留标签。** 端点上的每个标签都会添加到该位置的标签集合中。 +3. **保留元数据。** 附加在端点上的每条 `DojoMeta` 记录都会重新指向新的位置。 +4. **创建一个 `LocationProductReference`**，使该 URL 出现在正确的资产（产品）下。 +5. **为每个 `Endpoint_Status` 创建一个 `LocationFindingReference`**： + + | Endpoint_Status 标志 | 生成的位置状态 | + | --- | --- | + | `risk_accepted=True` | **风险已接受** | + | `false_positive=True` | **误报** | + | `out_of_scope=True` | **超出范围** | + | `mitigated=True` | **已缓解** | + | （以上均不满足） | **活动** | + + 该映射关系与顺序相关：*首个*匹配的标志将生效。这是有意为之的设计，用于将旧版的多标志组合归并为位置所使用的单一规范状态。 + + +## 迁移不会执行哪些操作 + +- 迁移**不会**创建依赖位置。SBOM 和库数据从未以端点的形式存在过，因此迁移没有可转换的内容。要填充依赖项，请上传 SBOM（参见[使用 SBOM](../pro__working_with_sboms)），或使用能够输出依赖数据的解析器重新运行扫描。 +- 迁移**不会**删除原始的端点或 Endpoint_Status 记录。这些记录会保留在数据库中，用于支撑只读的旧版 API。启用该功能后，新版界面和导入流程不会再使用这些记录。 + +## 迁移后的端点 API + +启用位置功能后，旧版端点 API 会进入**只读兼容**模式，旨在让现有的自动化流程无需修改代码即可继续运行——但仅限于读取流量。 + +### 仍然可用的功能 + +- `GET /api/v2/endpoints/` — 返回的记录*看起来像*端点，但实际上是由 Location Product Reference 记录与 URL 位置连接映射而成的。熟悉的字段（`protocol`、`host`、`port`、`path`、`query`、`fragment`、`tags`、`product`、`active_finding_count`）都会保留。 +- `GET /api/v2/endpoints/{id}/` — 单个端点的获取方式相同。`id` 为原始端点 ID，会通过资产引用映射在迁移过程中得以保留。 +- `GET /api/v2/endpoint_status/` 和 `GET /api/v2/endpoint_status/{id}/` — 返回由 `LocationFindingReference` 映射而成的记录。旧版的 `mitigated`、`false_positive`、`out_of_scope` 和 `risk_accepted` 布尔字段会被重新构建。 +- 按 `protocol`、`host`、`port`、`path`、`query`、`fragment`、`product` 和 `tag(s)` 进行筛选的功能仍可正常使用。 +- 单个端点上的 `generate_report` 操作仍可正常使用。 + +### 会返回 403 的操作 + +- 对 `/api/v2/endpoints/` 和 `/api/v2/endpoint_status/` 执行 `POST`、`PUT`、`PATCH` 和 `DELETE` 操作，都会返回 `HTTP 403`，响应内容为： + + > Writes to this endpoint are deprecated when V3_FEATURE_LOCATIONS is enabled + + 需要写入端点数据的客户端必须迁移到新的引用端点（`POST /api/v2/location_findings/`、`POST /api/v2/location_products/`）以及 URL 端点（`POST /api/v2/urls/`）。 + +### 需要注意的行为差异 + +以下几点与原始端点 API 的行为有所不同： + +- **单一状态取代多个标志。** 位置在同一时刻只有一个状态。如果您的代码依赖于某个发现项在 Endpoint_Status 上*同时*为 `mitigated=True` *和* `false_positive=True`，这种情况将无法再表示——迁移会选取优先级最高的标志（顺序如上表所示）。 +- **Endpoint_Status 上的 `endpoint` 字段。** 旧版的 `endpoint` 字段是通过查找匹配的资产引用重新构建的。在极少数情况下，如果发现项的资产与其位置的资产引用不再匹配，该字段可能为空。 +- **分页与排序。** 只读兼容层上可用的排序字段为 `host`、`product`、`id` 和 `active_finding_count`。如果您的客户端按其他字段排序，请改用上述字段之一，或迁移到新的位置端点。 + +## 标签与元数据 + +应用于端点的标签会成为位置对象上的标签（而非 URL 子类型上的标签）。旧版 API 中基于标签的筛选功能仍可正常匹配。 + +迁移过程中，端点元数据会重新指向对应的位置。通过 `/api/v2/endpoint_meta/` 读取元数据的现有自动化流程应能继续正常工作；新的元数据应通过位置端点写入。 diff --git a/docs/content/asset_modelling/locations/PRO__source_code_locations.it.md b/docs/content/asset_modelling/locations/PRO__source_code_locations.it.md new file mode 100644 index 0000000000..613f05f166 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__source_code_locations.it.md @@ -0,0 +1,46 @@ +--- +title: Location del codice sorgente +description: Le Code location rappresentano dove risiede nel codice sorgente un riscontro + di analisi statica e ne registrano la cronologia degli spostamenti man mano che + il codice evolve +weight: 6 +audience: pro +--- + +**Le Location del codice sorgente** estendono il modello Location all'analisi statica: accanto a URL (DAST) e Dependency (SCA), una location di tipo **Code** descrive dove risiede nel sorgente un riscontro SAST, identificato dal suo **percorso file e numero di riga**. + +> Le Location del codice sorgente richiedono la funzionalità Location (Beta). Per abilitare Location sulla propria istanza, contattare [support@defectdojo.com](mailto:support@defectdojo.com). + +## Cosa rappresentano + +Ogni riscontro statico che segnala un percorso file ottiene una Code location. Il valore canonico della location è `path/to/file.py:42` (o solo il percorso file quando lo strumento non riporta la riga). Come tutte le Location, le code location sono oggetti condivisi: due riscontri sullo stesso file e riga fanno riferimento alla stessa location, e la location porta con sé stati di riferimento per riscontro e per asset. + +Le code location sono **gestite dalle scansioni**: vengono create e aggiornate dagli import e dai reimport, non manualmente. Non esiste un'azione "Nuova Location del codice sorgente": lo scanner è la fonte di verità su dove risiedono i riscontri nel codice. + +## Dove trovarle + +- **All Source Code** nella barra laterale elenca tutte le code location dell'istanza, con lo stesso filtraggio e tagging di URL e Dependency. +- **View Source Code** nel menu Location di un Asset limita l'elenco a un singolo asset. +- La pagina di un riscontro mostra la sua code location attuale e, quando il riscontro si è spostato, la sua **cronologia delle location**. + +## Cronologia degli spostamenti + +Il codice sorgente si sposta continuamente: i commit spostano i numeri di riga, i refactoring rinominano i file. Quando [Location Drift Matching](/triage_findings/finding_deduplication/pro__location_drift_matching/) è abilitato per uno strumento, un riscontro che si sposta mantiene la propria identità, e i suoi riferimenti alla code location ne registrano il percorso: + +- Il riferimento del riscontro alla location **precedente** viene mitigato e contrassegnato con *dove si è spostato il riscontro* e *perché è stata effettuata la corrispondenza* (riga più vicina, dataflow, rinomina del file ...). +- Viene creato un riferimento alla **nuova** location, che rimane attivo. + +Il risultato è una catena di sostituzioni consultabile — "questo riscontro si trovava in `auth.py:42`, poi in `auth.py:57`, poi in `session.py:31`" — visualizzata come una timeline nella pagina del riscontro. Lo stesso meccanismo di cronologia copre gli spostamenti di URL e gli aggiornamenti di versione delle dipendenze, quindi tutti e tre i tipi di location condividono un'unica interfaccia a timeline. + +La cronologia viene registrata a partire dal momento in cui Location viene abilitata sull'istanza. I riscontri spostatisi prima di allora mantengono la loro location attuale; gli spostamenti passati sono stati applicati ma non registrati. Per le istanze con anni di cronologia precedenti alla funzionalità, il [comando di consolidamento del churn](/triage_findings/finding_deduplication/pro__location_drift_matching/#consolidating-historical-churn) può ricostruire i percorsi unendo le catene storiche di chiusura-e-ricreazione. + +## Correttezza dello stato + +Gli stati dei riferimenti alle code location vengono mantenuti veritieri dal reimport su **ogni** algoritmo di corrispondenza, indipendentemente dal fatto che il drift matching sia abilitato o meno: + +- Il riferimento di codice attuale di un riscontro corrispondente viene sincronizzato a ogni reimport, così un riscontro spostato non lascia il proprio vecchio riferimento attivo per sempre. +- La stessa sincronizzazione indipendente dall'impostazione si applica ai riferimenti di dependency: quando la versione del pacchetto di un riscontro SCA viene aggiornata, il riferimento alla vecchia versione viene mitigato invece di rimanere attivo insieme al nuovo. + +## Relazione con i campi del riscontro + +I campi propri del riscontro `file_path` / `line` rimangono gli scalari autorevoli (sono ciò che filtri, hash e API espongono); la Code location è la vista condivisa e con conteggio dei riferimenti di quella stessa coordinata. Il reimport aggiorna gli scalari in base all'ultima scansione e il meccanismo delle location ne deriva le location: i due non possono disallinearsi. diff --git a/docs/content/asset_modelling/locations/PRO__source_code_locations.pt-br.md b/docs/content/asset_modelling/locations/PRO__source_code_locations.pt-br.md new file mode 100644 index 0000000000..63bd06bb99 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__source_code_locations.pt-br.md @@ -0,0 +1,46 @@ +--- +title: Localizações de Código-Fonte +description: Localizações de código modelam onde um achado de análise estática vive + no código-fonte e registram seu histórico de movimentação à medida que o código + evolui +weight: 6 +audience: pro +--- + +As **Localizações de Código-Fonte** estendem o modelo de Localizações à análise estática: além de URLs (DAST) e Dependências (SCA), uma localização do tipo **Código** descreve onde um achado de SAST vive no código-fonte — identificado pelo **caminho do arquivo e número da linha**. + +> As Localizações de Código-Fonte exigem o recurso de Localizações (Beta). Para habilitar as Localizações na sua instância, entre em contato com [support@defectdojo.com](mailto:support@defectdojo.com). + +## O Que Elas Modelam + +Todo achado estático que reporta um caminho de arquivo recebe uma localização de Código. O valor canônico da localização é `path/to/file.py:42` (ou apenas o caminho do arquivo quando a ferramenta não reporta uma linha). Como todas as Localizações, as localizações de código são objetos compartilhados: dois achados no mesmo arquivo e linha referenciam a mesma localização, e a localização carrega status de referência por achado e por ativo. + +As localizações de código são **gerenciadas por varredura**: são criadas e atualizadas por importações e reimportações, não manualmente. Não existe uma ação "Nova Localização de Código-Fonte" — o scanner é a fonte da verdade sobre onde os achados de código vivem. + +## Onde Encontrá-las + +- **All Source Code** na barra lateral lista todas as localizações de código da instância, com a mesma filtragem e marcação por tags que URLs e Dependências. +- **View Source Code** no menu de Localizações de um Ativo restringe a lista a um único ativo. +- A página de um achado mostra sua localização de código atual e, quando o achado se moveu, seu **histórico de localização**. + +## Histórico de Movimentação + +O código-fonte se move constantemente: commits deslocam números de linha, refatorações renomeiam arquivos. Quando o [Location Drift Matching](/triage_findings/finding_deduplication/pro__location_drift_matching/) está habilitado para uma ferramenta, um achado que se move mantém sua identidade, e suas referências de localização de código registram o rastro: + +- A referência do achado à localização **antiga** é mitigada e marcada com *para onde o achado se moveu* e *por que a correspondência foi feita* (linha mais próxima, fluxo de dados, renomeação de arquivo...). +- Uma referência à localização **nova** é criada e permanece ativa. + +O resultado é uma cadeia de substituição navegável — "este achado viveu em `auth.py:42`, depois em `auth.py:57`, depois em `session.py:31`" — renderizada como uma linha do tempo na página do achado. O mesmo mecanismo de histórico cobre movimentações de URL e atualizações de versão de dependência, então os três tipos de localização compartilham uma única interface de linha do tempo. + +O histórico é registrado a partir do momento em que as Localizações são habilitadas na instância. Achados que se moveram antes disso mantêm sua localização atual; os saltos anteriores foram aplicados, mas não registrados. Para instâncias com anos de histórico anterior ao recurso, o [comando de consolidação de churn](/triage_findings/finding_deduplication/pro__location_drift_matching/#consolidating-historical-churn) pode reconstruir os rastros ao mesclar cadeias históricas de fechar-e-recriar. + +## Correção de Status + +Os status de referência de localização de código são mantidos fiéis por meio da reimportação em **todos** os algoritmos de correspondência, independentemente de a correspondência por deriva (drift matching) estar habilitada: + +- A referência de código atual de um achado correspondido é sincronizada a cada reimportação, de modo que um achado que se moveu não deixe sua referência antiga ativa para sempre. +- A mesma sincronização independente de configuração se aplica às referências de dependência: quando a versão do pacote de um achado de SCA é atualizada, a referência da versão antiga é mitigada em vez de permanecer ativa junto com a nova. + +## Relação com os Campos do Achado + +Os próprios campos `file_path` / `line` do achado continuam sendo os valores escalares autoritativos (são eles que os filtros, os hashes e a API expõem); a localização de Código é a visão compartilhada e com contagem de referências dessa mesma coordenada. A reimportação atualiza os escalares a partir da varredura mais recente, e o mecanismo de localizações deriva as localizações a partir deles — os dois não podem divergir. diff --git a/docs/content/asset_modelling/locations/PRO__source_code_locations.zh-hans.md b/docs/content/asset_modelling/locations/PRO__source_code_locations.zh-hans.md new file mode 100644 index 0000000000..f426913511 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__source_code_locations.zh-hans.md @@ -0,0 +1,44 @@ +--- +title: 源代码位置 +description: 代码位置用于建模静态分析发现项在源代码中的位置，并随着代码演进记录其变动历史 +weight: 6 +audience: pro +--- + +**源代码位置**将位置模型扩展到了静态分析领域：除了 URL（DAST）和依赖项（SCA）之外，**代码**位置用于描述某个 SAST 发现项在源代码中的位置——通过其**文件路径和行号**来标识。 + +> 源代码位置需要启用位置功能（测试版）。如需在您的实例上启用位置功能，请联系 [support@defectdojo.com](mailto:support@defectdojo.com)。 + +## 建模内容 + +每个报告了文件路径的静态发现项都会获得一个代码位置。该位置的规范值为 `path/to/file.py:42`（如果工具未报告行号，则仅为文件路径）。与所有位置一样，代码位置是共享对象：位于同一文件同一行的两个发现项会引用同一个位置，该位置同时携带按发现项和按资产划分的引用状态。 + +代码位置由**扫描管理**：它们通过导入和重新导入创建和更新，而不是手动创建。系统没有“新建源代码位置”操作——扫描器才是代码发现项所在位置的权威数据来源。 + +## 在哪里查看 + +- 侧边栏中的**所有源代码**会列出该实例中的每个代码位置，筛选和标签方式与 URL 及依赖项相同。 +- 资产的位置菜单中的**查看源代码**会将列表范围限定为单个资产。 +- 发现项页面会显示其当前的代码位置，如果该发现项发生过移动，还会显示其**位置历史**。 + +## 变动历史 + +源代码会不断变动：提交会改变行号，重构会重命名文件。当为某个工具启用了[位置漂移匹配](/triage_findings/finding_deduplication/pro__location_drift_matching/)后，发生移动的发现项会保留其身份标识，其代码位置引用会记录变动轨迹： + +- 该发现项对**旧**位置的引用会被标记为已缓解，并注明*发现项移动到了何处*以及*匹配的原因*（最近行、数据流、文件重命名等）。 +- 系统会创建一个指向**新**位置的引用，并保持其活动状态。 + +最终会形成一条可浏览的替代链——“该发现项最初位于 `auth.py:42`，随后移动到 `auth.py:57`，再移动到 `session.py:31`”——并以时间线的形式呈现在发现项页面上。同一套历史记录机制也适用于 URL 移动和依赖项版本升级，因此这三种位置类型共用同一套时间线界面。 + +历史记录从该实例启用位置功能的那一刻开始记录。在此之前发生移动的发现项会保留其当前位置；此前的变动虽然已经生效，但不会被记录下来。对于拥有多年历史数据（早于该功能上线）的实例，可以使用[变动合并命令](/triage_findings/finding_deduplication/pro__location_drift_matching/#consolidating-historical-churn)，在合并历史上的“关闭再重建”链条的同时重建变动轨迹。 + +## 状态准确性 + +无论是否启用漂移匹配，代码位置引用状态都会在**每种**匹配算法下通过重新导入保持准确： + +- 每次重新导入时，都会同步匹配发现项的当前代码引用，因此发生移动的发现项不会让其旧引用永远保持活动状态。 +- 这种不受开关影响的同步机制同样适用于依赖引用：当某个 SCA 发现项的软件包版本升级时，旧版本的引用会被标记为已缓解，而不会与新版本的引用同时保持活动状态。 + +## 与发现项字段的关系 + +发现项自身的 `file_path` / `line` 字段仍然是权威的标量值（筛选、哈希计算和 API 所公开的正是这些字段）；代码位置则是对同一坐标的共享、引用计数视图。重新导入会根据最新扫描结果刷新这些标量值，位置机制再据此推导出位置——两者不会出现不一致。 diff --git a/docs/content/asset_modelling/locations/PRO__working_with_sboms.it.md b/docs/content/asset_modelling/locations/PRO__working_with_sboms.it.md new file mode 100644 index 0000000000..0e083c2e22 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__working_with_sboms.it.md @@ -0,0 +1,107 @@ +--- +title: Utilizzo degli SBOM +description: Gestire le dipendenze software e gli SBOM come Location +audience: pro +weight: 5 +--- + +DefectDojo Pro rappresenta le librerie software come **Dependency Location**. Una Dependency è un sottotipo di Location identificato da un [Package URL (pURL)](https://github.com/package-url/purl-spec) e pensato per rappresentare una singola libreria o pacchetto — `org.apache.logging.log4j:log4j-core@2.17.0`, `pypi/django@5.0.2`, `npm/react@18.2.0`, e così via. + +Le Dependency sostituiscono il precedente modello **Components**, che era collegato solo ai Finding. Con Location, le librerie possono esistere indipendentemente da qualsiasi vulnerabilità — è possibile caricare un SBOM su un Asset e lasciare che i Finding si colleghino automaticamente alle dipendenze a cui fanno riferimento man mano che arrivano le scansioni. + +## Cosa contiene una Dependency + +Ogni Dependency è identificata in modo univoco da un pURL, scomposto in campi atomici su cui è possibile cercare e filtrare: + +| Campo | Significato | Esempio | +| --- | --- | --- | +| `purl_type` | Ecosistema della libreria | `npm`, `pypi`, `maven`, `cargo`, `nuget`, `gem` | +| `namespace` | Vendor o organizzazione | `org.apache.logging` | +| `name` | Nome della libreria | `log4j-core` | +| `version` | Versione specifica | `2.17.0` | +| `qualifiers` *(opzionale)* | Dettagli implementativi | `arch=amd64` | +| `subpath` *(opzionale)* | Percorso all'interno di un archivio o monorepo | `src/lib/foo` | +| `artifact_hashes` *(opzionale)* | Impronte digitali | somme SHA256 | +| `license_expression` *(opzionale)* | Espressione di licenza SPDX | `Apache-2.0`, `MIT` | +| `file_path` *(opzionale)* | Dove è stata trovata la libreria nel progetto | `package-lock.json` | + +Questa scomposizione atomica è ciò che rende utile la ricerca basata su pURL: si può chiedere *"tutti i pacchetti `pypi` nel namespace `django` alla versione 4.x"* e DefectDojo può rispondere senza dover analizzare una stringa di testo libero. + +## Owned-By vs Used-By + +Quando una Dependency è associata a un Asset, l'Asset Reference porta con sé una **relazione** opzionale che descrive *come* la libreria appartiene all'Asset: + +- **`owned_by`** — *"questa libreria è di proprietà di questo Asset"*. Utilizzare questo valore per le librerie proprietarie che un Asset pubblica o mantiene. +- **`used_by`** — *"questa libreria è utilizzata da questo Asset"*. Utilizzare questo valore per le dipendenze di terze parti che un Asset consuma. + +La stessa libreria può essere `owned_by` per un Asset e `used_by` per molti altri, che è esattamente la relazione necessaria per rispondere a *"chi consuma il pacchetto pubblicato dal mio team?"* durante il triage delle vulnerabilità. + +## Caricamento di un SBOM + +Per popolare le Dependency in blocco, caricare un file SBOM su un Product. L'endpoint è: + +``` +POST /api/v2/sbom-import/ +``` + +| Campo | Descrizione | +| --- | --- | +| `product` | L'ID del Product (Asset) di destinazione | +| `file` | Il file SBOM | +| `scan_type` | Il formato dell'SBOM — vedi i formati supportati di seguito | +| `replace` *(opzionale)* | Se `true`, le associazioni Product obsolete non supportate da un riferimento a un Finding esistente vengono rimosse. Predefinito: `false` (cumulativo) | + +L'importatore analizza il file, estrae i record `Dependency`, li deduplica rispetto alle Location esistenti (creandone di nuove quando necessario) e crea Asset Reference che collegano ogni Dependency al Product. L'interfaccia Pro espone lo stesso flusso di caricamento — vedi l'azione **Upload SBOM** nella scheda Location di un Product. + +### Formati supportati + +L'MVP include parser per i due formati SBOM dominanti: + +- **CycloneDX** — JSON e XML +- **SPDX** — JSON (v2 e v3), XML e tag-value + +Il formato SWID Tag non è ancora supportato. + +### Sostituzione o Aggiunta + +Per impostazione predefinita, i caricamenti ripetuti sono **additivi**: le dipendenze già presenti sull'Asset vengono mantenute, quelle nuove vengono aggiunte e nulla viene rimosso. Questo corrisponde al tipico flusso di lavoro degli aggiornamenti incrementali degli SBOM. + +Impostare `replace=true` per effettuare una pulizia. Quando la modalità replace è attiva, dopo un import riuscito l'importatore rimuove le associazioni Product che non erano presenti nel nuovo SBOM **e** che non sono attualmente referenziate da un Finding attivo. I riferimenti collegati a Finding attivi vengono preservati anche in modalità replace, quindi non si perde il contesto della vulnerabilità solo perché un nuovo SBOM omette un pacchetto. + +## Findings che fanno riferimento a librerie + +Quando un parser acquisisce una vulnerabilità collegata a una libreria — ad esempio, uno strumento SCA che segnala `CVE-2021-44228` contro `log4j-core@2.14.1` — l'importatore: + +1. Cerca una Dependency Location esistente tramite il pURL, oppure ne crea una nuova. +2. Crea una `LocationFindingReference` che collega il Finding alla Dependency con stato **Attivo**. +3. Crea una `LocationProductReference` in modo che la Dependency compaia anche sul Product padre, se non è già presente. + +Poiché i Finding e i caricamenti SBOM condividono gli stessi oggetti Dependency sottostanti, un Finding acquisito *prima* di un caricamento SBOM sarà visibile retroattivamente nella vista SBOM, e viceversa. + +## API REST + +| Attività | Endpoint | +| --- | --- | +| Caricare un SBOM | `POST /api/v2/sbom-import/` | +| Elencare le Dependency | `GET /api/v2/dependencies/` | +| Creare una Dependency manualmente | `POST /api/v2/dependencies/` | +| Elencare le Dependency Location | `GET /api/v2/location/?location_type=dependency` | +| Collegare una Dependency a un Finding | `POST /api/v2/location_findings/` | +| Collegare una Dependency a un Product (con `owned_by` / `used_by`) | `POST /api/v2/location_products/` | + +I filtri su `/api/v2/dependencies/` includono i campi componenti del pURL, i tag e l'ordinamento su `name`, `version` e il conteggio dei Finding attivi. + +## Nell'interfaccia Pro + +Quando Location è abilitata, la navigazione espone: + +- **Locations / Dependencies** — Elenco globale di tutte le Dependency nell'istanza, con filtri pURL. +- **Locations su un Product/Asset** — Vista per Asset che mostra sia URL sia Dependency, con l'azione **Upload SBOM** disponibile nella scheda Dependencies. +- **New Dependency** — Modulo per creare una singola libreria inserendo manualmente i componenti del suo pURL. +- **Findings detail** — Un Finding che riguarda una libreria mostra le sue Dependency Location insieme a eventuali URL Location, così è possibile vedere *"questa CVE riguarda `log4j-core@2.14.1` sull'Asset 6 e sull'Asset 9"* in un unico posto. + +## Cosa non è incluso nell'MVP + +- **Formato SBOM SWID Tag** — Non viene analizzato. È richiesto CycloneDX o SPDX. +- **Valutazione del rischio di licenza** — Il campo `license_expression` viene acquisito quando presente nell'SBOM, ma DefectDojo non segnala ancora i riscontri per incompatibilità di licenza. Il reporting basato sulle licenze è nella roadmap come seguito dell'MVP di Location. +- **Location per immagini container e risorse cloud** — Futuri sottotipi di Location. Per ora, le librerie individuate all'interno di un'immagine container vengono registrate come Dependency; l'immagine container stessa non è ancora una Location di prima classe. diff --git a/docs/content/asset_modelling/locations/PRO__working_with_sboms.pt-br.md b/docs/content/asset_modelling/locations/PRO__working_with_sboms.pt-br.md new file mode 100644 index 0000000000..773176a729 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__working_with_sboms.pt-br.md @@ -0,0 +1,107 @@ +--- +title: Trabalhando com SBOMs +description: Gerencie dependências de software e SBOMs como Localizações +audience: pro +weight: 5 +--- + +O DefectDojo Pro modela bibliotecas de software como **Localizações de Dependência**. Uma Dependência é um subtipo de Localização identificado por uma [Package URL (pURL)](https://github.com/package-url/purl-spec) e destinado a representar uma única biblioteca ou pacote — `org.apache.logging.log4j:log4j-core@2.17.0`, `pypi/django@5.0.2`, `npm/react@18.2.0`, e assim por diante. + +As Dependências substituem o antigo modelo de **Componentes**, que era anexado apenas a Achados. Com as Localizações, as bibliotecas podem existir independentemente de qualquer vulnerabilidade — você pode fazer upload de um SBOM para um Ativo e deixar que os Achados se anexem automaticamente às dependências que referenciam à medida que as varreduras chegam. + +## O Que Uma Dependência Contém + +Toda Dependência é identificada de forma exclusiva por uma pURL, decomposta em campos atômicos nos quais você pode pesquisar e filtrar: + +| Campo | Significado | Exemplo | +| --- | --- | --- | +| `purl_type` | Ecossistema da biblioteca | `npm`, `pypi`, `maven`, `cargo`, `nuget`, `gem` | +| `namespace` | Fornecedor ou organização | `org.apache.logging` | +| `name` | Nome da biblioteca | `log4j-core` | +| `version` | Versão específica | `2.17.0` | +| `qualifiers` *(opcional)* | Detalhes de implementação | `arch=amd64` | +| `subpath` *(opcional)* | Caminho dentro de um arquivo compactado ou monorepo | `src/lib/foo` | +| `artifact_hashes` *(opcional)* | Fingerprints | Somas SHA256 | +| `license_expression` *(opcional)* | Expressão de licença SPDX | `Apache-2.0`, `MIT` | +| `file_path` *(opcional)* | Onde a biblioteca foi encontrada no projeto | `package-lock.json` | + +Essa decomposição atômica é o que torna útil a pesquisa baseada em pURL: você pode perguntar *"todos os pacotes `pypi` no namespace `django` na versão 4.x"* e o DefectDojo consegue responder isso sem analisar uma string de texto livre. + +## Owned-By vs Used-By + +Quando uma Dependência é associada a um Ativo, a Asset Reference carrega um **relacionamento** opcional que descreve *como* a biblioteca pertence ao Ativo: + +- **`owned_by`** — *"esta biblioteca é de propriedade deste Ativo"*. Use isso para bibliotecas próprias (first-party) que um Ativo publica ou mantém. +- **`used_by`** — *"esta biblioteca é usada por este Ativo"*. Use isso para dependências de terceiros que um Ativo consome. + +A mesma biblioteca pode ser `owned_by` de um Ativo e `used_by` de vários outros, que é exatamente o relacionamento necessário para responder *"quem consome o pacote que minha equipe publica?"* durante a triagem de vulnerabilidades. + +## Fazendo Upload de um SBOM + +Para popular Dependências em massa, faça upload de um arquivo SBOM em relação a um Produto. O endpoint é: + +``` +POST /api/v2/sbom-import/ +``` + +| Campo | Descrição | +| --- | --- | +| `product` | O ID do Produto (Ativo) de destino | +| `file` | O arquivo SBOM | +| `scan_type` | O formato do SBOM — veja os formatos suportados abaixo | +| `replace` *(opcional)* | Se `true`, associações de Produto obsoletas que não têm o suporte de uma referência de Achado existente são removidas. Padrão: `false` (cumulativo) | + +O importador analisa o arquivo, extrai os registros `Dependency`, deduplica-os em relação às Localizações existentes (criando novas conforme necessário) e cria Asset References vinculando cada Dependência ao Produto. A interface do Pro expõe o mesmo fluxo de upload — veja a ação **Upload SBOM** na aba de Localizações de um Produto. + +### Formatos Suportados + +O MVP inclui parsers para os dois formatos de SBOM dominantes: + +- **CycloneDX** — JSON e XML +- **SPDX** — JSON (v2 e v3), XML e tag-value + +O formato SWID Tag ainda não é suportado. + +### Substituir vs Anexar + +Por padrão, uploads repetidos são **aditivos**: as dependências que já existem no Ativo são mantidas, novas são adicionadas e nada é removido. Isso corresponde ao fluxo de trabalho típico de atualizações incrementais de SBOM. + +Defina `replace=true` para podar (prune). Quando o modo replace está ativado, após uma importação bem-sucedida o importador remove as associações de Produto que não estavam presentes no novo SBOM **e** que não são referenciadas atualmente por um Achado ativo. As referências vinculadas a Achados ativos são preservadas mesmo no modo replace, para que você não perca o contexto de vulnerabilidade apenas porque um novo SBOM omite um pacote. + +## Achados Que Referenciam Bibliotecas + +Quando um parser ingere uma vulnerabilidade vinculada a uma biblioteca — por exemplo, uma ferramenta de SCA reportando `CVE-2021-44228` contra `log4j-core@2.14.1` — o importador: + +1. Procura uma Localização de Dependência existente pela pURL, ou cria uma nova. +2. Cria uma `LocationFindingReference` vinculando o Achado à Dependência com status **Ativo**. +3. Cria uma `LocationProductReference` para que a Dependência também apareça no Produto pai, caso ainda não apareça. + +Como os Achados e os uploads de SBOM compartilham os mesmos objetos de Dependência subjacentes, um Achado ingerido *antes* de um upload de SBOM ficará visível retroativamente na visualização do SBOM, e vice-versa. + +## API REST + +| Tarefa | Endpoint | +| --- | --- | +| Fazer upload de um SBOM | `POST /api/v2/sbom-import/` | +| Listar Dependências | `GET /api/v2/dependencies/` | +| Criar uma Dependência manualmente | `POST /api/v2/dependencies/` | +| Listar Localizações de Dependência | `GET /api/v2/location/?location_type=dependency` | +| Vincular uma Dependência a um Achado | `POST /api/v2/location_findings/` | +| Vincular uma Dependência a um Produto (com `owned_by` / `used_by`) | `POST /api/v2/location_products/` | + +Os filtros em `/api/v2/dependencies/` incluem os campos de componente da pURL, tags e ordenação por `name`, `version` e contagem de achados ativos. + +## Na Interface do Pro + +Quando as Localizações estão habilitadas, a navegação expõe: + +- **Locations / Dependencies** — Lista global de todas as Dependências na instância, com filtros de pURL. +- **Locations on a Product/Asset** — Visualização por Ativo que mostra tanto URLs quanto Dependências, com a ação **Upload SBOM** disponível na aba Dependencies. +- **New Dependency** — Formulário para criar uma única biblioteca inserindo manualmente os componentes de sua pURL. +- **Findings detail** — Um Achado que envolve uma biblioteca mostra suas Localizações de Dependência ao lado de quaisquer Localizações de URL, para que você possa ver *"este CVE afeta `log4j-core@2.14.1` no Ativo 6 e no Ativo 9"* em um só lugar. + +## O Que Não Está no MVP + +- **Formato de SBOM SWID Tag** — Não é analisado. CycloneDX ou SPDX é obrigatório. +- **Pontuação de risco de licença** — O campo `license_expression` é capturado quando presente no SBOM, mas o DefectDojo ainda não sinaliza achados por incompatibilidade de licença. Relatórios baseados em licença estão no roadmap como um follow-up ao MVP de Localizações. +- **Localizações de imagem de contêiner e recurso de nuvem** — Subtipos futuros de Localização. Por enquanto, bibliotecas descobertas dentro de uma imagem de contêiner são registradas como Dependências; a própria imagem de contêiner ainda não é uma Localização de primeira classe. diff --git a/docs/content/asset_modelling/locations/PRO__working_with_sboms.zh-hans.md b/docs/content/asset_modelling/locations/PRO__working_with_sboms.zh-hans.md new file mode 100644 index 0000000000..9e2f3b02cf --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__working_with_sboms.zh-hans.md @@ -0,0 +1,107 @@ +--- +title: 使用 SBOM +description: 以位置的形式管理软件依赖项和 SBOM +audience: pro +weight: 5 +--- + +DefectDojo Pro 将软件库建模为**依赖位置**。依赖项是一种位置子类型，通过[软件包 URL（pURL）](https://github.com/package-url/purl-spec)进行标识，用于表示单个库或软件包——例如 `org.apache.logging.log4j:log4j-core@2.17.0`、`pypi/django@5.0.2`、`npm/react@18.2.0` 等。 + +依赖项取代了此前仅能附加在发现项上的**组件**模型。借助位置功能，库可以独立于任何漏洞而存在——您可以向某个资产上传 SBOM，随后在扫描结果不断导入时，让发现项自动关联到它们所引用的依赖项。 + +## 依赖项包含哪些内容 + +每个依赖项都由一个 pURL 唯一标识，并分解为若干可供搜索和筛选的原子字段： + +| 字段 | 含义 | 示例 | +| --- | --- | --- | +| `purl_type` | 库生态系统 | `npm`、`pypi`、`maven`、`cargo`、`nuget`、`gem` | +| `namespace` | 供应商或组织 | `org.apache.logging` | +| `name` | 库名称 | `log4j-core` | +| `version` | 具体版本 | `2.17.0` | +| `qualifiers` *(可选)* | 实现细节 | `arch=amd64` | +| `subpath` *(可选)* | 归档文件或 monorepo 内的路径 | `src/lib/foo` | +| `artifact_hashes` *(可选)* | 指纹 | SHA256 校验和 | +| `license_expression` *(可选)* | SPDX 许可证表达式 | `Apache-2.0`、`MIT` | +| `file_path` *(可选)* | 在项目中发现该库的位置 | `package-lock.json` | + +正是这种原子化的拆分，使得基于 pURL 的搜索变得实用：您可以询问*“`django` 命名空间下所有版本为 4.x 的 `pypi` 软件包”*，DefectDojo 无需解析自由文本字符串即可给出答案。 + +## 归属方（Owned-By）与使用方（Used-By） + +当某个依赖项与某个资产关联时，资产引用会携带一个可选的**关系**字段，用于描述该库*以何种方式*归属于该资产： + +- **`owned_by`** —— *“该库归属于此资产”*。适用于某资产发布或维护的自有库。 +- **`used_by`** —— *“该库被此资产使用”*。适用于某资产所使用的第三方依赖项。 + +同一个库可以对一个资产是 `owned_by`，同时对其他多个资产是 `used_by`，这正是在漏洞分诊过程中回答*“谁在使用我们团队发布的软件包？”*所需要的关系。 + +## 上传 SBOM + +要批量填充依赖项，请针对某个产品上传 SBOM 文件。该端点为： + +``` +POST /api/v2/sbom-import/ +``` + +| 字段 | 说明 | +| --- | --- | +| `product` | 目标产品（资产）ID | +| `file` | SBOM 文件 | +| `scan_type` | SBOM 格式——见下方支持的格式 | +| `replace` *(可选)* | 若为 `true`，则会移除没有现有发现项引用支撑的过期产品关联。默认值：`false`（累加模式） | + +导入器会解析该文件、提取 `Dependency` 记录、将其与现有位置进行去重（按需创建新记录），并创建资产引用，将每个依赖项关联到该产品。Pro 版界面提供了相同的上传流程——参见产品位置标签页中的**上传 SBOM**操作。 + +### 支持的格式 + +该 MVP 版本提供了针对两种主流 SBOM 格式的解析器： + +- **CycloneDX** —— JSON 和 XML +- **SPDX** —— JSON（v2 和 v3）、XML 和 tag-value + +目前尚不支持 SWID Tag 格式。 + +### 替换与追加 + +默认情况下，重复上传是**累加式**的：资产上已存在的依赖项会被保留，新的依赖项会被添加，不会移除任何内容。这与典型的增量 SBOM 更新流程相符。 + +将 `replace` 设置为 `true` 可进行清理。启用替换模式后，导入成功后，导入器会移除新 SBOM 中不存在**且**当前未被任何活动发现项引用的产品关联。即使在替换模式下，与活动发现项相关联的引用也会被保留，因此不会因为新的 SBOM 遗漏了某个软件包而丢失漏洞上下文。 + +## 引用库的发现项 + +当解析器摄取与某个库相关联的漏洞时——例如某个 SCA 工具针对 `log4j-core@2.14.1` 报告了 `CVE-2021-44228`——导入器会： + +1. 按 pURL 查找现有的依赖位置，若不存在则创建一个新的。 +2. 创建一个 `LocationFindingReference`，将该发现项与该依赖项关联，状态为**活动**。 +3. 创建一个 `LocationProductReference`，使该依赖项也出现在其所属的父级产品下（如果尚未出现）。 + +由于发现项和 SBOM 上传共用同一套底层依赖项对象，*先于* SBOM 上传而摄取的发现项会追溯性地出现在 SBOM 视图中，反之亦然。 + +## REST API + +| 任务 | 端点 | +| --- | --- | +| 上传 SBOM | `POST /api/v2/sbom-import/` | +| 列出依赖项 | `GET /api/v2/dependencies/` | +| 手动创建依赖项 | `POST /api/v2/dependencies/` | +| 列出依赖位置 | `GET /api/v2/location/?location_type=dependency` | +| 将依赖项关联到发现项 | `POST /api/v2/location_findings/` | +| 将依赖项关联到产品（使用 `owned_by` / `used_by`） | `POST /api/v2/location_products/` | + +`/api/v2/dependencies/` 上的筛选条件包括 pURL 的各组成字段、标签，以及按 `name`、`version` 和活动发现项数量进行排序。 + +## 在 Pro 版界面中 + +启用位置功能后，导航栏会提供以下选项： + +- **位置 / 依赖项** —— 该实例中所有依赖项的全局列表，支持 pURL 筛选。 +- **产品/资产上的位置** —— 按资产划分的视图，同时显示 URL 和依赖项，**上传 SBOM** 操作显示在依赖项标签页上。 +- **新建依赖项** —— 通过手动输入 pURL 各组成部分来创建单个库的表单。 +- **发现项详情** —— 涉及某个库的发现项会将其依赖位置与任何 URL 位置一并显示，因此您可以在同一个地方看到“该 CVE 影响资产 6 和资产 9 上的 `log4j-core@2.14.1`”。 + +## MVP 中尚未包含的内容 + +- **SWID Tag SBOM 格式** —— 尚未支持解析，需使用 CycloneDX 或 SPDX。 +- **许可证风险评分** —— 当 SBOM 中存在 `license_expression` 字段时会被采集，但 DefectDojo 尚不会针对许可证不兼容标记发现项。基于许可证的报告功能已列入路线图，作为位置 MVP 的后续功能。 +- **容器镜像与云资源位置** —— 属于未来的位置子类型。目前，在容器镜像中发现的库会被记录为依赖项；容器镜像本身尚未成为一等公民的位置类型。 diff --git a/docs/content/asset_modelling/locations/PRO__working_with_urls.it.md b/docs/content/asset_modelling/locations/PRO__working_with_urls.it.md new file mode 100644 index 0000000000..98cea27d1e --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__working_with_urls.it.md @@ -0,0 +1,88 @@ +--- +title: Utilizzo degli URL +description: Utilizzo quotidiano delle URL Location come sostituto degli Endpoint +audience: pro +weight: 4 +--- + +Le URL Location sono il sostituto funzionale del vecchio modello Endpoint. Memorizzano gli stessi campi in forma di URL a cui si è abituati — `protocol`, `host`, `port`, `path`, `query`, `fragment` — e svolgono lo stesso ruolo: identificare *dove* risiede un Finding di un'applicazione web. + +Questa pagina illustra cosa cambia quando si inizia a usare le URL Location quotidianamente, le nuove superfici dell'interfaccia e gli endpoint API da usare al posto della vecchia API Endpoint. + +## Il sottotipo URL + +Ogni URL è una Location. Ciò significa che un URL possiede sia: + +- I campi strutturati dell'URL (`protocol`, `user_info`, `host`, `port`, `path`, `query`, `fragment`, oltre a un `hash` usato per la deduplicazione). +- I campi condivisi della Location (`location_type="url"`, una stringa canonica `location_value` per la visualizzazione e la ricerca, tag, tag ereditati, metadati e collegamenti Reference ad Asset e Finding). + +Quando si crea o si carica un URL, DefectDojo lo analizza nei campi strutturati e scrive sia la riga URL sia la riga Location padre in un'unica transazione. La deduplicazione degli URL avviene per corrispondenza esatta tra i campi strutturati — due URL sono considerati uguali se ogni componente corrisponde, con il consueto collasso della porta predefinita (`http://example.com:80/` e `http://example.com/` risolvono nello stesso URL). + +## Nell'interfaccia Pro + +Quando la funzionalità Location è abilitata, la navigazione espone: + +- **Locations / All** — Un elenco di tutte le Location, sia nel sottotipo URL sia in quello Dependency. Filtrabile per tipo, stato, Asset, Finding o tag. +- **Locations / URLs** — Un elenco limitato alle sole URL Location. È l'equivalente più vicino alla vecchia pagina Endpoint. +- **New URL** — Un modulo per creare un singolo URL con campi strutturati, tag e associazioni opzionali ad Asset/Finding. +- **Locations su un Asset** — Da qualsiasi Asset, la scheda **Locations** mostra gli URL e le Dependency collegati a quell'Asset, con conteggi di stato e azioni rapide. + +I flussi di lavoro comuni dell'interfaccia Endpoint sono stati preservati: + +- **Aggiornamenti di stato in blocco.** Selezionare più URL Location e applicare uno stato (Attivo, Mitigato, Falso positivo, Rischio accettato, Fuori ambito) ai relativi riferimenti Finding in un'unica azione. +- **Aggiunta di URL esistenti a un Asset.** Usare **Add Existing** nella scheda Locations di un Asset per collegare URL già presenti nel sistema invece di crearne di duplicati. +- **Tag.** I tag applicati a una URL Location si propagano come tag ereditati sui Finding che la referenziano, allo stesso modo in cui facevano prima i tag degli Endpoint. + +## Modello di stato + +Le URL Location usano le stesse etichette a stato singolo di tutte le altre Location: + +| Stato | Significato | +| --- | --- | +| **Attivo** | Il Finding su questo URL è aperto. | +| **Mitigato** | Il Finding è stato risolto per questo URL. | +| **Falso positivo** | Il Finding non è una vulnerabilità reale per questo URL. | +| **Rischio accettato** | Il Finding è riconosciuto ma accettato su questo URL. | +| **Fuori ambito** | Questo URL è escluso dall'engagement. | + +Nota che il vecchio modello Endpoint Status consentiva più flag contemporaneamente (ad es. `mitigated=True` e `false_positive=True`). Le Location impongono un solo stato alla volta. Se si è migrato dagli Endpoint, è stato preservato il flag più specifico (vedi la tabella di mappatura in [Migrazione dagli Endpoint](../pro__migrating_from_endpoints)). + +Gli Asset Reference usano uno stato più semplice: solo **Attivo** o **Mitigato**, poiché lo stato a livello di Asset non richiede il dettaglio di audit. + +## API REST + +Usare questi endpoint al posto della vecchia API Endpoint: + +| Attività | Endpoint | +| --- | --- | +| Elencare gli URL | `GET /api/v2/urls/` | +| Creare un URL | `POST /api/v2/urls/` | +| Aggiornare i tag o i metadati di un URL | `PATCH /api/v2/urls/{id}/` | +| Elencare tutte le Location (URL + Dependency) | `GET /api/v2/location/?location_type=url` | +| Collegare un URL a un Finding | `POST /api/v2/location_findings/` | +| Collegare un URL a un Asset | `POST /api/v2/location_Assets/` | +| Aggiornare lo stato di un collegamento Finding | `PATCH /api/v2/location_findings/{id}/` | +| Rimuovere un collegamento Finding | `DELETE /api/v2/location_findings/{id}/` | + +I filtri su `/api/v2/urls/` includono i campi strutturati dell'URL più `tag(s)`, `has_tags`, `Asset`, e l'ordinamento per `host`, `Asset` o conteggio dei Finding attivi. + +Il vecchio endpoint `/api/v2/endpoints/` continua a servire il traffico in **lettura** tramite uno shim di compatibilità — vedi [Migrazione dagli Endpoint](../pro__migrating_from_endpoints) per ciò che viene preservato e dove lo shim si discosta dal comportamento originale. Le **scritture** verso gli endpoint legacy restituiscono `403` e devono essere spostate verso gli endpoint sopra indicati. + +## Importazione di URL dalle scansioni + +Gli import dello scanner creano automaticamente le URL Location. Quando un parser genera un URL per un Finding (nello stesso modo in cui prima generava un Endpoint), l'importatore: + +1. Cerca un URL esistente con campi strutturati corrispondenti, oppure ne crea uno. +2. Crea un Finding Reference che collega il Finding all'URL con stato **Attivo**. +3. Crea (o riutilizza) un Asset Reference in modo che l'URL compaia anche sull'Asset padre. + +I parser DefectDojo che in precedenza creavano Endpoint sono stati aggiornati per creare automaticamente Location in Pro. + +## Cose che si comportano diversamente + +Vale la pena notare alcuni piccoli cambiamenti di comportamento: + +- **Un solo stato per coppia URL/Finding.** Come descritto sopra, il modello Endpoint_Status multi-flag viene compresso in un unico stato. I flussi di lavoro che attivavano i flag in modo indipendente devono scegliere una singola transizione. +- **I tag risiedono sulla Location, non sull'URL.** Il sottotipo URL non ha un proprio insieme di tag; i tag appartengono alla Location padre. Se si legge un URL tramite l'API, il campo `tags` proviene da `location.tags`. +- **La deduplicazione è per URL canonico, non per Asset.** Due Asset che hanno lo stesso URL condividono un'unica URL Location sottostante e la referenziano due volte (un Asset Reference ciascuno). Questo è intenzionale ed è ciò che consente il reporting cross-Asset. +- **Il campo `endpoints` sui Finding.** Quando il flag è attivo, questo campo nell'API Finding continua a restituire righe, ma sono proiettate dalle URL Location anziché dalla tabella Endpoint. Trattarlo come sola lettura e scrivere invece tramite `/api/v2/location_findings/`. diff --git a/docs/content/asset_modelling/locations/PRO__working_with_urls.pt-br.md b/docs/content/asset_modelling/locations/PRO__working_with_urls.pt-br.md new file mode 100644 index 0000000000..2c550635d9 --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__working_with_urls.pt-br.md @@ -0,0 +1,88 @@ +--- +title: Trabalhando com URLs +description: Uso cotidiano de Localizações de URL como substituição dos Endpoints +audience: pro +weight: 4 +--- + +As Localizações de URL são a substituição funcional do antigo modelo de Endpoints. Elas armazenam os mesmos campos no formato de URL aos quais você já está acostumado — `protocol`, `host`, `port`, `path`, `query`, `fragment` — e cumprem o mesmo papel: identificar *onde* vive um Achado de aplicação web. + +Esta página aborda o que muda quando você passa a usar Localizações de URL no dia a dia, as novas telas da interface e os endpoints de API a usar no lugar da antiga API de Endpoint. + +## O Subtipo URL + +Toda URL é uma Localização. Isso significa que uma URL tem, ao mesmo tempo: + +- Os campos estruturados de URL (`protocol`, `user_info`, `host`, `port`, `path`, `query`, `fragment`, além de um `hash` usado para deduplicação). +- Os campos compartilhados de Localização (`location_type="url"`, uma string canônica `location_value` para exibição e busca, tags, tags herdadas, metadados e vínculos de referência com Ativos e Achados). + +Quando você cria ou faz upload de uma URL, o DefectDojo a analisa nos campos estruturados e grava tanto a linha de URL quanto sua linha de Localização pai em uma única transação. A deduplicação de URL é uma correspondência exata entre os campos estruturados — duas URLs são consideradas iguais se todos os componentes coincidirem, com o colapso padrão de porta default (`http://example.com:80/` e `http://example.com/` resolvem para a mesma URL). + +## Na Interface do Pro + +Quando o recurso de Localizações está habilitado, a navegação expõe: + +- **Locations / All** — Uma lista de todas as Localizações, tanto do subtipo URL quanto do subtipo Dependência. Filtre por tipo, status, Ativo, Achado ou tag. +- **Locations / URLs** — Uma lista restrita apenas às Localizações de URL. É o análogo mais próximo da antiga página de Endpoints. +- **New URL** — Um formulário para criar uma única URL com campos estruturados, tags e associações opcionais de Ativo/Achado. +- **Locations on an Asset** — A partir de qualquer Ativo, a aba **Locations** mostra as URLs e Dependências anexadas a esse Ativo, com contagens de status e ações rápidas. + +Os fluxos de trabalho comuns da interface de Endpoints são preservados: + +- **Atualizações de status em massa.** Selecione várias Localizações de URL e aplique um status (Ativo, Mitigado, Falso positivo, Risco aceito, Fora do escopo) às suas referências de Achado em uma única ação. +- **Adicionando URLs existentes a um Ativo.** Use **Add Existing** na aba Locations de um Ativo para vincular URLs já existentes no sistema, em vez de criar duplicatas. +- **Tags.** As tags aplicadas a uma Localização de URL propagam-se como tags herdadas nos Achados que a referenciam, da mesma forma que as tags de Endpoint faziam anteriormente. + +## Modelo de Status + +As Localizações de URL usam os mesmos rótulos de status único que todas as outras Localizações: + +| Status | Significado | +| --- | --- | +| **Ativo** | O Achado nesta URL está aberto. | +| **Mitigado** | O Achado foi corrigido para esta URL. | +| **Falso positivo** | O Achado não é uma vulnerabilidade real para esta URL. | +| **Risco aceito** | O Achado é reconhecido, mas aceito nesta URL. | +| **Fora do escopo** | Esta URL está excluída do engajamento. | + +Observe que o antigo modelo de Endpoint Status permitia múltiplas flags simultaneamente (por exemplo, `mitigated=True` e `false_positive=True`). As Localizações impõem apenas um status por vez. Se você migrou a partir de Endpoints, a flag mais específica foi preservada (veja a tabela de mapeamento em [Migração a partir de Endpoints](../pro__migrating_from_endpoints)). + +As Asset References usam um status mais simples: apenas **Ativo** ou **Mitigado**, já que o status em nível de Ativo não precisa do mesmo detalhamento de auditoria. + +## API REST + +Use estes endpoints no lugar da antiga API de Endpoint: + +| Tarefa | Endpoint | +| --- | --- | +| Listar URLs | `GET /api/v2/urls/` | +| Criar uma URL | `POST /api/v2/urls/` | +| Atualizar as tags ou metadados de uma URL | `PATCH /api/v2/urls/{id}/` | +| Listar todas as Localizações (URLs + Dependências) | `GET /api/v2/location/?location_type=url` | +| Vincular uma URL a um Achado | `POST /api/v2/location_findings/` | +| Vincular uma URL a um Ativo | `POST /api/v2/location_Assets/` | +| Atualizar o status de um vínculo de Achado | `PATCH /api/v2/location_findings/{id}/` | +| Remover um vínculo de Achado | `DELETE /api/v2/location_findings/{id}/` | + +Os filtros em `/api/v2/urls/` incluem os campos estruturados de URL, além de `tag(s)`, `has_tags`, `Asset`, e ordenação por `host`, `Asset` ou contagem de achados ativos. + +O antigo endpoint `/api/v2/endpoints/` ainda atende tráfego de **leitura** por meio de uma camada de compatibilidade — veja [Migração a partir de Endpoints](../pro__migrating_from_endpoints) para saber o que é preservado e onde essa camada difere do comportamento original. **Gravações** nos endpoints legados retornam `403` e devem ser migradas para os endpoints acima. + +## Importando URLs a partir de Varreduras + +As importações de scanner criam Localizações de URL automaticamente. Quando um parser emite uma URL para um Achado (da mesma forma que antes emitia um Endpoint), o importador: + +1. Procura uma URL existente com campos estruturados correspondentes, ou cria uma. +2. Cria uma Finding Reference vinculando o Achado à URL com status **Ativo**. +3. Cria (ou reutiliza) uma Asset Reference para que a URL também apareça no Ativo pai. + +Os parsers do DefectDojo que anteriormente criavam Endpoints foram atualizados para criar Localizações automaticamente no Pro. + +## Coisas Que Se Comportam de Forma Diferente + +Vale destacar algumas pequenas mudanças de comportamento: + +- **Um status por par URL/Achado.** Como descrito acima, o modelo de múltiplas flags do Endpoint_Status é reduzido a um único status. Fluxos de trabalho que alternavam flags de forma independente precisam escolher uma única transição. +- **As tags residem na Localização, não na URL.** O subtipo URL não possui seu próprio conjunto de tags; as tags pertencem à Localização pai. Se você ler uma URL pela API, o campo `tags` vem de `location.tags`. +- **A deduplicação é por URL canônica, não por Ativo.** Dois Ativos que têm a mesma URL compartilham uma única Localização de URL subjacente e a referenciam duas vezes (uma Asset Reference cada). Isso é intencional e é o que permite relatórios entre Ativos. +- **O campo `endpoints` nos Achados.** Quando a flag está ativada, esse campo na API de Achado ainda retorna linhas, mas elas são projetadas a partir de Localizações de URL, em vez da tabela de Endpoint. Trate-o como somente leitura e grave por meio de `/api/v2/location_findings/`. diff --git a/docs/content/asset_modelling/locations/PRO__working_with_urls.zh-hans.md b/docs/content/asset_modelling/locations/PRO__working_with_urls.zh-hans.md new file mode 100644 index 0000000000..fb6e272d5b --- /dev/null +++ b/docs/content/asset_modelling/locations/PRO__working_with_urls.zh-hans.md @@ -0,0 +1,88 @@ +--- +title: 使用 URL +description: 作为端点替代方案的 URL 位置日常使用方法 +audience: pro +weight: 4 +--- + +URL 位置在功能上取代了旧版的端点模型。它们存储着您熟悉的相同 URL 结构字段——`protocol`、`host`、`port`、`path`、`query`、`fragment`——并发挥着相同的作用：标识某个 Web 应用发现项*位于何处*。 + +本页介绍在日常使用 URL 位置时会发生哪些变化、新增的界面入口，以及应使用哪些 API 端点来代替旧版端点 API。 + +## URL 子类型 + +每个 URL 都是一个位置。这意味着 URL 同时具备： + +- 结构化的 URL 字段（`protocol`、`user_info`、`host`、`port`、`path`、`query`、`fragment`，以及用于去重的 `hash`）。 +- 共享的位置字段（`location_type="url"`、用于显示和搜索的规范 `location_value` 字符串、标签、继承标签、元数据，以及指向资产和发现项的引用链接）。 + +当您创建或上传一个 URL 时，DefectDojo 会将其解析为结构化字段，并在一次事务中同时写入 URL 记录及其父级位置记录。URL 去重采用结构化字段的精确匹配——只有当所有组成部分都匹配时，两个 URL 才会被视为相同，同时会应用标准的默认端口归并规则（`http://example.com:80/` 和 `http://example.com/` 会解析为同一个 URL）。 + +## 在 Pro 版界面中 + +启用位置功能后，导航栏会提供以下选项： + +- **位置 / 全部** —— 列出 URL 和依赖项两种子类型下的所有位置，可按类型、状态、资产、发现项或标签进行筛选。 +- **位置 / URL** —— 仅显示 URL 位置的限定列表，是与旧版端点页面最为接近的对应功能。 +- **新建 URL** —— 用于创建单个 URL 的表单，包含结构化字段、标签以及可选的资产/发现项关联。 +- **资产上的位置** —— 在任意资产中，**位置**标签页会显示附加在该资产上的 URL 和依赖项，并提供状态统计和快捷操作。 + +旧版端点界面中的常见工作流程得以保留： + +- **批量状态更新。** 选择多个 URL 位置，一次性为其发现项引用应用某个状态（活动、已缓解、误报、风险已接受、超出范围）。 +- **将现有 URL 添加到资产。** 在资产的位置标签页中使用**添加现有项**，即可关联系统中已存在的 URL，而不必创建重复项。 +- **标签。** 应用于某个 URL 位置的标签，会作为继承标签传播到引用它的发现项上，与此前端点标签的行为方式相同。 + +## 状态模型 + +URL 位置使用与所有其他位置相同的单一状态标签： + +| 状态 | 含义 | +| --- | --- | +| **活动** | 该 URL 上的发现项处于开放状态。 | +| **已缓解** | 该 URL 上的发现项已完成修复。 | +| **误报** | 该发现项在此 URL 上并非真实漏洞。 | +| **风险已接受** | 该发现项在此 URL 上已被确认但接受其风险。 | +| **超出范围** | 该 URL 已被排除在测试活动范围之外。 | + +请注意，旧版的端点状态模型允许多个标志同时生效（例如 `mitigated=True` 和 `false_positive=True`）。位置在同一时刻只强制保留一个状态。如果您是从端点迁移而来，系统会保留最具体的标志（参见[从端点迁移](../pro__migrating_from_endpoints)中的映射表）。 + +资产引用使用更简单的状态：仅有**活动**或**已缓解**，因为资产级别的状态不需要那么详细的审计信息。 + +## REST API + +请使用以下端点来代替旧版端点 API： + +| 任务 | 端点 | +| --- | --- | +| 列出 URL | `GET /api/v2/urls/` | +| 创建 URL | `POST /api/v2/urls/` | +| 更新 URL 的标签或元数据 | `PATCH /api/v2/urls/{id}/` | +| 列出所有位置（URL + 依赖项） | `GET /api/v2/location/?location_type=url` | +| 将 URL 关联到发现项 | `POST /api/v2/location_findings/` | +| 将 URL 关联到资产 | `POST /api/v2/location_Assets/` | +| 更新发现项关联的状态 | `PATCH /api/v2/location_findings/{id}/` | +| 移除发现项关联 | `DELETE /api/v2/location_findings/{id}/` | + +`/api/v2/urls/` 上的筛选条件包括结构化 URL 字段，以及 `tag(s)`、`has_tags`、`Asset`，并支持按 `host`、`Asset` 或活动发现项数量排序。 + +旧版的 `/api/v2/endpoints/` 端点仍通过兼容层提供**读取**流量的服务——关于保留了哪些内容以及该兼容层与原始行为的差异，请参见[从端点迁移](../pro__migrating_from_endpoints)。对旧版端点的**写入**操作会返回 `403`，必须迁移到上述端点。 + +## 从扫描导入 URL + +扫描器导入会自动创建 URL 位置。当解析器为某个发现项输出一个 URL 时（与此前输出端点的方式相同），导入器会： + +1. 查找结构化字段匹配的现有 URL，若不存在则创建一个。 +2. 创建一个发现项引用，将该发现项与该 URL 关联，状态为**活动**。 +3. 创建（或复用）一个资产引用，使该 URL 也出现在其所属的父级资产下。 + +此前会创建端点的 DefectDojo 解析器均已更新，可在 Pro 版中自动创建位置。 + +## 行为差异之处 + +以下几个细微的行为变化值得注意： + +- **每个 URL/发现项组合仅有一个状态。** 如上所述，多标志的 Endpoint_Status 模型已被归并为单一状态。原先独立切换各个标志的工作流程，现在需要选择一次单一的状态转换。 +- **标签位于位置上，而非 URL 上。** URL 子类型本身不携带独立的标签集合；标签属于其父级位置。通过 API 读取 URL 时，`tags` 字段来自 `location.tags`。 +- **去重按规范化 URL 进行，而非按资产进行。** 拥有相同 URL 的两个资产会共享同一个底层 URL 位置，并各自对其引用一次（每个资产各有一个资产引用）。这是有意为之的设计，正是它使得跨资产报告成为可能。 +- **发现项上的 `endpoints` 字段。** 当该功能开启时，发现项 API 上的这个字段仍会返回记录，但这些记录是由 URL 位置映射而成，而非来自端点表。请将其视为只读字段，写入操作应改为通过 `/api/v2/location_findings/` 进行。 diff --git a/docs/content/asset_modelling/locations/_index.it.md b/docs/content/asset_modelling/locations/_index.it.md new file mode 100644 index 0000000000..028e7d7942 --- /dev/null +++ b/docs/content/asset_modelling/locations/_index.it.md @@ -0,0 +1,12 @@ +--- +title: Location +description: Modellazione degli asset ad alta fedeltà — URL, SBOM e oltre +date: 2026-05-06 00:00:00+00:00 +draft: false +type: docs +audience: pro +weight: 4 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/locations/_index.pt-br.md b/docs/content/asset_modelling/locations/_index.pt-br.md new file mode 100644 index 0000000000..e16a4e98a9 --- /dev/null +++ b/docs/content/asset_modelling/locations/_index.pt-br.md @@ -0,0 +1,12 @@ +--- +title: Localizações +description: Modelagem de ativos com maior fidelidade — URLs, SBOMs e muito mais +date: 2026-05-06 00:00:00+00:00 +draft: false +type: docs +audience: pro +weight: 4 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/locations/_index.zh-hans.md b/docs/content/asset_modelling/locations/_index.zh-hans.md new file mode 100644 index 0000000000..a5acc51898 --- /dev/null +++ b/docs/content/asset_modelling/locations/_index.zh-hans.md @@ -0,0 +1,12 @@ +--- +title: 位置 +description: 更高精度的资产建模——URL、SBOM 及更多 +date: 2026-05-06 00:00:00+00:00 +draft: false +type: docs +audience: pro +weight: 4 +sidebar: + collapsed: false +exclude_search: true +--- diff --git a/docs/content/asset_modelling/tags/OS__tagging_objects.it.md b/docs/content/asset_modelling/tags/OS__tagging_objects.it.md new file mode 100644 index 0000000000..d8c47d66ea --- /dev/null +++ b/docs/content/asset_modelling/tags/OS__tagging_objects.it.md @@ -0,0 +1,149 @@ +--- +title: Assegnazione dei Tag agli Oggetti +description: Usa i Tag per creare una nuova suddivisione del tuo modello dei dati +draft: false +weight: 2 +exclude_search: false +audience: opensource +--- + +I Tag sono ideali per raggruppare gli oggetti in un modo che può essere filtrato in porzioni più piccole e più digeribili. Possono essere usati per indicare lo stato, o per creare insiemi personalizzati di Organizzazioni, Asset, Engagement o Riscontri in tutto il modello dei dati. + +In DefectDojo, i tag sono cittadini di prima classe e sono riconosciuti come i facilitatori +dell'organizzazione a ogni livello del modello dei dati. + +Ecco un esempio con un Asset con due tag e quattro riscontri, ciascuno con un singolo tag: + +![High level example of usage with tags](images/tags-high-level-example.png) + +### Formati dei Tag + +I tag possono essere formattati in uno dei seguenti modi: +- StringaSenzaSpazi +- stringa-con-trattini +- stringa_con_underscore +- duepunti:accettabili + +## Gestione dei Tag + +### Aggiunta e rimozione + +I tag possono essere gestiti nei seguenti modi: + +1. Creazione o modifica di nuovi oggetti + + Quando un nuovo oggetto viene creato o modificato tramite l'interfaccia utente o l'API, è presente un campo per specificare + i tag da impostare su un dato oggetto. Questo campo è un campo a selezione multipla che dispone anche di + completamento automatico per rendere semplice la ricerca e l'aggiunta di tag esistenti. Ecco come appare il campo + sull'Asset dello screenshot nella sezione precedente: + + ![Tag management on an object](images/tags-management-on-object.png) + +2. Import e Reimport + + I tag possono anche essere applicati a un dato test al momento dell'import o del reimport. Questo è un caso d'uso molto + utile quando si importa tramite API con automazione, poiché offre l'opportunità di + aggiungere dettagli sull'esecuzione automatica e informazioni sullo strumento che potrebbero non essere acquisite nel test + o nell'oggetto riscontro direttamente. + + Il campo appare e si comporta esattamente come su un dato oggetto + +3. Menu di modifica in blocco (solo Riscontri) + + Quando è necessario aggiornare molti Riscontri con lo stesso insieme di tag, si può usare il menu di modifica in blocco per + alleggerire l'onere. + + Nell'esempio seguente, supponiamo di voler aggiornare i tag dei due riscontri con il tag "tag-group-alpha" in un nuovo elenco di tag come questo ["tag-group-charlie", "tag-group-delta"]. + Per prima cosa selezionerei i tag da aggiornare: + + ![Select findings for bulk edit tag update](images/tags-select-findings-for-bulk-edit.png) + + Una volta selezionato un riscontro, appare un nuovo pulsante con il nome "Modifica in blocco". Facendo clic su questo pulsante + si apre un menu a tendina con molte opzioni, ma per ora l'attenzione è solo sui tag. Aggiorna il + campo con l'elenco di tag desiderato come segue, e fai clic su invia + + ![Apply changes for bulk edit tag update](images/tags-bulk-edit-submit.png) + + I tag sui Riscontri selezionati verranno aggiornati con quanto specificato nel campo tag + all'interno del menu di modifica in blocco + + ![Completed bulk edit tag update](images/tags-bulk-edit-complete.png) + +## Ereditarietà dei Tag + +Quando l'Ereditarietà dei Tag è abilitata, i tag applicati a un dato Asset verranno automaticamente applicati a tutti gli oggetti sotto gli Asset nella [Gerarchia degli Asset](/asset_modelling/os_hierarchy/os__asset_hierarchy/). + +### Configurazione + +L'Ereditarietà dei Tag può essere abilitata ai seguenti livelli di ambito: +- Ambito globale + - Ogni Asset a livello di sistema inizierà ad applicare i tag a tutti gli oggetti figli (Engagement, Test e Riscontri) + - Questo si imposta nelle Impostazioni di Sistema +- Ambito Asset + - Solo l'Asset selezionato inizierà ad applicare i tag a tutti gli oggetti figli (Engagement, Test e Riscontri) + - Questo si imposta nella pagina di creazione/modifica dell'Asset + +### Comportamenti + +Quando l'Ereditarietà dei Tag è abilitata, i Tag standard possono essere aggiunti e rimossi dagli oggetti nel modo consueto. +Tuttavia i tag ereditati non possono essere rimossi da un oggetto figlio senza rimuoverli dall'oggetto genitore +Vedi il seguente esempio di aggiunta di un tag "test_only_tag" all'oggetto Test e di un tag "engagement_only_tag" all'Engagement. + +![Example of inherited tags](images/tags-inherit-exmaple.png) + +Quando vengono apportati aggiornamenti all'elenco dei tag su un Asset, le stesse modifiche vengono applicate in modo asincrono a tutti gli oggetti all'interno dell'Asset. La durata di questa attività è direttamente correlata al numero di oggetti contenuti in un riscontro. + +**Open-Source:** Se le modifiche ai Tag non vengono osservate entro un periodo di tempo ragionevole, consulta i log del worker celery per identificare dove potrebbero essersi verificati eventuali problemi. + + +### Filtrare per Tag (interfaccia classica) + +I tag possono essere filtrati in molti modi sia tramite l'interfaccia utente sia tramite l'API. Ad esempio, ecco un estratto +dei filtri dei Riscontri: + +![Snippet of the finding filters](images/tags-finding-filter-snippet.png) + +Ci sono dieci campi relativi ai tag: + + - Tag: filtra su qualsiasi tag associato a un dato Riscontro + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "B" + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "F" + - Non Tag: filtra su qualsiasi tag *non* associato a un dato Riscontro + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "F" + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "B" + - Il Nome del Tag Contiene: filtra su qualsiasi tag che contenga parte o tutta la query nel dato Riscontro + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "et" (parte di "Beta") + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "meg" (parte di "Omega") + - Non Tag: filtra su qualsiasi tag che *non* contenga parte o tutta la query nel dato Riscontro + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "meg" (parte di "Omega") + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "et" (parte di "Beta") + +Per gli altri sei filtri sui tag, valgono le stesse regole di "Tag" e "Non Tag" descritte sopra, +ma a livelli diversi del modello dei dati: + + - Tag (Test): filtra su qualsiasi tag associato al Test di un dato Riscontro + - Non Tag (Test): filtra su qualsiasi tag *non* associato al Test di un dato Riscontro + - Tag (Engagement): filtra su qualsiasi tag associato all'Engagement di un dato Riscontro + - Non Tag (Engagement): filtra su qualsiasi tag *non* associato all'Engagement di un dato Riscontro + - Tag (Asset): filtra su qualsiasi tag associato all'Asset di un dato Riscontro + - Non Tag (Asset): filtra su qualsiasi tag *non* associato all'Asset di un dato Riscontro diff --git a/docs/content/asset_modelling/tags/OS__tagging_objects.pt-br.md b/docs/content/asset_modelling/tags/OS__tagging_objects.pt-br.md new file mode 100644 index 0000000000..217fc6c822 --- /dev/null +++ b/docs/content/asset_modelling/tags/OS__tagging_objects.pt-br.md @@ -0,0 +1,149 @@ +--- +title: Aplicando Tags a Objetos +description: Use Tags para criar um novo recorte do seu modelo de dados +draft: false +weight: 2 +exclude_search: false +audience: opensource +--- + +As Tags são ideais para agrupar objetos de uma forma que pode ser filtrada em partes menores e mais digeríveis. Elas podem ser usadas para indicar status ou para criar conjuntos personalizados de Organizações, Ativos, Engajamentos ou Achados em todo o modelo de dados. + +No DefectDojo, as tags são um elemento de primeira classe e são reconhecidas como facilitadoras +da organização em cada nível do modelo de dados. + +Aqui está um exemplo de um Ativo com duas tags e quatro achados, cada um com uma única tag: + +![Exemplo de alto nível do uso de tags](images/tags-high-level-example.png) + +### Formatos de Tag + +As tags podem ser formatadas de qualquer uma das seguintes maneiras: +- StringWithNoSpaces +- string-with-hyphens +- string_with_underscores +- colons:acceptable + +## Gerenciamento de Tags + +### Adicionando e Removendo + +As tags podem ser gerenciadas das seguintes formas: + +1. Criando ou Editando novos objetos + + Quando um novo objeto é criado ou editado pela UI ou pela API, há um campo para especificar + as tags a serem definidas em um determinado objeto. Esse campo é um campo de múltipla seleção que também + conta com autocompletar, tornando muito mais fácil buscar e adicionar tags existentes. Veja como o campo + aparece no Ativo do print de tela da seção anterior: + + ![Gerenciamento de tags em um objeto](images/tags-management-on-object.png) + +2. Importação e Reimportação + + As tags também podem ser aplicadas a um determinado teste no momento da importação ou reimportação. Esse é + um caso de uso muito útil ao importar via API com automação, pois oferece a oportunidade de anexar + detalhes da execução da automação e informações da ferramenta que talvez não sejam capturadas + diretamente no objeto de teste ou de achado. + + O campo tem a mesma aparência e o mesmo comportamento de quando está em um objeto qualquer + +3. Menu de Edição em Massa (somente achados) + + Quando é necessário atualizar muitos Achados com o mesmo conjunto de tags, o menu de edição em massa pode + ser usado para facilitar o trabalho. + + No exemplo a seguir, digamos que eu queira atualizar as tags dos dois achados com a tag "tag-group-alpha" para uma nova lista de tags como esta ["tag-group-charlie", "tag-group-delta"]. + Primeiro, eu selecionaria as tags a serem atualizadas: + + ![Selecionar achados para atualização de tags em massa](images/tags-select-findings-for-bulk-edit.png) + + Depois que um achado é selecionado, um novo botão aparece com o nome "Bulk Edit". Ao clicar nesse botão, + aparece um menu suspenso com várias opções, mas o foco por enquanto é apenas nas tags. Atualize o + campo com a lista de tags desejada, como a seguir, e clique em enviar + + ![Aplicar alterações da atualização de tags em massa](images/tags-bulk-edit-submit.png) + + As tags dos Achados selecionados serão atualizadas para o que foi especificado no campo de tags + dentro do menu de edição em massa + + ![Atualização de tags em massa concluída](images/tags-bulk-edit-complete.png) + +## Herança de Tags + +Quando a Herança de Tags está habilitada, as tags aplicadas a um determinado Ativo serão automaticamente aplicadas a todos os objetos abaixo dos Ativos na [Hierarquia de Ativos](/asset_modelling/os_hierarchy/os__asset_hierarchy/). + +### Configuração + +A Herança de Tags pode ser habilitada nos seguintes níveis de escopo: +- Escopo Global + - Todo Ativo em todo o sistema passará a aplicar tags a todos os objetos filhos (Engajamentos, Testes e Achados) + - Isso é definido nas Configurações do Sistema +- Escopo de Ativo + - Somente o Ativo selecionado passará a aplicar tags a todos os objetos filhos (Engajamentos, Testes e Achados) + - Isso é definido na página de criação/edição do Ativo + +### Comportamentos + +Quando a Herança de Tags está habilitada, as Tags padrão podem ser adicionadas e removidas dos objetos da forma usual. +No entanto, as tags herdadas não podem ser removidas de um objeto filho sem removê-las do objeto pai +Veja o exemplo a seguir de adição de uma tag "test_only_tag" ao objeto Teste e uma tag "engagement_only_tag" ao Engajamento. + +![Exemplo de tags herdadas](images/tags-inherit-exmaple.png) + +Quando são feitas atualizações na lista de tags de um Ativo, as mesmas alterações são aplicadas de forma assíncrona a todos os objetos dentro do Ativo. A duração dessa tarefa está diretamente relacionada à quantidade de objetos contidos em um achado. + +**Open Source:** Se as alterações de tags não forem observadas em um período de tempo razoável, consulte os logs do worker do celery para identificar onde possíveis problemas podem ter ocorrido. + + +### Filtragem por Tags (UI Clássica) + +As tags podem ser filtradas de várias formas, tanto pela UI quanto pela API. Por exemplo, aqui está um trecho +dos filtros de Achado: + +![Trecho dos filtros de achado](images/tags-finding-filter-snippet.png) + +Há dez campos relacionados a tags: + + - Tags: filtra por quaisquer tags que estejam anexadas a um determinado Achado + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta de Filtro: "B" + - O Achado *não* será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta de Filtro: "F" + - Not Tags: filtra por quaisquer tags que *não* estejam anexadas a um determinado Achado + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta de Filtro: "F" + - O Achado *não* será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta de Filtro: "B" + - Tag Name Contains: filtra por quaisquer tags que contenham parte ou toda a consulta no Achado em questão + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta de Filtro: "et" (parte de "Beta") + - O Achado *não* será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta de Filtro: "meg" (parte de "Omega") + - Not Tags: filtra por quaisquer tags que *não* contenham parte ou toda a consulta no Achado em questão + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta de Filtro: "meg" (parte de "Omega") + - O Achado *não* será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta de Filtro: "et" (parte de "Beta") + +Os outros seis filtros de tags seguem as mesmas regras que "Tags" e "Not Tags" acima, +mas em níveis diferentes do modelo de dados: + + - Tags (Teste): filtra por quaisquer tags anexadas ao Teste de um determinado Achado + - Not Tags (Teste): filtra por quaisquer tags que *não* estejam anexadas ao Teste de um determinado Achado + - Tags (Engajamento): filtra por quaisquer tags anexadas ao Engajamento de um determinado Achado + - Not Tags (Engajamento): filtra por quaisquer tags que *não* estejam anexadas ao Engajamento de um determinado Achado + - Tags (Ativo): filtra por quaisquer tags anexadas ao Ativo de um determinado Achado + - Not Tags (Ativo): filtra por quaisquer tags que *não* estejam anexadas ao Ativo de um determinado Achado diff --git a/docs/content/asset_modelling/tags/OS__tagging_objects.zh-hans.md b/docs/content/asset_modelling/tags/OS__tagging_objects.zh-hans.md new file mode 100644 index 0000000000..075e67b892 --- /dev/null +++ b/docs/content/asset_modelling/tags/OS__tagging_objects.zh-hans.md @@ -0,0 +1,135 @@ +--- +title: 为对象添加标签 +description: 使用标签为您的数据模型创建新的切分维度 +draft: false +weight: 2 +exclude_search: false +audience: opensource +--- + +标签非常适合以一种可筛选、可拆分为更小、更易理解的方式对对象进行分组。您可以使用标签来表示状态,或者跨数据模型创建自定义的组织、资产、测试活动或发现项集合。 + +在 DefectDojo 中,标签是一等对象,被视为数据模型每一层级组织方式的促成因素。 + +以下示例展示了一个带有两个标签的资产,以及四个各自带有一个标签的发现项: + +![High level example of usage with tags](images/tags-high-level-example.png) + +### 标签格式 + +标签可以采用以下任意一种格式: +- StringWithNoSpaces +- string-with-hyphens +- string_with_underscores +- colons:acceptable + +## 标签管理 + +### 添加与删除 + +标签可以通过以下几种方式进行管理: + +1. 创建或编辑新对象 + + 当通过 UI 或 API 创建或编辑新对象时,会有一个字段用于指定要为该对象设置的标签。该字段是一个多选字段,并且带有自动补全功能,可以让搜索和添加现有标签变得轻而易举。以下是上一节截图中该资产上该字段的样子: + + ![Tag management on an object](images/tags-management-on-object.png) + +2. 导入与重新导入 + + 标签也可以在导入或重新导入某个测试时应用到该测试上。当通过自动化方式经由 API 导入时,这是一个非常实用的场景,因为它提供了一个机会,可以附加那些可能不会直接体现在测试或发现项对象中的自动化运行详情和工具信息。 + + 该字段的外观和行为与其在普通对象上完全一致 + +3. 批量编辑菜单(仅限发现项) + + 当需要用同一组标签更新大量发现项时,可以使用批量编辑菜单来减轻工作负担。 + + 在下面的示例中,假设我想将带有标签"tag-group-alpha"的两个发现项的标签更新为一个新的标签列表,如["tag-group-charlie", "tag-group-delta"]。 + 首先,我会选中需要更新的发现项: + + ![Select findings for bulk edit tag update](images/tags-select-findings-for-bulk-edit.png) + + 选中某个发现项后,会出现一个名为"Bulk Edit(批量编辑)"的新按钮。点击该按钮会弹出一个包含多个选项的下拉菜单,但目前我们只关注标签部分。将该字段更新为如下所需的标签列表,然后点击提交 + + ![Apply changes for bulk edit tag update](images/tags-bulk-edit-submit.png) + + 所选发现项上的标签将被更新为批量编辑菜单中标签字段所指定的内容 + + ![Completed bulk edit tag update](images/tags-bulk-edit-complete.png) + +## 标签继承 + +启用标签继承后,应用于某个资产的标签将自动应用到[资产层级结构](/asset_modelling/os_hierarchy/os__asset_hierarchy/)中该资产下的所有对象。 + +### 配置 + +标签继承可以在以下作用域级别启用: +- 全局作用域 + - 系统范围内的每个资产都会开始将标签应用到其所有子对象(测试活动、测试和发现项) + - 该设置在系统设置中进行配置 +- 资产作用域 + - 仅所选资产会开始将标签应用到其所有子对象(测试活动、测试和发现项) + - 该设置在资产的创建/编辑页面中进行配置 + +### 行为 + +启用标签继承后,标准标签仍可以按常规方式添加到对象或从对象中删除。 +但是,继承的标签如果不从父对象中删除,就无法从子对象中删除。请参见以下示例:向测试对象添加标签"test_only_tag",向测试活动添加标签"engagement_only_tag"。 + +![Example of inherited tags](images/tags-inherit-exmaple.png) + +当资产上的标签列表发生更新时,相同的更改会异步应用到该资产内的所有对象。此任务所需的时长与发现项中所包含对象的数量直接相关。 + +**开源版:** 如果在合理的时间内没有观察到标签变更生效,请查阅 celery worker 日志以确定问题可能出现的位置。 + + +### 按标签筛选(经典界面) + +标签可以通过 UI 和 API 以多种方式进行筛选。例如,以下是发现项过滤器的一个片段: + +![Snippet of the finding filters](images/tags-finding-filter-snippet.png) + +与标签相关的字段共有十个: + + - 标签(Tags):筛选附加在给定发现项上的任意标签 + - 示例: + - 该发现项会被返回 + - 发现项标签:["A", "B", "C"] + - 筛选查询:"B" + - 该发现项*不会*被返回 + - 发现项标签:["A", "B", "C"] + - 筛选查询:"F" + - 排除标签(Not Tags):筛选*未*附加在给定发现项上的任意标签 + - 示例: + - 该发现项会被返回 + - 发现项标签:["A", "B", "C"] + - 筛选查询:"F" + - 该发现项*不会*被返回 + - 发现项标签:["A", "B", "C"] + - 筛选查询:"B" + - 标签名称包含(Tag Name Contains):筛选在给定发现项中,标签名称部分或全部包含查询内容的标签 + - 示例: + - 该发现项会被返回 + - 发现项标签:["Alpha", "Beta", "Charlie"] + - 筛选查询:"et"("Beta"的一部分) + - 该发现项*不会*被返回 + - 发现项标签:["Alpha", "Beta", "Charlie"] + - 筛选查询:"meg"("Omega"的一部分) + - 排除标签(Not Tags):筛选在给定发现项中,标签名称*不*包含部分或全部查询内容的标签 + - 示例: + - 该发现项会被返回 + - 发现项标签:["Alpha", "Beta", "Charlie"] + - 筛选查询:"meg"("Omega"的一部分) + - 该发现项*不会*被返回 + - 发现项标签:["Alpha", "Beta", "Charlie"] + - 筛选查询:"et"("Beta"的一部分) + +对于其余六个标签字段,它们遵循与上述"标签(Tags)"和"排除标签(Not Tags)"相同的规则,只是作用于数据模型中的不同层级: + + - 标签(测试)(Tags (Test)):筛选附加在给定发现项所属测试上的任意标签 + - 排除标签(测试)(Not Tags (Test)):筛选*未*附加在给定发现项所属测试上的任意标签 + - 标签(测试活动)(Tags (Engagement)):筛选附加在给定发现项所属测试活动上的任意标签 + - 排除标签(测试活动)(Not Tags (Engagement)):筛选*未*附加在给定发现项所属测试活动上的任意标签 + - 标签(资产)(Tags (Asset)):筛选附加在给定发现项所属资产上的任意标签 + - 排除标签(资产)(Not Tags (Asset)):筛选*未*附加在给定发现项所属资产上的任意标签 diff --git a/docs/content/asset_modelling/tags/PRO__tagging_objects copy.it.md b/docs/content/asset_modelling/tags/PRO__tagging_objects copy.it.md new file mode 100644 index 0000000000..cffbe20da5 --- /dev/null +++ b/docs/content/asset_modelling/tags/PRO__tagging_objects copy.it.md @@ -0,0 +1,179 @@ +--- +title: Tagging degli oggetti +description: Utilizza i Tag per creare una nuova suddivisione del tuo modello dati +draft: false +weight: 2 +exclude_search: false +audience: pro +aliases: +- /it/en/working_with_findings/organizing_engagements_tests/tagging_objects +--- + +I Tag sono ideali per raggruppare gli oggetti in un modo che consenta di filtrarli in blocchi più piccoli e gestibili. Possono essere utilizzati per indicare uno stato, oppure per creare insiemi personalizzati di Tipi di Prodotto, Prodotti, Engagement o Riscontri in tutto il modello dati. + +In DefectDojo, i Tag sono cittadini di prima classe e sono riconosciuti come i facilitatori +dell'organizzazione a ogni livello del modello dati. + +Ecco un esempio con un Prodotto con due tag e quattro riscontri, ciascuno con un singolo tag: + +![Esempio di alto livello dell'utilizzo dei tag](images/tags-high-level-example.png) + +### Formati dei Tag + +I tag possono essere formattati in uno dei seguenti modi: +- StringWithNoSpaces +- string-with-hyphens +- string_with_underscores +- colons:acceptable + +## Gestione dei Tag (UI Pro) + +### Aggiunta e rimozione + +I tag possono essere gestiti nei seguenti modi: + +1. **Creazione o modifica di nuovi oggetti** + + Quando un nuovo oggetto viene creato o modificato tramite l'interfaccia utente o l'API, è presente un campo per specificare + i tag da impostare su un determinato oggetto. + + ![tag](images/tags_product.png) + +2. **Durante l'importazione/reimportazione dei Riscontri** + + I tag sono disponibili nel modulo di importazione/reimportazione, sia nell'interfaccia utente che tramite l'API. Quando questo modulo viene inviato, al **Test** verranno assegnati i tag `[tag]` e `[daily-import]`. Se viene selezionata l'opzione "Apply Tags to Findings" o "Apply Tags to Endpoints", anche quegli oggetti verranno taggati. I tag offrono l'opportunità di aggiungere dettagli sull'esecuzione dell'automazione e informazioni sullo strumento che potrebbero non essere acquisite direttamente nell'oggetto Test o Riscontro. + + ![tag](images/tags_importscan.png) + +3. **Tramite la modifica collettiva** + + Quando vengono selezionati più Riscontri da una tabella, è possibile utilizzare il menu di modifica collettiva per modificare contemporaneamente i Tag associati a più Riscontri. Tieni presente che questa operazione sostituirà tutti i Tag a livello di Riscontro con quelli specificati; i Tag esistenti sui Riscontri verranno sovrascritti. + + ![modifica collettiva dei riscontri](images/Bulk_Editing_Findings.png) + + +## Gestione dei Tag (UI classica / Open Source) + +### Aggiunta e rimozione + +I tag possono essere gestiti nei seguenti modi: + +1. Creazione o modifica di nuovi oggetti + + Quando un nuovo oggetto viene creato o modificato tramite l'interfaccia utente o l'API, è presente un campo per specificare + i tag da impostare su un determinato oggetto. Questo campo è un campo a selezione multipla che dispone anche del + completamento automatico, per rendere semplicissima la ricerca e l'aggiunta di tag esistenti. Ecco come si presenta il campo + sul Prodotto, nella schermata della sezione precedente: + + ![Gestione dei tag su un oggetto](images/tags-management-on-object.png) + +2. Importazione e reimportazione + + I tag possono anche essere applicati a un determinato test al momento dell'importazione o della reimportazione. Questo è un + caso d'uso molto utile quando si importa tramite API con l'automazione, poiché offre l'opportunità di + aggiungere dettagli sull'esecuzione dell'automazione e informazioni sullo strumento che potrebbero non essere acquisite direttamente nell'oggetto test + o riscontro. + + Il campo ha lo stesso aspetto e lo stesso comportamento di quello presente su un determinato oggetto + +3. Menu di modifica collettiva (solo Riscontri) + + Quando è necessario aggiornare molti Riscontri con lo stesso insieme di tag, il menu di modifica collettiva può essere + utilizzato per semplificare l'operazione. + + Nell'esempio seguente, supponiamo di voler aggiornare i tag dei due riscontri con il tag "tag-group-alpha" in un nuovo elenco di tag come questo ["tag-group-charlie", "tag-group-delta"]. + Per prima cosa selezionerei i tag da aggiornare: + + ![Selezione dei riscontri per l'aggiornamento collettivo dei tag](images/tags-select-findings-for-bulk-edit.png) + + Una volta selezionato un riscontro, appare un nuovo pulsante denominato "Modifica collettiva". Facendo clic su questo pulsante + viene visualizzato un menu a tendina con molte opzioni, ma per ora ci concentriamo solo sui tag. Aggiorna il + campo con l'elenco di tag desiderato come segue, quindi fai clic su invia + + ![Applicazione delle modifiche per l'aggiornamento collettivo dei tag](images/tags-bulk-edit-submit.png) + + I tag sui Riscontri selezionati verranno aggiornati con quanto specificato nel campo dei tag + all'interno del menu di modifica collettiva + + ![Aggiornamento collettivo dei tag completato](images/tags-bulk-edit-complete.png) + +## Ereditarietà dei Tag + +**Nota sull'UI Pro: sebbene l'ereditarietà dei Tag possa essere configurata tramite l'UI Pro, i Tag ereditati possono attualmente essere consultati e filtrati solo tramite l'UI classica o l'API.** + +Quando l'Ereditarietà dei Tag è abilitata, i tag applicati a un determinato Prodotto verranno applicati automaticamente a tutti gli oggetti sottostanti ai Prodotti nella [Gerarchia dei Prodotti](/asset_modelling/os_hierarchy/product_hierarchy/). + +### Configurazione + +L'Ereditarietà dei Tag può essere abilitata ai seguenti livelli di ambito: +- Ambito globale + - Ogni Prodotto a livello di sistema inizierà ad applicare i tag a tutti gli oggetti figli (Engagement, Test e Riscontri) + - Questa impostazione si configura all'interno delle Impostazioni di sistema +- Ambito Prodotto + - Solo il Prodotto selezionato inizierà ad applicare i tag a tutti gli oggetti figli (Engagement, Test e Riscontri) + - Questa impostazione si configura nella pagina di creazione/modifica del Prodotto + +### Comportamenti + +Quando l'Ereditarietà dei Tag è abilitata, i Tag standard possono essere aggiunti e rimossi dagli oggetti nel modo consueto. +Tuttavia i tag ereditati non possono essere rimossi da un oggetto figlio senza rimuoverli dall'oggetto padre +Vedi il seguente esempio di aggiunta di un tag "test_only_tag" all'oggetto Test e di un tag "engagement_only_tag" all'Engagement. + +![Esempio di tag ereditati](images/tags-inherit-exmaple.png) + +Quando vengono apportati aggiornamenti all'elenco dei tag di un Prodotto, le stesse modifiche vengono applicate in modo asincrono a tutti gli oggetti all'interno del Prodotto. La durata di questa operazione è direttamente correlata al numero di oggetti contenuti in un riscontro. + +**Open Source:** se le modifiche ai Tag non vengono osservate entro un periodo di tempo ragionevole, consulta i log del worker celery per individuare l'origine di eventuali problemi. + + +### Filtro per Tag (UI classica) + +I tag possono essere filtrati in molti modi, sia tramite l'interfaccia utente che tramite l'API. Ad esempio, ecco un estratto +dei filtri dei Riscontri: + +![Estratto dei filtri dei riscontri](images/tags-finding-filter-snippet.png) + +Sono presenti dieci campi relativi ai tag: + + - Tag: filtra in base a qualsiasi tag associato a un determinato Riscontro + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "B" + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "F" + - Non Tag: filtra in base a qualsiasi tag *non* associato a un determinato Riscontro + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "F" + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["A", "B", "C"] + - Query di filtro: "B" + - Il nome del Tag contiene: filtra in base a qualsiasi tag che contenga in parte o interamente la query nel Riscontro indicato + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "et" (parte di "Beta") + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "meg" (parte di "Omega") + - Non Tag: filtra in base a qualsiasi tag che *non* contenga in parte o interamente la query nel Riscontro indicato + - Esempi: + - Il Riscontro verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "meg" (parte di "Omega") + - Il Riscontro *non* verrà restituito + - Tag del Riscontro: ["Alpha", "Beta", "Charlie"] + - Query di filtro: "et" (parte di "Beta") + +Per gli altri sei filtri di tag, valgono le stesse regole di "Tag" e "Non Tag" descritte sopra, +ma a livelli diversi del modello dati: + + - Tag (Test): filtra in base a qualsiasi tag associato al Test di un determinato Riscontro + - Non Tag (Test): filtra in base a qualsiasi tag *non* associato al Test di un determinato Riscontro + - Tag (Engagement): filtra in base a qualsiasi tag associato all'Engagement di un determinato Riscontro + - Non Tag (Engagement): filtra in base a qualsiasi tag *non* associato all'Engagement di un determinato Riscontro + - Tag (Prodotto): filtra in base a qualsiasi tag associato al Prodotto di un determinato Riscontro + - Non Tag (Prodotto): filtra in base a qualsiasi tag *non* associato al Prodotto di un determinato Riscontro diff --git a/docs/content/asset_modelling/tags/PRO__tagging_objects copy.pt-br.md b/docs/content/asset_modelling/tags/PRO__tagging_objects copy.pt-br.md new file mode 100644 index 0000000000..7b970ce8ea --- /dev/null +++ b/docs/content/asset_modelling/tags/PRO__tagging_objects copy.pt-br.md @@ -0,0 +1,179 @@ +--- +title: Marcação de Objetos +description: Use Tags para criar um novo recorte do seu modelo de dados +draft: false +weight: 2 +exclude_search: false +audience: pro +aliases: +- /pt-br/en/working_with_findings/organizing_engagements_tests/tagging_objects +--- + +Tags são ideais para agrupar objetos de forma que possam ser filtrados em blocos menores e mais fáceis de analisar. Podem ser usadas para indicar status ou para criar conjuntos personalizados de Tipo de Produto, Produtos, Engajamentos ou Achados em todo o modelo de dados. + +No DefectDojo, as tags são um cidadão de primeira classe e são reconhecidas como as facilitadoras +da organização em cada nível do modelo de dados. + +Aqui está um exemplo com um Produto com duas tags e quatro achados, cada um com uma única tag: + +![High level example of usage with tags](images/tags-high-level-example.png) + +### Formatos de Tag + +As tags podem ser formatadas de qualquer uma das seguintes maneiras: +- StringWithNoSpaces +- string-with-hyphens +- string_with_underscores +- colons:acceptable + +## Gerenciamento de Tags (Pro UI) + +### Adicionando e Removendo + +As tags podem ser gerenciadas das seguintes formas: + +1. **Criando ou Editando novos objetos** + + Quando um novo objeto é criado ou editado pela UI ou pela API, há um campo para especificar + as tags a serem definidas em um determinado objeto. + + ![tag](images/tags_product.png) + +2. **Ao Importar/Reimportar Achados** + + As tags estão disponíveis no formulário de Importação/Reimportação, tanto na UI quanto via API. Quando esse formulário é enviado, o **Teste** será marcado com `[tag]` e `[daily-import]`. Se "Apply Tags to Findings" ou "Apply Tags to Endpoints" estiver selecionado, esses objetos também serão marcados. As tags oferecem a oportunidade de anexar detalhes de execução de automação e informações da ferramenta que talvez não sejam capturadas diretamente no objeto Teste ou Achado. + + ![tag](images/tags_importscan.png) + +3. **Via Edição em Massa** + + Quando muitos Achados são selecionados em uma tabela, você pode usar o menu de Edição em Massa para alterar as Tags associadas a vários Achados simultaneamente. Observe que isso substituirá todas as Tags no nível do Achado pelas Tags especificadas; as Tags existentes do Achado serão sobrescritas. + + ![bulk editing findings](images/Bulk_Editing_Findings.png) + + +## Gerenciamento de Tags (Classic UI / OpenSource) + +### Adicionando e Removendo + +As tags podem ser gerenciadas das seguintes formas: + +1. Criando ou Editando novos objetos + + Quando um novo objeto é criado ou editado pela UI ou pela API, há um campo para especificar + as tags a serem definidas em um determinado objeto. Esse campo é um campo de seleção múltipla que também conta com + preenchimento automático, tornando fácil buscar e adicionar tags existentes. Veja como o campo + se parece no Produto a partir da captura de tela da seção anterior: + + ![Tag management on an object](images/tags-management-on-object.png) + +2. Importar e Reimportar + + As tags também podem ser aplicadas a um determinado teste no momento da importação ou reimportação. Esse é um caso de uso muito + útil ao importar via API com automação, pois oferece a oportunidade de + anexar detalhes de execução de automação e informações da ferramenta que talvez não sejam capturadas diretamente no objeto teste + ou achado. + + O campo se parece e se comporta exatamente como em um determinado objeto + +3. Menu de Edição em Massa (apenas Achados) + + Quando é necessário atualizar muitos Achados com o mesmo conjunto de tags, o menu de edição em massa pode ser + usado para facilitar essa tarefa. + + No exemplo a seguir, digamos que eu queira atualizar as tags dos dois achados com a tag "tag-group-alpha" para uma nova lista de tags como esta ["tag-group-charlie", "tag-group-delta"]. + Primeiro eu selecionaria as tags a serem atualizadas: + + ![Select findings for bulk edit tag update](images/tags-select-findings-for-bulk-edit.png) + + Uma vez selecionado um achado, um novo botão aparece com o nome "Bulk Edit". Clicar nesse botão + exibe um menu suspenso com muitas opções, mas por enquanto o foco é apenas nas tags. Atualize o + campo com a lista de tags desejada, conforme a seguir, e clique em enviar + + ![Apply changes for bulk edit tag update](images/tags-bulk-edit-submit.png) + + As tags nos Achados selecionados serão atualizadas para o que foi especificado no campo de tags + dentro do menu de edição em massa + + ![Completed bulk edit tag update](images/tags-bulk-edit-complete.png) + +## Herança de Tags + +**Nota da Pro UI: embora a herança de Tags possa ser configurada usando a Pro UI, as Tags herdadas atualmente só podem ser acessadas e filtradas pela Classic UI ou pela API.** + +Quando a Herança de Tags está habilitada, as tags aplicadas a um determinado Produto serão automaticamente aplicadas a todos os objetos abaixo de Produtos na [Hierarquia de Produtos](/asset_modelling/os_hierarchy/product_hierarchy/). + +### Configuração + +A Herança de Tags pode ser habilitada nos seguintes níveis de escopo: +- Escopo Global + - Todo Produto do sistema passará a aplicar tags a todos os objetos filhos (Engajamentos, Testes e Achados) + - Isso é definido nas Configurações do Sistema +- Escopo de Produto + - Apenas o Produto selecionado passará a aplicar tags a todos os objetos filhos (Engajamentos, Testes e Achados) + - Isso é definido na página de criação/edição do Produto + +### Comportamentos + +Quando a Herança de Tags está habilitada, as Tags padrão podem ser adicionadas e removidas dos objetos da forma usual. +No entanto, as tags herdadas não podem ser removidas de um objeto filho sem removê-las do objeto pai +Veja o exemplo a seguir de adição de uma tag "test_only_tag" ao objeto Teste e de uma tag "engagement_only_tag" ao Engajamento. + +![Example of inherited tags](images/tags-inherit-exmaple.png) + +Quando são feitas atualizações na lista de tags de um Produto, as mesmas alterações são feitas de forma assíncrona em todos os objetos dentro do Produto. A duração dessa tarefa está diretamente relacionada ao número de objetos contidos em um achado. + +**Open-Source:** Se as alterações de Tag não forem observadas dentro de um período razoável, consulte os logs do celery worker para identificar onde possam ter surgido problemas. + + +### Filtrando por Tags (Classic UI) + +As tags podem ser filtradas de várias maneiras, tanto pela UI quanto pela API. Por exemplo, aqui está um trecho +dos filtros de Achado: + +![Snippet of the finding filters](images/tags-finding-filter-snippet.png) + +Existem dez campos relacionados a tags: + + - Tags: filtra por quaisquer tags que estejam anexadas a um determinado Achado + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta do Filtro: "B" + - O Achado *não* será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta do Filtro: "F" + - Not Tags: filtra por quaisquer tags que *não* estejam anexadas a um determinado Achado + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta do Filtro: "F" + - O Achado *não* será retornado + - Tags do Achado: ["A", "B", "C"] + - Consulta do Filtro: "B" + - Tag Name Contains: filtra por quaisquer tags que contenham parte ou a totalidade da consulta no Achado em questão + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta do Filtro: "et" (parte de "Beta") + - O Achado *não* será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta do Filtro: "meg" (parte de "Omega") + - Not Tags: filtra por quaisquer tags que *não* contenham parte ou a totalidade da consulta no Achado em questão + - Exemplos: + - O Achado será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta do Filtro: "meg" (parte de "Omega") + - O Achado *não* será retornado + - Tags do Achado: ["Alpha", "Beta", "Charlie"] + - Consulta do Filtro: "et" (parte de "Beta") + +Quanto aos outros seis filtros de tag, eles seguem as mesmas regras de "Tags" e "Not Tags" como acima, +mas em níveis diferentes do modelo de dados: + + - Tags (Test): filtra por quaisquer tags que estejam anexadas ao Teste de um determinado Achado + - Not Tags (Test): filtra por quaisquer tags que *não* estejam anexadas ao Teste de um determinado Achado + - Tags (Engagement): filtra por quaisquer tags que estejam anexadas ao Engajamento de um determinado Achado + - Not Tags (Engagement): filtra por quaisquer tags que *não* estejam anexadas ao Engajamento de um determinado Achado + - Tags (Product): filtra por quaisquer tags que estejam anexadas ao Produto de um determinado Achado + - Not Tags (Product): filtra por quaisquer tags que *não* estejam anexadas ao Produto de um determinado Achado diff --git a/docs/content/asset_modelling/tags/PRO__tagging_objects copy.zh-hans.md b/docs/content/asset_modelling/tags/PRO__tagging_objects copy.zh-hans.md new file mode 100644 index 0000000000..eda64bc505 --- /dev/null +++ b/docs/content/asset_modelling/tags/PRO__tagging_objects copy.zh-hans.md @@ -0,0 +1,165 @@ +--- +title: 为对象打标签 +description: 使用标签为您的数据模型创建新的切片 +draft: false +weight: 2 +exclude_search: false +audience: pro +aliases: +- /zh-hans/en/working_with_findings/organizing_engagements_tests/tagging_objects +--- + +标签非常适合以可筛选的方式对对象进行分组,将其拆分为更小、更易于理解的片段。它们可用于标注状态,也可用于在整个数据模型中创建产品类型、产品、测试活动或发现项的自定义集合。 + +在 DefectDojo 中,标签是一等公民,被视为数据模型每个层级中组织管理的推动者。 + +以下示例展示了一个具有两个标签的产品,以及四个各带一个标签的发现项: + +![标签用法的高层示例](images/tags-high-level-example.png) + +### 标签格式 + +标签可以采用以下任意一种格式: +- StringWithNoSpaces(无空格字符串) +- string-with-hyphens(带连字符的字符串) +- string_with_underscores(带下划线的字符串) +- colons:acceptable(可包含冒号) + +## 标签管理(Pro 界面) + +### 添加和移除 + +标签可以通过以下方式进行管理: + +1. **创建或编辑新对象** + + 当通过界面或 API 创建或编辑新对象时,会有一个字段用于指定要为该对象设置的标签。 + + ![标签](images/tags_product.png) + +2. **在导入/重新导入发现项时** + + 导入/重新导入表单(无论是在界面中还是通过 API)都提供标签字段。提交该表单后,**测试**将被标记为 `[tag]` 和 `[daily-import]`。如果选中了“将标签应用于发现项”或“将标签应用于端点”,这些对象也会被打上标签。标签为附加自动化运行详情和工具信息提供了机会,而这些信息可能不会被直接记录在测试或发现项对象中。 + + ![标签](images/tags_importscan.png) + +3. **通过批量编辑** + + 当从表格中选中多个发现项时,您可以使用批量编辑菜单同时更改多个发现项关联的标签。请注意,这会将所有发现项级别的标签替换为指定的标签;现有的发现项标签将被覆盖。 + + ![批量编辑发现项](images/Bulk_Editing_Findings.png) + + +## 标签管理(经典界面 / 开源版) + +### 添加和移除 + +标签可以通过以下方式进行管理: + +1. 创建或编辑新对象 + + 当通过界面或 API 创建或编辑新对象时,会有一个字段用于指定要为该对象设置的标签。该字段是一个多选字段,还具备自动补全功能,使搜索和添加现有标签变得轻而易举。以下是上一节截图中产品上该字段的样子: + + ![对象上的标签管理](images/tags-management-on-object.png) + +2. 导入和重新导入 + + 标签也可以在导入或重新导入时应用于给定测试。当通过自动化方式经由 API 导入时,这是一个非常实用的场景,因为它提供了附加自动化运行详情和工具信息的机会,而这些信息可能不会被直接记录在测试或发现项对象中。 + + 该字段的外观和行为与对象上的字段完全相同 + +3. 批量编辑菜单(仅限发现项) + + 当需要为多个发现项更新同一组标签时,可以使用批量编辑菜单来减轻工作量。 + + 在以下示例中,假设我想将两个带有标签“tag-group-alpha”的发现项的标签更新为新的标签列表 ["tag-group-charlie", "tag-group-delta"]。 + 首先,我会选择要更新的标签: + + ![选择要批量编辑标签的发现项](images/tags-select-findings-for-bulk-edit.png) + + 选中某个发现项后,会出现一个名为“批量编辑”的新按钮。点击该按钮会弹出一个包含多个选项的下拉菜单,但目前只关注标签。将该字段更新为所需的标签列表,如下所示,然后点击提交 + + ![应用批量编辑标签更新的更改](images/tags-bulk-edit-submit.png) + + 所选发现项上的标签将被更新为批量编辑菜单中标签字段所指定的内容 + + ![完成的批量编辑标签更新](images/tags-bulk-edit-complete.png) + +## 标签继承 + +**Pro 界面说明:虽然可以通过 Pro 界面配置标签继承,但目前继承的标签只能通过经典界面或 API 进行访问和筛选。** + +当启用标签继承后,应用于某个产品的标签将自动应用于[产品层级结构](/asset_modelling/os_hierarchy/product_hierarchy/)中该产品下的所有对象。 + +### 配置 + +标签继承可以在以下范围级别启用: +- 全局范围 + - 系统范围内的每个产品都将开始把标签应用于其所有子对象(测试活动、测试和发现项) + - 该设置位于系统设置中 +- 产品范围 + - 只有所选产品会开始把标签应用于其所有子对象(测试活动、测试和发现项) + - 该设置位于产品创建/编辑页面 + +### 行为 + +启用标签继承后,标准标签仍可以按照常规方式添加到对象或从对象中移除。 +但是,继承的标签如果不从父对象中移除,就无法从子对象中移除。 +请参见以下示例:向测试对象添加标签“test_only_tag”,向测试活动添加标签“engagement_only_tag”。 + +![继承标签示例](images/tags-inherit-exmaple.png) + +当对产品上的标签列表进行更新时,产品内的所有对象都会异步进行相同的更改。此任务耗时的长短与发现项中包含的对象数量直接相关。 + +**开源版:** 如果在合理的时间内没有观察到标签变更,请查阅 celery worker 日志以确定可能出现问题的位置。 + + +### 按标签筛选(经典界面) + +可以通过界面和 API 以多种方式筛选标签。例如,以下是发现项筛选器的一个片段: + +![发现项筛选器片段](images/tags-finding-filter-snippet.png) + +有十个与标签相关的字段: + + - 标签(Tags):筛选附加在给定发现项上的任意标签 + - 示例: + - 将返回该发现项 + - 发现项标签: ["A", "B", "C"] + - 筛选查询: "B" + - *不会*返回该发现项 + - 发现项标签: ["A", "B", "C"] + - 筛选查询: "F" + - 排除标签(Not Tags):筛选*未*附加在给定发现项上的任意标签 + - 示例: + - 将返回该发现项 + - 发现项标签: ["A", "B", "C"] + - 筛选查询: "F" + - *不会*返回该发现项 + - 发现项标签: ["A", "B", "C"] + - 筛选查询: "B" + - 标签名称包含(Tag Name Contains):筛选在给定发现项中标签名称包含部分或全部查询内容的标签 + - 示例: + - 将返回该发现项 + - 发现项标签: ["Alpha", "Beta", "Charlie"] + - 筛选查询: "et"(“Beta”的一部分) + - *不会*返回该发现项 + - 发现项标签: ["Alpha", "Beta", "Charlie"] + - 筛选查询: "meg"(“Omega”的一部分) + - 排除标签(Not Tags):筛选在给定发现项中标签名称*不*包含部分或全部查询内容的标签 + - 示例: + - 将返回该发现项 + - 发现项标签: ["Alpha", "Beta", "Charlie"] + - 筛选查询: "meg"(“Omega”的一部分) + - *不会*返回该发现项 + - 发现项标签: ["Alpha", "Beta", "Charlie"] + - 筛选查询: "et"(“Beta”的一部分) + +对于其余六个标签筛选器,它们遵循与上述“标签”和“排除标签”相同的规则,只是作用于数据模型中的不同层级: + + - 标签(测试):筛选附加在给定发现项所属测试上的任意标签 + - 排除标签(测试):筛选*未*附加在给定发现项所属测试上的任意标签 + - 标签(测试活动):筛选附加在给定发现项所属测试活动上的任意标签 + - 排除标签(测试活动):筛选*未*附加在给定发现项所属测试活动上的任意标签 + - 标签(产品):筛选附加在给定发现项所属产品上的任意标签 + - 排除标签(产品):筛选*未*附加在给定发现项所属产品上的任意标签 diff --git a/docs/content/asset_modelling/tags/_index.it.md b/docs/content/asset_modelling/tags/_index.it.md new file mode 100644 index 0000000000..a3257755c8 --- /dev/null +++ b/docs/content/asset_modelling/tags/_index.it.md @@ -0,0 +1,8 @@ +--- +title: Tag +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +--- diff --git a/docs/content/asset_modelling/tags/_index.pt-br.md b/docs/content/asset_modelling/tags/_index.pt-br.md new file mode 100644 index 0000000000..e14bb290d3 --- /dev/null +++ b/docs/content/asset_modelling/tags/_index.pt-br.md @@ -0,0 +1,8 @@ +--- +title: Tags +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +--- diff --git a/docs/content/asset_modelling/tags/_index.zh-hans.md b/docs/content/asset_modelling/tags/_index.zh-hans.md new file mode 100644 index 0000000000..8fc251f31b --- /dev/null +++ b/docs/content/asset_modelling/tags/_index.zh-hans.md @@ -0,0 +1,8 @@ +--- +title: 标签 +date: 2021-02-02 20:46:29+01:00 +draft: false +type: docs +weight: 1 +exclude_search: true +--- diff --git a/docs/content/automation/api/_index.it.md b/docs/content/automation/api/_index.it.md new file mode 100644 index 0000000000..ad87ca3e1f --- /dev/null +++ b/docs/content/automation/api/_index.it.md @@ -0,0 +1,16 @@ +--- +title: Automazione +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 98 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- diff --git a/docs/content/automation/api/_index.pt-br.md b/docs/content/automation/api/_index.pt-br.md new file mode 100644 index 0000000000..b72c2b4d9e --- /dev/null +++ b/docs/content/automation/api/_index.pt-br.md @@ -0,0 +1,16 @@ +--- +title: Automação +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 98 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- diff --git a/docs/content/automation/api/_index.zh-hans.md b/docs/content/automation/api/_index.zh-hans.md new file mode 100644 index 0000000000..e7bc6da008 --- /dev/null +++ b/docs/content/automation/api/_index.zh-hans.md @@ -0,0 +1,16 @@ +--- +title: 自动化 +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 98 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +--- diff --git a/docs/content/automation/api/api-v2-docs.it.md b/docs/content/automation/api/api-v2-docs.it.md new file mode 100644 index 0000000000..9130171afa --- /dev/null +++ b/docs/content/automation/api/api-v2-docs.it.md @@ -0,0 +1,419 @@ +--- +title: API DefectDojo v2 +description: L'API di DefectDojo consente di automatizzare le attività, ad es. il + caricamento dei report di scansione nelle pipeline CI/CD. +draft: false +weight: 2 +aliases: +- /it/en/api/api-v2-docs +--- + +L'API di DefectDojo è creata utilizzando [Django Rest +Framework](http://www.django-rest-framework.org/). La documentazione di +ogni endpoint è disponibile in ogni installazione di DefectDojo su +[`/api/v2/oa3/swagger-ui`](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) ed è accessibile selezionando il link API v2 +Docs nel menu a tendina dell'utente nell'intestazione. + +![image](images/api_v2_1.png) + +La documentazione è generata utilizzando [drf-spectacular](https://drf-spectacular.readthedocs.io/) su [`/api/v2/oa3/swagger-ui/`](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/), ed è +interattiva. Nella parte superiore della documentazione API v2 è presente un link che genera una specifica OpenAPI v3. + +Per interagire con la documentazione, è necessario un valore valido dell'header Authorization. +Visita la vista `/api/key-v2` per generare la tua +API Key (`Token `) e copia il valore dell'header fornito. + +![image](images/api_v2_2.png) + +Ogni sezione consente di effettuare chiamate all'API e visualizzare la Request +URL, il Response Body, il Response Code e i Response Headers. + +![image](images/api_v2_3.png) + +Se hai effettuato l'accesso alla web UI di Defect Dojo, non è necessario fornire il token di autorizzazione. + +## Autenticazione + +L'API utilizza l'autenticazione tramite header con API key. Il formato dell' +header dovrebbe essere: : + + Authorization: Token + +Ad esempio: : + + Authorization: Token c8572a5adf107a693aa6c72584da31f4d1f1dcff + +### Metodo di autenticazione alternativo + +Se utilizzi [un metodo di autenticazione alternativo](/admin/sso/) per gli utenti, potresti voler disabilitare i token API di DefectDojo perché potrebbero aggirare il tuo sistema di autenticazione. +L'uso dei token API di DefectDojo può essere disabilitato impostando la variabile d'ambiente `DD_API_TOKENS_ENABLED` su `False`. +Oppure è possibile disabilitare solo l'endpoint `api/v2/api-token-auth/` impostando `DD_API_TOKEN_AUTH_ENDPOINT_ENABLED` su `False`. + +## Codice di esempio + +Ecco alcuni semplici esempi in python e i loro risultati prodotti contro +l'endpoint `/users`: : + +{{< highlight python >}} +import requests + +url = 'http://127.0.0.1:8000/api/v2/users' +headers = {'content-type': 'application/json', + 'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'} +r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed + +for key, value in r.__dict__.items(): + print(f"'{key}': '{value}'") + print('------------------') +{{< /highlight >}} + +Questo codice restituirà l'elenco di tutti gli utenti definiti in DefectDojo. +Il risultato dell'oggetto json è simile a questo: : + +{{< highlight json >}} + [ + { + "first_name": "Tyagi", + "id": 22, + "last_login": "2019-06-18T08:05:51.925743", + "last_name": "Paz", + "username": "dev7958" + }, + { + "first_name": "saurabh", + "id": 31, + "last_login": "2019-06-06T11:44:32.533035", + "last_name": "", + "username": "saurabh.paz" + } + ] +{{< /highlight >}} + +Ecco un altro esempio contro l'endpoint `/users`, questa +volta filtreremo i risultati per includere solo gli utenti il cui nome +utente include `jay`: + +{{< highlight python >}} +import requests + +url = 'http://127.0.0.1:8000/api/v2/users/?username__contains=jay' +headers = {'content-type': 'application/json', + 'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'} +r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed + +for key, value in r.__dict__.items(): + print(f"'{key}': '{value}'") + print('------------------') +{{< /highlight >}} + +Il risultato dell'oggetto json è: : + +{{< highlight json >}} +[ + { + "first_name": "Jay", + "id": 22, + "last_login": "2015-10-28T08:05:51.925743", + "last_name": "Paz", + "username": "jay7958" + }, + { + "first_name": "", + "id": 31, + "last_login": "2015-10-13T11:44:32.533035", + "last_name": "", + "username": "jay.paz" + } +] +{{< /highlight >}} + +Consulta la [documentazione di Django Rest Framework +sull'interazione con un'API](https://www.django-rest-framework.org/) per +ulteriori esempi e suggerimenti. + +## Chiamare manualmente l'API + +Strumenti come Postman possono essere utilizzati per testare l'API. + +Esempio per l'importazione di un risultato di scansione: + +- Verbo: POST +- URI: +- Scheda Headers: + + aggiungi l'header di autenticazione + : - Key: Authorization + - Value: Token c8572a5adf107a693aa6c72584da31f4d1f1dcff + +- Scheda Body + + - seleziona "form-data", clicca su "bulk edit". Esempio per una scansione ZAP: + + + + engagement:3 + verified:true + active:true + lead:1 + tags:test + scan_type:ZAP Scan + minimum_severity:Info + close_old_findings:false + +- Scheda Body + + - Clicca sulla modalità "Key-value" + - Aggiungi un parametro "file" di tipo "file". Questo attiverà + i dati multi-part form per l'invio del contenuto del file + - Sfoglia per trovare il file da caricare + +- Clicca su invia + +## Client / Wrapper API + +| Wrapper | Stato | Note | +| -----------------------------| ------------------------| ------------------------| +| [Wrapper python specifico](https://github.com/DefectDojo/defectdojo_api) | funzionante (2021-01-21) | Wrapper API che include script per il caricamento continuo CI/CD. È leggermente indietro rispetto alle ultime funzionalità dell'API poiché prevediamo di rinnovare il wrapper API | +| [Wrapper python Openapi](https://github.com/alles-klar/defectdojo-api-v2-client) | | solo proof of concept, dove abbiamo scoperto che la specifica OpenAPI non è ancora perfetta | +| [Libreria Java](https://github.com/secureCodeBox/defectdojo-client-java) | funzionante (2021-08-30) | Creata dalle gentili persone di [SecureCodeBox](https://github.com/secureCodeBox/secureCodeBox) | +| [Immagine che utilizza la libreria Java](https://github.com/SDA-SE/defectdojo-client) | funzionante (2021-08-30) | | +| [Libreria .Net/C#](https://www.nuget.org/packages/DefectDojo.Api/) | funzionante (2021-06-08) | | +| [dd-import](https://github.com/MaibornWolff/dd-import) | funzionante (2021-08-24) | dd-import non è direttamente un wrapper API. Offre alcune funzioni di comodità per semplificare l'importazione di riscontri e dati sui linguaggi dalle pipeline CI/CD. | + +Alcuni dei wrapper API contengono una discreta quantità di logica per facilitare la scansione e l'importazione negli ambienti CI/CD. Siamo nel processo di semplificare questo aspetto rendendo l'API di DefectDojo più intelligente (in modo che i wrapper/script API possano essere più semplici). + +## Note sull'API + +### Importazione / Reimportazione + +**Reimport** è in realtà il modo più semplice per iniziare, poiché creerà al volo qualsiasi entità se necessario e rileverà automaticamente se si tratta di un primo caricamento o di un nuovo caricamento. + +## Importazione +L'importazione tramite API viene eseguita tramite l'endpoint [import-scan](https://demo.defectdojo.org/api/v2/doc/). + +Come descritto in [Gerarchia dei Prodotti](/asset_modelling/os_hierarchy/product_hierarchy/), il Test viene creato all'interno di un Engagement, all'interno di un Prodotto, all'interno di un Product Type. + +Un'importazione può essere eseguita specificando i nomi di queste entità nella richiesta API: + + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "product_type_name": 'Good Products', + "product_name": 'My little product', + "engagement_name": 'Important import', + "auto_create_context": True, +} +``` + +Quando `auto_create_context` è `True`, il prodotto, l'engagement e l'ambiente verranno creati se necessario. Assicurati che il tuo utente disponga di [permessi](/admin/user_management/about_perms_and_roles/) sufficienti per farlo. + +Un modo classico per importare una scansione è specificare invece l'ID dell'engagement: + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "engagement": 123, +} +``` + +## Reimportazione +La reimportazione tramite API viene eseguita tramite l'endpoint [reimport-scan](https://demo.defectdojo.org/api/v2/doc/). + +Una reimportazione può essere eseguita specificando i nomi di queste entità nella richiesta API: + + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "product_type_name": 'Good Products', + "product_name": 'My little product', + "engagement_name": 'Important import', + "auto_create_context": True, + "do_not_reactivate": False, +} +``` + +Quando `auto_create_context` è `True`, il Product Type, il Prodotto e l'Engagement verranno creati se non esistono già. Assicurati che il tuo utente disponga di [permessi](/admin/user_management/about_perms_and_roles/) sufficienti per creare un Prodotto/Product Type. + +Quando `do_not_reactivate` è `True`, l'importazione/reimportazione ignorerà i riscontri attivi caricati e non riattiverà i riscontri precedentemente chiusi, pur creando comunque nuovi riscontri se ce ne sono di nuovi. Riceverai una nota sul riscontro per spiegare che non è stato riattivato per questo motivo. + +Una reimportazione selezionerà automaticamente l'ultimo test all'interno dell'engagement fornito che soddisfa lo `scan_type` fornito e (facoltativamente) il `test_title` fornito. + +Se non viene trovato alcun Test esistente, l'endpoint di reimportazione utilizzerà la funzione di importazione per importare il report fornito in un nuovo Test. Questo significa che uno script (CI/CD) che utilizza l'API non ha bisogno di sapere se un Test esiste già, o se si tratta di un primo caricamento per questo Prodotto / Engagement. + +Un modo classico per reimportare una scansione è specificare invece l'ID del test: + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test": 123, +} +``` + +## Generazione dei Report + +DefectDojo può generare un report dei riscontri tramite l'API nei formati **JSON**, **HTML**, **CSV** o **Excel**. + +Un report viene generato con una richiesta `POST` a un'azione `generate_report/`. L'endpoint findings genera report sull'intera istanza, e la maggior parte degli altri oggetti espone un'azione per\-oggetto: + +| Endpoint | Ambito | +|---|---| +| `POST /api/v2/findings/generate_report/` | Ogni riscontro che hai il permesso di visualizzare | +| `POST /api/v2/products/{id}/generate_report/` | Un prodotto | +| `POST /api/v2/engagements/{id}/generate_report/` | Un engagement | +| `POST /api/v2/tests/{id}/generate_report/` | Un test | +| `POST /api/v2/product_types/{id}/generate_report/` | Un product type | +| `POST /api/v2/endpoints/{id}/generate_report/` | Un endpoint | + +Gli alias degli oggetti Pro espongono la stessa azione: `/api/v2/assets/{id}/generate_report/`, `/api/v2/organizations/{id}/generate_report/` e `/api/v2/location/{id}/generate_report/`. + +### Opzioni della richiesta + +Tutti i campi sono opzionali — inviare un corpo vuoto (`{}`) restituisce un report JSON. + +| Campo | Tipo | Predefinito | Descrizione | +|---|---|---|---| +| `report_type` | string | `JSON` | Uno tra `JSON`, `HTML`, `CSV`, `Excel`. | +| `include_finding_notes` | boolean | `false` | Include le note di ogni riscontro. | +| `include_finding_images` | boolean | `false` | Include le immagini allegate ai riscontri. | +| `include_executive_summary` | boolean | `false` | Include una sezione di riepilogo esecutivo. | +| `include_table_of_contents` | boolean | `false` | Include un indice. | + +Un `report_type` non supportato (ad esempio `PDF`) restituisce `400 Bad Request` con un errore sul campo `report_type`. + +### Esempio + +Genera un report CSV di tutti i riscontri che puoi visualizzare e salvalo in un file: + +```bash +curl -X POST \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{"report_type": "CSV"}' \ + https:///api/v2/findings/generate_report/ \ + -o findings.csv +``` + +### Formati di risposta + +| `report_type` | Content type | Risposta | +|---|---|---| +| `JSON` (predefinito) | `application/json` | Corpo del report nella risposta | +| `HTML` | `text/html` | Pagina del report renderizzata | +| `CSV` | `text/csv` | Allegato file | +| `Excel` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Allegato file `.xlsx` | + +CSV ed Excel vengono restituiti come allegati file con un header `Content-Disposition` anziché come corpo JSON. Il nome del file viene ricavato dall'oggetto da cui è stato generato il report — ad esempio `product_1_findings.csv` o `test_42_findings.xlsx`. L'endpoint `/findings/generate_report/` non è associato a un singolo oggetto, quindi i suoi download sono chiamati `findings.csv` e `findings.xlsx`. + +### Note e limitazioni + +* Le opzioni `include_*` influiscono solo sui report **JSON** e **HTML**. Le esportazioni **CSV** ed **Excel** contengono sempre le righe dei riscontri. +* La generazione dei report richiede il permesso di **visualizzazione** sugli oggetti coinvolti, e un report contiene sempre e solo i riscontri che sei autorizzato a vedere. +* **I filtri standard tramite parametri di query non vengono applicati a questa azione.** A differenza di `GET /api/v2/findings/`, l'azione `generate_report/` non applica i filtri dei riscontri, quindi una richiesta come `POST /api/v2/findings/generate_report/?severity=High` genererà comunque un report su tutti i riscontri che puoi visualizzare. Per restringere un report, generalo invece da un prodotto, engagement o test specifico. + +## Comportamento di eliminazione asincrona + +Le eliminazioni in DefectDojo (sia tramite API che UI) vengono elaborate in modo **asincrono** dai worker in background di Celery. Quando elimini un Engagement, un Test o un altro oggetto, l'API o la UI restituiscono immediatamente una risposta di successo, ma l'eliminazione effettiva viene eseguita in background. + +Questo significa che: +- Gli oggetti potrebbero continuare ad apparire nelle query per un certo periodo di tempo dopo che l'eliminazione è stata confermata. +- Le eliminazioni a cascata (ad es. l'eliminazione di un Engagement elimina anche i suoi Test e Riscontri) vengono elaborate come una catena di attività in background. Gli oggetti figli vengono rimossi in ordine di dipendenza: prima i Riscontri, poi i Test, poi gli Engagement. +- Per Engagement di grandi dimensioni con molti Riscontri, questo processo può richiedere diversi minuti per completarsi. + +Non è necessario creare script personalizzati per eliminare gli oggetti in ordine di dipendenza. Una singola richiesta `DELETE` su un Engagement si propagherà automaticamente a cascata su tutti gli oggetti figli. Basta lasciare il tempo necessario alle attività in background per completarsi. + +## Limiti di paginazione dell'API + +DefectDojo Pro impone una dimensione massima della pagina di **250** risultati per richiesta API. Impostare `limit` a un valore superiore a 250 può causare errori HTTP 502 dovuti a timeout delle query. + +Le istanze Open Source di DefectDojo possono anch'esse riscontrare timeout con dimensioni di pagina molto grandi, a seconda delle dimensioni del dataset e delle risorse del server. + +Per set di risultati di grandi dimensioni, utilizza la paginazione con una dimensione di pagina compresa tra 50 e 250 e aggiungi brevi ritardi tra le richieste paginate per evitare di saturare il pool di worker. + +## Best practice per l'importazione su larga scala + +Quando importi risultati di scansione su larga scala (ad es. pipeline SBOM con migliaia di componenti), considera quanto segue: + +- **Usa `background_import=true`** per payload di grandi dimensioni. Le importazioni sincrone occupano un worker uwsgi per l'intera durata dell'importazione, il che può degradare le prestazioni per tutti gli utenti. +- **Punta a dimensioni del payload inferiori a 1 MB per importazione**, quando possibile. Suddividi gli SBOM di grandi dimensioni in file più piccoli per prodotto o gruppo di componenti. +- **Aggiungi ritardi tra chiamate API consecutive** per evitare l'esaurimento del pool di worker, che causa errori HTTP 502. +- **Usa Reimport** (`/api/v2/reimport-scan/`) per le scansioni ricorrenti, per aggiornare i riscontri esistenti invece di crearne di duplicati. + +## Risposte dell'importazione in background (API: `background_import`) + +Un'importazione in background viene restituita non appena il report caricato è stato analizzato, prima che +qualsiasi riscontro sia stato scritto. La sua risposta descrive quindi un lavoro *pianificato*, ed è +strutturata diversamente rispetto a una sincrona. Questo vale per `/api/v2/import-scan/` e +`/api/v2/reimport-scan/` ogni volta che `background_import` è `true`, oppure ogni volta che +l'impostazione di sistema `api_async_import` la attiva per ogni importazione. + +Una risposta in background contiene: + +- `background_import` — `true`. Questo è il campo su cui basare la logica. +- `status` — lo stato del ciclo di vita del test nel momento in cui la risposta è stata prodotta: + `Processing`, `Post Processing - Deduplication`, + `Post Processing - False Positive History`, `Processed` o `Failed`. +- `findings_parsed` — quanti riscontri sono stati letti dal report. Questo è un conteggio di analisi, + non un conteggio di creazione: la deduplicazione e le opzioni di importazione fornite determinano + quanti riscontri vengono effettivamente scritti. +- `test_id` (e `engagement_id`, `product_id`, `product_type_id`) — gli identificatori da + interrogare periodicamente. +- `message` — le stesse informazioni di `status` e `findings_parsed`, in forma discorsiva. Preferisci + i campi strutturati. + +**Non** contiene `statistics`, e non contiene `deduplication_complete`. +Queste chiavi sono assenti anziché pari a zero, perché a quel punto non è stato creato alcun riscontro +e riportare degli zeri descriverebbe erroneamente l'importazione. Un client che legge +`response["statistics"]` incondizionatamente fallirà su un'importazione in background — leggi prima +`background_import`, oppure usa `statistics` solo nel percorso sincrono. + +Per seguire un'importazione in background fino al completamento, interroga periodicamente il test: + +``` +POST /api/v2/import-scan/ (background_import=true) -> test_id, status, findings_parsed +GET /api/v2/tests/{test_id}/ -> status, processing +``` + +Ripeti la `GET` finché `status` non è `Processed` (l'importazione è terminata, e i conteggi dei riscontri +del test sono ora significativi) o `Failed` (l'importazione non si è completata). Mentre +l'importazione è in corso, `processing` è `true` e `status` indica in quale fase si trova. Usa +alcuni secondi tra un'interrogazione e l'altra; un report di grandi dimensioni può richiedere minuti nella post-elaborazione. + +Un'importazione sincrona (`background_import` omesso o `false`) è invariata: restituisce +la risposta una volta che i riscontri sono stati scritti, include `statistics` e non include `status` +né `findings_parsed`. + +## Utilizzo del campo Data di completamento scansione (API: `scan_date`) + +DefectDojo offre una pletora di report di scanner supportati, ma non tutti contengono le +informazioni più importanti per un utente. Il campo `scan_date` è una funzionalità intelligente e flessibile che +consente agli utenti di impostare la data di completamento di un determinato report di scansione, e di propagarla +a tutti i riscontri importati. Questo campo **non** è obbligatorio, ma il valore predefinito per +questo campo è la data di importazione (quando la richiesta viene elaborata e viene restituita una risposta positiva). + +Ecco i seguenti casi d'uso per l'utilizzo di questo campo: + +1. Il report **non** imposta la data, e `scan_date` **non** è impostato all'importazione + - La data del riscontro sarà il valore predefinito di `scan_date` +2. Il report **imposta** la data, e `scan_date` **non** è impostato all'importazione + - La data del riscontro sarà quella impostata dal report +3. Il report **non** imposta la data, e `scan_date` **è** impostato all'importazione + - La data del riscontro sarà quella impostata dall'utente per `scan_date` +4. Il report **imposta** la data, e `scan_date` **è** impostato all'importazione + - La data del riscontro sarà quella impostata dall'utente per `scan_date` diff --git a/docs/content/automation/api/api-v2-docs.pt-br.md b/docs/content/automation/api/api-v2-docs.pt-br.md new file mode 100644 index 0000000000..292c629055 --- /dev/null +++ b/docs/content/automation/api/api-v2-docs.pt-br.md @@ -0,0 +1,398 @@ +--- +title: DefectDojo API v2 +description: A API do DefectDojo permite automatizar tarefas, por exemplo, enviar + relatórios de scan em pipelines de CI/CD. +draft: false +weight: 2 +aliases: +- /pt-br/en/api/api-v2-docs +--- + +A API do DefectDojo é criada usando o [Django Rest +Framework](http://www.django-rest-framework.org/). A documentação de +cada endpoint está disponível em cada instalação do DefectDojo em +[`/api/v2/oa3/swagger-ui`](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) e pode ser acessada escolhendo o link API v2 +Docs no menu suspenso do usuário no cabeçalho. + +![image](images/api_v2_1.png) + +A documentação é gerada usando o [drf-spectacular](https://drf-spectacular.readthedocs.io/) em [`/api/v2/oa3/swagger-ui/`](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) e é +interativa. No topo da documentação da API v2 há um link que gera uma especificação OpenAPI v3. + +Para interagir com a documentação, é necessário um valor válido de +cabeçalho Authorization. Acesse a view `/api/key-v2` para gerar sua +API Key (`Token `) e copie o valor de cabeçalho fornecido. + +![image](images/api_v2_2.png) + +Cada seção permite que você faça chamadas à API e visualize a Request +URL, o Response Body, o Response Code e os Response Headers. + +![image](images/api_v2_3.png) + +Se você estiver logado na interface web do Defect Dojo, não é necessário fornecer o token de autorização. + +## Autenticação + +A API usa autenticação por cabeçalho com API key. O formato do +cabeçalho deve ser: : + + Authorization: Token + +Por exemplo: : + + Authorization: Token c8572a5adf107a693aa6c72584da31f4d1f1dcff + +### Método de autenticação alternativo + +Se você usa [um método de autenticação alternativo](/admin/sso/) para os usuários, talvez queira desabilitar os tokens de API do DefectDojo, pois isso pode contornar seu esquema de autenticação. \ +A utilização dos tokens de API do DefectDojo pode ser desabilitada especificando a variável de ambiente `DD_API_TOKENS_ENABLED` como `False`. +Ou apenas o endpoint `api/v2/api-token-auth/` pode ser desabilitado definindo `DD_API_TOKEN_AUTH_ENDPOINT_ENABLED` como `False`. + +## Código de exemplo + +Seguem alguns exemplos simples em python e seus resultados produzidos +contra o endpoint `/users`: : + +{{< highlight python >}} +import requests + +url = 'http://127.0.0.1:8000/api/v2/users' +headers = {'content-type': 'application/json', + 'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'} +r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed + +for key, value in r.__dict__.items(): + print(f"'{key}': '{value}'") + print('------------------') +{{< /highlight >}} + +Esse código retornará a lista de todos os usuários definidos no DefectDojo. +O objeto json resultante se parece com: : + +{{< highlight json >}} + [ + { + "first_name": "Tyagi", + "id": 22, + "last_login": "2019-06-18T08:05:51.925743", + "last_name": "Paz", + "username": "dev7958" + }, + { + "first_name": "saurabh", + "id": 31, + "last_login": "2019-06-06T11:44:32.533035", + "last_name": "", + "username": "saurabh.paz" + } + ] +{{< /highlight >}} + +Aqui está outro exemplo contra o endpoint `/users`; desta vez +filtraremos os resultados para incluir apenas os usuários cujo nome de +usuário contém `jay`: + +{{< highlight python >}} +import requests + +url = 'http://127.0.0.1:8000/api/v2/users/?username__contains=jay' +headers = {'content-type': 'application/json', + 'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'} +r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed + +for key, value in r.__dict__.items(): + print(f"'{key}': '{value}'") + print('------------------') +{{< /highlight >}} + +O objeto json resultante é: : + +{{< highlight json >}} +[ + { + "first_name": "Jay", + "id": 22, + "last_login": "2015-10-28T08:05:51.925743", + "last_name": "Paz", + "username": "jay7958" + }, + { + "first_name": "", + "id": 31, + "last_login": "2015-10-13T11:44:32.533035", + "last_name": "", + "username": "jay.paz" + } +] +{{< /highlight >}} + +Consulte a [documentação do Django Rest Framework sobre como interagir +com uma API](https://www.django-rest-framework.org/) para +exemplos e dicas adicionais. + +## Chamando a API manualmente + +Ferramentas como o Postman podem ser usadas para testar a API. + +Exemplo de importação de um resultado de scan: + +- Verbo: POST +- URI: +- Aba Headers: + + adicione o cabeçalho de autenticação + : - Chave: Authorization + - Valor: Token c8572a5adf107a693aa6c72584da31f4d1f1dcff + +- Aba Body + + - selecione \"form-data\", clique em \"bulk edit\". Exemplo para um scan ZAP: + + + + engagement:3 + verified:true + active:true + lead:1 + tags:test + scan_type:ZAP Scan + minimum_severity:Info + close_old_findings:false + +- Aba Body + + - Clique em \"Key-value\" edit + - Adicione um parâmetro \"file\" do tipo \"file\". Isso acionará o + envio de dados de formulário multi-part para enviar o conteúdo do arquivo + - Navegue até o arquivo a ser enviado + +- Clique em enviar + +## Clientes / Wrappers de API + +| Wrapper | Status | Notes | +| -----------------------------| ------------------------| ------------------------| +| [Specific python wrapper](https://github.com/DefectDojo/defectdojo_api) | funcionando (2021-01-21) | Wrapper de API incluindo scripts para envio contínuo em CI/CD. Está um pouco atrasado em relação aos recursos mais recentes da API, pois planejamos reformular o wrapper | +| [Openapi python wrapper](https://github.com/alles-klar/defectdojo-api-v2-client) | | apenas prova de conceito, na qual descobrimos que a especificação OpenAPI ainda não está perfeita | +| [Java library](https://github.com/secureCodeBox/defectdojo-client-java) | funcionando (2021-08-30) | Criado pelas gentis pessoas do [SecureCodeBox](https://github.com/secureCodeBox/secureCodeBox) | +| [Image using the Java library](https://github.com/SDA-SE/defectdojo-client) | funcionando (2021-08-30) | | +| [.Net/C# library](https://www.nuget.org/packages/DefectDojo.Api/) | funcionando (2021-06-08) | | +| [dd-import](https://github.com/MaibornWolff/dd-import) | funcionando (2021-08-24) | dd-import não é diretamente um wrapper de API. Ele oferece algumas funções de conveniência para facilitar a importação de achados e dados de linguagem a partir de pipelines de CI/CD. | + +Alguns dos wrappers de API contêm bastante lógica para facilitar o escaneamento e a importação em ambientes de CI/CD. Estamos no processo de simplificar isso tornando a API do DefectDojo mais inteligente (para que os wrappers/scripts de API possam ser mais simples). + +## Notas sobre a API + +### Import / Reimport + +**Reimport** é, na verdade, a forma mais fácil de começar, pois ele cria as entidades necessárias dinamicamente e detecta automaticamente se é o primeiro upload ou um novo envio. + +## Importação +A importação via API é realizada através do endpoint [import-scan](https://demo.defectdojo.org/api/v2/doc/). + +Conforme descrito em [Product Hierarchy](/asset_modelling/os_hierarchy/product_hierarchy/), o Teste é criado dentro de um Engajamento, dentro de um Produto, dentro de um Tipo de Produto. + +Uma importação pode ser realizada especificando os nomes dessas entidades na requisição da API: + + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "product_type_name": 'Good Products', + "product_name": 'My little product', + "engagement_name": 'Important import', + "auto_create_context": True, +} +``` + +Quando `auto_create_context` é `True`, o produto, o engajamento e o ambiente serão criados se necessário. Certifique-se de que seu usuário tenha [permissões](/admin/user_management/about_perms_and_roles/) suficientes para isso. + +Uma forma clássica de importar um scan é especificando o ID do engajamento em vez disso: + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "engagement": 123, +} +``` + +## Reimportação +A reimportação via API é realizada através do endpoint [reimport-scan](https://demo.defectdojo.org/api/v2/doc/). + +Uma reimportação pode ser realizada especificando os nomes dessas entidades na requisição da API: + + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "product_type_name": 'Good Products', + "product_name": 'My little product', + "engagement_name": 'Important import', + "auto_create_context": True, + "do_not_reactivate": False, +} +``` + +Quando `auto_create_context` é `True`, o Tipo de Produto, o Produto e o Engajamento serão criados caso ainda não existam. Certifique-se de que seu usuário tenha [permissões](/admin/user_management/about_perms_and_roles/) suficientes para criar um Produto/Tipo de Produto. + +Quando `do_not_reactivate` é `True`, a importação/reimportação ignorará os achados ativos enviados e não reativará achados anteriormente fechados, embora ainda crie novos achados caso haja novidades. Você receberá uma nota no achado explicando que ele não foi reativado por esse motivo. + +Uma reimportação selecionará automaticamente o teste mais recente dentro do engajamento fornecido que satisfaça o `scan_type` informado e (opcionalmente) o `test_title` informado. + +Se nenhum Teste existente for encontrado, o endpoint de reimportação usará a função de importação para importar o relatório fornecido em um novo Teste. Isso significa que um script (de CI/CD) que usa a API não precisa saber se um Teste já existe, ou se é o primeiro upload para esse Produto/Engajamento. + +Uma forma clássica de reimportar um scan é especificando o ID do teste em vez disso: + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test": 123, +} +``` + +## Gerando relatórios + +O DefectDojo pode gerar um relatório de achados através da API nos formatos **JSON**, **HTML**, **CSV** ou **Excel**. + +Um relatório é gerado com uma requisição `POST` para uma ação `generate_report/`. O endpoint de achados gera relatórios em toda a sua instância, e a maioria dos outros objetos expõe uma ação por objeto: + +| Endpoint | Scope | +|---|---| +| `POST /api/v2/findings/generate_report/` | Todo achado que você tenha permissão para visualizar | +| `POST /api/v2/products/{id}/generate_report/` | Um produto | +| `POST /api/v2/engagements/{id}/generate_report/` | Um engajamento | +| `POST /api/v2/tests/{id}/generate_report/` | Um teste | +| `POST /api/v2/product_types/{id}/generate_report/` | Um tipo de produto | +| `POST /api/v2/endpoints/{id}/generate_report/` | Um endpoint | + +Os aliases de objeto do Pro expõem a mesma ação: `/api/v2/assets/{id}/generate_report/`, `/api/v2/organizations/{id}/generate_report/` e `/api/v2/location/{id}/generate_report/`. + +### Opções da requisição + +Todos os campos são opcionais — enviar um corpo vazio (`{}`) retorna um relatório JSON. + +| Field | Type | Default | Description | +|---|---|---|---| +| `report_type` | string | `JSON` | Um de `JSON`, `HTML`, `CSV`, `Excel`. | +| `include_finding_notes` | boolean | `false` | Inclui as notas de cada achado. | +| `include_finding_images` | boolean | `false` | Inclui as imagens anexadas aos achados. | +| `include_executive_summary` | boolean | `false` | Inclui uma seção de resumo executivo. | +| `include_table_of_contents` | boolean | `false` | Inclui um sumário. | + +Um `report_type` não suportado (por exemplo, `PDF`) retorna `400 Bad Request` com um erro no campo `report_type`. + +### Exemplo + +Gere um relatório CSV de todos os achados que você pode visualizar e salve-o em um arquivo: + +```bash +curl -X POST \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{"report_type": "CSV"}' \ + https:///api/v2/findings/generate_report/ \ + -o findings.csv +``` + +### Formatos de resposta + +| `report_type` | Content type | Response | +|---|---|---| +| `JSON` (default) | `application/json` | Corpo do relatório na resposta | +| `HTML` | `text/html` | Página de relatório renderizada | +| `CSV` | `text/csv` | Anexo de arquivo | +| `Excel` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Anexo de arquivo `.xlsx` | + +CSV e Excel são retornados como anexos de arquivo com um cabeçalho `Content-Disposition`, em vez de um corpo JSON. O nome do arquivo é derivado do objeto a partir do qual o relatório foi gerado — por exemplo, `product_1_findings.csv` ou `test_42_findings.xlsx`. O endpoint `/findings/generate_report/` não está restrito a um único objeto, portanto seus downloads recebem os nomes `findings.csv` e `findings.xlsx`. + +### Notas e limitações + +* As opções `include_*` afetam apenas os relatórios **JSON** e **HTML**. As exportações **CSV** e **Excel** sempre contêm as linhas de achados. +* A geração de relatórios requer permissão de **visualização** nos objetos envolvidos, e um relatório sempre contém apenas os achados que você está autorizado a ver. +* **Os filtros de parâmetros de consulta padrão não são aplicados a esta ação.** Diferente de `GET /api/v2/findings/`, a ação `generate_report/` não aplica os filtros de achados, portanto uma requisição como `POST /api/v2/findings/generate_report/?severity=High` ainda gera relatório sobre todos os achados que você pode visualizar. Para restringir um relatório, gere-o a partir de um produto, engajamento ou teste específico. + +## Comportamento de exclusão assíncrona + +As exclusões no DefectDojo (tanto pela API quanto pela UI) são processadas de forma **assíncrona** por workers em segundo plano do Celery. Quando você exclui um Engajamento, Teste ou outro objeto, a API ou a UI retorna uma resposta de sucesso imediatamente, mas a exclusão de fato é executada em segundo plano. + +Isso significa que: +- Os objetos ainda podem aparecer em consultas por um período após a exclusão ser confirmada. +- As exclusões em cascata (por exemplo, excluir um Engajamento também exclui seus Testes e Achados) são processadas como uma cadeia de tarefas em segundo plano. Os objetos filhos são removidos em ordem de dependência: Achados, depois Testes, depois Engajamentos. +- Para Engajamentos grandes com muitos Achados, esse processo pode levar vários minutos para ser concluído. + +Não há necessidade de criar scripts personalizados para excluir objetos em ordem de dependência. Uma única requisição `DELETE` em um Engajamento se propagará automaticamente em cascata para todos os objetos filhos. Basta aguardar o tempo necessário para que as tarefas em segundo plano sejam concluídas. + +## Limites de paginação da API + +O DefectDojo Pro impõe um tamanho máximo de página de **250** resultados por requisição de API. Definir `limit` acima de 250 pode resultar em erros HTTP 502 devido a timeouts de consulta. + +Instâncias do DefectDojo Open Source também podem apresentar timeouts com tamanhos de página muito grandes, dependendo do tamanho do conjunto de dados e dos recursos do servidor. + +Para conjuntos de resultados grandes, use paginação com um tamanho de página de 50 a 250 e adicione pequenos atrasos entre as requisições paginadas para evitar sobrecarregar o pool de workers. + +## Boas práticas para importação em grande escala + +Ao importar resultados de scan em grande escala (por exemplo, pipelines de SBOM com milhares de componentes), considere o seguinte: + +- **Use `background_import=true`** para payloads grandes. Importações síncronas ocupam um worker uwsgi durante toda a importação, o que pode degradar o desempenho para todos os usuários. +- **Direcione tamanhos de payload abaixo de 1 MB por importação**, sempre que possível. Divida SBOMs grandes em arquivos menores por produto ou grupo de componentes. +- **Adicione atrasos entre chamadas de API consecutivas** para evitar o esgotamento do pool de workers, o que causa erros HTTP 502. +- **Use a Reimportação** (`/api/v2/reimport-scan/`) para scans recorrentes, a fim de atualizar achados existentes em vez de criar duplicatas. + +## Respostas de importação em segundo plano (API: `background_import`) + +Uma importação em segundo plano retorna assim que o relatório enviado é analisado (parsed), antes que qualquer achado tenha sido gravado. Sua resposta, portanto, descreve um trabalho *agendado*, e tem um formato diferente do de uma importação síncrona. Isso se aplica a `/api/v2/import-scan/` e `/api/v2/reimport-scan/` sempre que `background_import` é `true`, ou sempre que a configuração de sistema `api_async_import` ativa esse comportamento para todas as importações. + +Uma resposta em segundo plano contém: + +- `background_import` — `true`. Este é o campo em que se deve basear a lógica condicional. +- `status` — o status de ciclo de vida do teste no momento em que a resposta foi produzida: + `Processing`, `Post Processing - Deduplication`, + `Post Processing - False Positive History`, `Processed` ou `Failed`. +- `findings_parsed` — quantos achados foram lidos a partir do relatório. Esta é uma contagem de análise (parse), não uma contagem de criação: a deduplicação e as opções de importação fornecidas por você determinam quantos achados são de fato gravados. +- `test_id` (e `engagement_id`, `product_id`, `product_type_id`) — os identificadores para consulta. +- `message` — a mesma informação de `status` e `findings_parsed`, em forma de texto. Prefira os campos estruturados. + +Ela **não** contém `statistics`, nem contém `deduplication_complete`. Essas chaves ficam ausentes em vez de zeradas, pois, nesse momento, nenhum achado foi criado, e informar zeros descreveria a importação de forma incorreta. Um cliente que lê `response["statistics"]` incondicionalmente falhará em uma importação em segundo plano — leia `background_import` primeiro, ou use `statistics` apenas no caminho síncrono. + +Para acompanhar uma importação em segundo plano até sua conclusão, consulte o teste: + +``` +POST /api/v2/import-scan/ (background_import=true) -> test_id, status, findings_parsed +GET /api/v2/tests/{test_id}/ -> status, processing +``` + +Repita o `GET` até que `status` seja `Processed` (a importação terminou, e as contagens de achados do teste agora são significativas) ou `Failed` (a importação não foi concluída). Enquanto a importação está em execução, `processing` é `true` e `status` informa em qual fase ela se encontra. Use alguns segundos entre as consultas; um relatório grande pode levar minutos no pós-processamento. + +Uma importação síncrona (`background_import` omitido ou `false`) permanece inalterada: ela retorna assim que os achados foram gravados, inclui `statistics` e não inclui `status` nem `findings_parsed`. + +## Usando o campo de data de conclusão do scan (API: `scan_date`) + +O DefectDojo oferece uma infinidade de relatórios de scanner suportados, mas nem todos contêm a informação mais importante para o usuário. O campo `scan_date` é um recurso inteligente e flexível que permite ao usuário definir a data de conclusão de um determinado relatório de scan, propagando-a para todos os achados importados. Este campo **não** é obrigatório, mas o valor padrão para esse campo é a data da importação (quando a requisição é processada e uma resposta de sucesso é retornada). + +Seguem os casos de uso para esse campo: + +1. O relatório **não** define a data, e `scan_date` **não** é definido na importação + - A data do achado será o valor padrão de `scan_date` +2. O relatório **define** a data, e `scan_date` **não** é definido na importação + - A data do achado será o que quer que o relatório definir +3. O relatório **não** define a data, e `scan_date` **é definido** na importação + - A data do achado será o que quer que o usuário tenha definido para `scan_date` +4. O relatório **define** a data, e `scan_date` **é definido** na importação + - A data do achado será o que quer que o usuário tenha definido para `scan_date` diff --git a/docs/content/automation/api/api-v2-docs.zh-hans.md b/docs/content/automation/api/api-v2-docs.zh-hans.md new file mode 100644 index 0000000000..1d84b1bb94 --- /dev/null +++ b/docs/content/automation/api/api-v2-docs.zh-hans.md @@ -0,0 +1,417 @@ +--- +title: DefectDojo API v2 +description: DefectDojo 的 API 可让您自动执行任务，例如在 CI/CD 流水线中上传扫描报告。 +draft: false +weight: 2 +aliases: +- /zh-hans/en/api/api-v2-docs +--- + +DefectDojo 的 API 使用 [Django Rest +Framework](http://www.django-rest-framework.org/) 构建。每个端点的文档 +在每个 DefectDojo 安装实例中都可以通过 +[`/api/v2/oa3/swagger-ui`](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) 获取，也可以通过页眉中用户下拉菜单里的 API v2 +Docs 链接访问。 + +![image](images/api_v2_1.png) + +该文档使用 [drf-spectacular](https://drf-spectacular.readthedocs.io/) 在 [`/api/v2/oa3/swagger-ui/`](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) 生成，并且 +是可交互的。在 API v2 文档顶部有一个链接，可用于生成 OpenAPI v3 规范。 + +要与该文档进行交互，需要提供一个有效的 Authorization 请求头 +值。访问 `/api/key-v2` 页面以生成您的 +API 密钥（`Token `），然后复制所提供的请求头值。 + +![image](images/api_v2_2.png) + +每个部分都允许您调用 API，并查看请求 +URL、响应正文（Response Body）、响应代码（Response Code）以及响应头（Response Headers）。 + +![image](images/api_v2_3.png) + +如果您已登录到 Defect Dojo 网页界面，则无需提供授权令牌。 + +## Authentication + +该 API 使用带有 API 密钥的请求头身份验证方式。请求头的 +格式应为：: + + Authorization: Token + +例如：: + + Authorization: Token c8572a5adf107a693aa6c72584da31f4d1f1dcff + +### Alternative authentication method + +如果您为用户使用[某种替代身份验证方法](/admin/sso/)，您可能会希望禁用 DefectDojo API 令牌，因为它可能绕过您的身份验证机制。\ +可以通过将环境变量 `DD_API_TOKENS_ENABLED` 设置为 `False` 来禁用 DefectDojo API 令牌的使用。 +也可以仅通过将 `DD_API_TOKEN_AUTH_ENDPOINT_ENABLED` 设置为 `False` 来禁用 `api/v2/api-token-auth/` 端点。 + +## Sample Code + +以下是一些针对 +`/users` 端点的简单 python 示例及其运行结果：: + +{{< highlight python >}} +import requests + +url = 'http://127.0.0.1:8000/api/v2/users' +headers = {'content-type': 'application/json', + 'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'} +r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed + +for key, value in r.__dict__.items(): + print(f"'{key}': '{value}'") + print('------------------') +{{< /highlight >}} + +此代码将返回 DefectDojo 中定义的所有用户列表。 +json 对象结果如下所示：: + +{{< highlight json >}} + [ + { + "first_name": "Tyagi", + "id": 22, + "last_login": "2019-06-18T08:05:51.925743", + "last_name": "Paz", + "username": "dev7958" + }, + { + "first_name": "saurabh", + "id": 31, + "last_login": "2019-06-06T11:44:32.533035", + "last_name": "", + "username": "saurabh.paz" + } + ] +{{< /highlight >}} + +下面是另一个针对 `/users` 端点的示例，这 +次我们将结果过滤为仅包含用户 +名中包含 `jay` 的用户： + +{{< highlight python >}} +import requests + +url = 'http://127.0.0.1:8000/api/v2/users/?username__contains=jay' +headers = {'content-type': 'application/json', + 'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'} +r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed + +for key, value in r.__dict__.items(): + print(f"'{key}': '{value}'") + print('------------------') +{{< /highlight >}} + +json 对象结果为：: + +{{< highlight json >}} +[ + { + "first_name": "Jay", + "id": 22, + "last_login": "2015-10-28T08:05:51.925743", + "last_name": "Paz", + "username": "jay7958" + }, + { + "first_name": "", + "id": 31, + "last_login": "2015-10-13T11:44:32.533035", + "last_name": "", + "username": "jay.paz" + } +] +{{< /highlight >}} + +更多示例和技巧请参阅 [Django Rest Framework\'s documentation on interacting with an +API](https://www.django-rest-framework.org/)。 + +## Manually calling the API + +可以使用 Postman 之类的工具来测试该 API。 + +导入扫描结果的示例： + +- 动词：POST +- URI： +- Headers 选项卡： + + 添加身份验证请求头 + : - Key：Authorization + - Value：Token c8572a5adf107a693aa6c72584da31f4d1f1dcff + +- Body 选项卡 + + - 选择 \"form-data\"，点击 \"bulk edit\"。ZAP 扫描示例： + + + + engagement:3 + verified:true + active:true + lead:1 + tags:test + scan_type:ZAP Scan + minimum_severity:Info + close_old_findings:false + +- Body 选项卡 + + - 点击 \"Key-value\" 编辑 + - 添加一个类型为 \"file\" 的 \"file\" 参数。这将触发 + 用于发送文件内容的多部分表单数据 + - 浏览并选择要上传的文件 + +- 点击发送 + +## Clients / API Wrappers + +| Wrapper | Status | Notes | +| -----------------------------| ------------------------| ------------------------| +| [Specific python wrapper](https://github.com/DefectDojo/defectdojo_api) | working (2021-01-21) | API 封装库，包含用于持续 CI/CD 上传的脚本。在最新 API 功能方面稍有滞后，因为我们计划对该 API 封装库进行改版 | +| [Openapi python wrapper](https://github.com/alles-klar/defectdojo-api-v2-client) | | 目前仅是概念验证，我们由此发现 OpenAPI 规范尚不完善 | +| [Java library](https://github.com/secureCodeBox/defectdojo-client-java) | working (2021-08-30) | 由 [SecureCodeBox](https://github.com/secureCodeBox/secureCodeBox) 的热心人士创建 | +| [Image using the Java library](https://github.com/SDA-SE/defectdojo-client) | working (2021-08-30) | | +| [.Net/C# library](https://www.nuget.org/packages/DefectDojo.Api/) | working (2021-06-08) | | +| [dd-import](https://github.com/MaibornWolff/dd-import) | working (2021-08-24) | dd-import 并非严格意义上的 API 封装库，它提供了一些便捷功能，使从 CI/CD 流水线导入发现项和语言数据变得更容易。 | + +部分 API 封装库包含相当多的逻辑，用于简化 CI/CD 环境中的扫描和导入操作。我们正在通过让 DefectDojo API 变得更智能，来简化这一点（这样 API 封装库/脚本就可以变得更简单）。 + +## API Notes + +### Import / Reimport + +**重新导入（Reimport）** 实际上是最容易上手的方式，因为它会在需要时即时创建各类实体，并自动检测这是首次上传还是重复上传。 + +## Import +通过 API 进行导入是通过 [import-scan](https://demo.defectdojo.org/api/v2/doc/) 端点完成的。 + +如[产品层级结构](/asset_modelling/os_hierarchy/product_hierarchy/)中所述，测试（Test）创建在测试活动（Engagement）内部，测试活动创建在产品（Product）内部，产品创建在产品类型（Product Type）内部。 + +可以通过在 API 请求中指定这些实体的名称来执行导入： + + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "product_type_name": 'Good Products', + "product_name": 'My little product', + "engagement_name": 'Important import', + "auto_create_context": True, +} +``` + +当 `auto_create_context` 为 `True` 时，将在需要时创建产品、测试活动和环境。请确保您的用户拥有足够的[权限](/admin/user_management/about_perms_and_roles/)来执行此操作。 + +导入扫描的经典方式是改为指定测试活动的 ID： + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "engagement": 123, +} +``` + +## Reimport +通过 API 进行重新导入是通过 [reimport-scan](https://demo.defectdojo.org/api/v2/doc/) 端点完成的。 + +可以通过在 API 请求中指定这些实体的名称来执行重新导入： + + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test_title": 'Manual ZAP Scan by John', + "product_type_name": 'Good Products', + "product_name": 'My little product', + "engagement_name": 'Important import', + "auto_create_context": True, + "do_not_reactivate": False, +} +``` + +当 `auto_create_context` 为 `True` 时，如果产品类型、产品和测试活动尚不存在，则会创建它们。请确保您的用户拥有足够的[权限](/admin/user_management/about_perms_and_roles/)来创建产品/产品类型。 + +当 `do_not_reactivate` 为 `True` 时，导入/重新导入将忽略已上传的活动发现项，不会重新激活先前已关闭的发现项，但仍会创建新的发现项（如果存在的话）。您会在该发现项上看到一条备注，说明它因此原因而未被重新激活。 + +重新导入将自动选择所提供测试活动中满足所提供 `scan_type`（以及可选提供的 `test_title`）条件的最新测试。 + +如果找不到现有测试，重新导入端点将使用导入功能，将所提供的报告导入到一个新的测试中。这意味着使用该 API 的（CI/CD）脚本无需知道某个测试是否已经存在，也无需知道这是否是该产品/测试活动的首次上传。 + +重新导入扫描的经典方式是改为指定测试的 ID： + +```JSON +{ + "minimum_severity": 'Info', + "active": True, + "verified": True, + "scan_type": 'ZAP Scan', + "test": 123, +} +``` + +## Generating Reports + +DefectDojo 可以通过 API 生成 **JSON**、**HTML**、**CSV** 或 **Excel** 格式的发现项报告。 + +报告是通过向 `generate_report/` 操作发送 `POST` 请求生成的。findings 端点会针对您整个实例生成报告，而大多数其他对象则提供针对单个对象的操作： + +| Endpoint | Scope | +|---|---| +| `POST /api/v2/findings/generate_report/` | 您有权查看的所有发现项 | +| `POST /api/v2/products/{id}/generate_report/` | 单个产品 | +| `POST /api/v2/engagements/{id}/generate_report/` | 单个测试活动 | +| `POST /api/v2/tests/{id}/generate_report/` | 单个测试 | +| `POST /api/v2/product_types/{id}/generate_report/` | 单个产品类型 | +| `POST /api/v2/endpoints/{id}/generate_report/` | 单个端点 | + +Pro 版的对象别名提供相同的操作：`/api/v2/assets/{id}/generate_report/`、`/api/v2/organizations/{id}/generate_report/` 以及 `/api/v2/location/{id}/generate_report/`。 + +### Request options + +所有字段均为可选 — 提交空请求体（`{}`）将返回一份 JSON 报告。 + +| Field | Type | Default | Description | +|---|---|---|---| +| `report_type` | string | `JSON` | 取值为 `JSON`、`HTML`、`CSV`、`Excel` 之一。 | +| `include_finding_notes` | boolean | `false` | 包含每个发现项的备注。 | +| `include_finding_images` | boolean | `false` | 包含发现项所附带的图片。 | +| `include_executive_summary` | boolean | `false` | 包含执行摘要部分。 | +| `include_table_of_contents` | boolean | `false` | 包含目录。 | + +不受支持的 `report_type`（例如 `PDF`）会返回 `400 Bad Request`，并在 `report_type` 字段上给出错误提示。 + +### Example + +生成一份包含您可查看的所有发现项的 CSV 报告，并将其保存到文件中： + +```bash +curl -X POST \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{"report_type": "CSV"}' \ + https:///api/v2/findings/generate_report/ \ + -o findings.csv +``` + +### Response formats + +| `report_type` | Content type | Response | +|---|---|---| +| `JSON` (default) | `application/json` | 响应中包含报告正文 | +| `HTML` | `text/html` | 渲染后的报告页面 | +| `CSV` | `text/csv` | 文件附件 | +| `Excel` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `.xlsx` 文件附件 | + +CSV 和 Excel 是作为带有 `Content-Disposition` 请求头的文件附件返回的，而不是作为 JSON 正文返回。文件名来源于生成报告所基于的对象 — 例如 `product_1_findings.csv` 或 `test_42_findings.xlsx`。`/findings/generate_report/` 端点不限定于单个对象，因此其下载文件名固定为 `findings.csv` 和 `findings.xlsx`。 + +### Notes and limitations + +* `include_*` 选项仅影响 **JSON** 和 **HTML** 报告。**CSV** 和 **Excel** 导出始终包含发现项行数据。 +* 生成报告需要对相关对象拥有**查看（view）**权限，报告中也只会包含您有权查看的发现项。 +* **标准的查询参数过滤器不适用于此操作。** 与 `GET /api/v2/findings/` 不同，`generate_report/` 操作不会应用发现项过滤器，因此像 `POST /api/v2/findings/generate_report/?severity=High` 这样的请求，仍会报告您可查看的全部发现项。若要缩小报告范围，请改为针对特定产品、测试活动或测试生成报告。 + +## Asynchronous Deletion Behavior + +DefectDojo 中的删除操作（无论通过 API 还是 UI）都由 Celery 后台工作进程**异步**处理。当您删除一个测试活动、测试或其他对象时，API 或 UI 会立即返回成功响应，但实际的删除操作会在后台运行。 + +这意味着： +- 在删除操作确认之后的一段时间内，对象可能仍会出现在查询结果中。 +- 级联删除（例如删除一个测试活动同时也会删除其测试和发现项）会作为一系列后台任务链进行处理。子对象会按依赖顺序被移除：先是发现项，然后是测试，最后是测试活动。 +- 对于包含大量发现项的大型测试活动，此过程可能需要几分钟才能完成。 + +无需构建自定义脚本来按依赖顺序删除对象。对某个测试活动发出的单个 `DELETE` 请求，会自动级联到其所有子对象。只需留出足够的时间让后台任务完成即可。 + +## API Pagination Limits + +DefectDojo Pro 对每个 API 请求强制实施最多 **250** 条结果的分页大小限制。将 `limit` 设置为高于 250 的值，可能会因查询超时而导致 HTTP 502 错误。 + +开源版 DefectDojo 实例在分页大小非常大时，也可能因数据集大小和服务器资源的不同而出现超时。 + +对于较大的结果集，请使用 50-250 之间的分页大小，并在各分页请求之间加入短暂延迟，以避免使工作进程池达到饱和。 + +## Large-Scale Import Best Practices + +在大规模导入扫描结果时（例如包含数千个组件的 SBOM 流水线），请考虑以下几点： + +- **对较大的负载使用 `background_import=true`。** 同步导入会在导入期间占用一个 uwsgi 工作进程，这可能会降低所有用户的性能。 +- **尽可能将每次导入的负载大小控制在 1 MB 以下。** 将较大的 SBOM 按产品或组件分组拆分为多个较小的文件。 +- **在连续的 API 调用之间加入延迟**，以避免工作进程池耗尽而引发 HTTP 502 错误。 +- **对定期性的扫描使用重新导入（Reimport）**（`/api/v2/reimport-scan/`）来更新现有发现项，而不是创建重复项。 + +## Background import responses (API: `background_import`) + +后台导入会在上传的报告解析完成后立即返回，此时尚未写入任何 +发现项。因此其响应描述的是*已计划*的工作，其结构也 +与同步导入不同。只要 `background_import` 为 `true`，或者 +`api_async_import` 系统设置为所有导入都启用了该行为，这一点就适用于 `/api/v2/import-scan/` 和 +`/api/v2/reimport-scan/`。 + +后台响应包含： + +- `background_import` — `true`。这是用于分支判断的字段。 +- `status` — 响应生成那一刻测试所处的生命周期状态： + `Processing`、`Post Processing - Deduplication`、 + `Post Processing - False Positive History`、`Processed` 或 `Failed`。 +- `findings_parsed` — 从报告中解析出的发现项数量。这是一个解析 + 计数，而非创建计数：去重逻辑以及您所提供的导入选项，将决定 + 最终实际写入多少条发现项。 +- `test_id`（以及 `engagement_id`、`product_id`、`product_type_id`）— 用于 + 轮询的标识符。 +- `message` — 以文字形式呈现与 `status` 和 `findings_parsed` 相同的信息。请优先使用 + 结构化字段。 + +它**不**包含 `statistics`，也不包含 `deduplication_complete`。 +这些键是缺失而非为零，因为此时尚未写入任何发现项， +若报告为零则会错误地描述该次导入。若客户端无条件读取 +`response["statistics"]`，在遇到后台导入时会失败 — 请先读取 +`background_import` 字段，或仅在同步路径中使用 `statistics`。 + +要跟踪某次后台导入直至完成，请轮询该测试： + +``` +POST /api/v2/import-scan/ (background_import=true) -> test_id, status, findings_parsed +GET /api/v2/tests/{test_id}/ -> status, processing +``` + +重复执行该 `GET` 请求，直到 `status` 变为 `Processed`（导入已完成，此时测试的 +发现项计数才具有意义）或 `Failed`（导入未能完成）。在 +导入进行期间，`processing` 为 `true`，`status` 会报告当前所处的阶段。请在 +每次轮询之间间隔几秒钟；较大的报告在后处理阶段可能会耗费数分钟。 + +同步导入（省略 `background_import` 或将其设为 `false`）保持不变：它会 +在发现项写入完成后返回，包含 `statistics`，且不包含 `status` +或 `findings_parsed`。 + +## Using the Scan Completion Date (API: `scan_date`) field + +DefectDojo 支持大量的扫描器报告格式，但并非所有报告都包含用户最看重的 +信息。`scan_date` 字段是一项灵活的智能功能， +允许用户设置某次给定扫描报告的完成日期，并将其向下传播 +到所有导入的发现项中。此字段**并非**必填，但该 +字段的默认值为导入日期（即请求被处理并成功返回响应的那一刻）。 + +以下是使用该字段的几种情形： + +1. 报告**未**设置日期，且导入时**未**设置 `scan_date` + - 发现项日期将采用 `scan_date` 的默认值 +2. 报告**设置**了日期，且导入时**未**设置 `scan_date` + - 发现项日期将采用报告所设置的日期 +3. 报告**未**设置日期，且导入时**设置**了 `scan_date` + - 发现项日期将采用用户为 `scan_date` 所设置的值 +4. 报告**设置**了日期，且导入时也**设置**了 `scan_date` + - 发现项日期将采用用户为 `scan_date` 所设置的值 diff --git a/docs/content/automation/api/languages.it.md b/docs/content/automation/api/languages.it.md new file mode 100644 index 0000000000..e5e0c009a9 --- /dev/null +++ b/docs/content/automation/api/languages.it.md @@ -0,0 +1,39 @@ +--- +title: Lingue e Righe di Codice +description: Importa i dati sulla composizione linguistica per un Prodotto utilizzando + lo strumento cloc +weight: 3 +audience: opensource +aliases: +- /it/en/open_source/languages +--- + +DefectDojo può visualizzare una ripartizione dei linguaggi di programmazione e delle righe di codice per un Prodotto, popolata importando un report dallo strumento [cloc](https://github.com/AlDanial/cloc) (Count Lines of Code) tramite l'API. + +## Generazione del report cloc + +Esegui `cloc` sul tuo codice utilizzando il flag `--json` per produrre un file JSON nel formato corretto: + +```bash +cloc --json /path/to/your/project > cloc-report.json +``` + +## Importazione tramite API + +Carica il report JSON su DefectDojo tramite l'API. Durante l'importazione, tutti i dati linguistici esistenti per il Prodotto vengono sostituiti con il contenuto del nuovo file. + +L'endpoint di importazione è documentato nella [documentazione API v2 di DefectDojo](../api-v2-docs/). + +## Visualizzazione dei risultati + +Dopo l'importazione, la ripartizione dei linguaggi viene visualizzata sul lato sinistro della pagina dei dettagli del Prodotto, mostrando ogni linguaggio e il relativo numero di righe. I colori di ogni linguaggio sono definiti dalle voci nella tabella `Language_Type`, pre-popolata con dati da GitHub. + +## Aggiornamento dei colori dei linguaggi + +GitHub aggiorna periodicamente i colori dei linguaggi man mano che emergono nuovi linguaggi. Per scaricare i dati sui colori più recenti, esegui il seguente comando di gestione: + +```bash +./manage.py import_github_languages +``` + +Questo legge da [ozh/github-colors](https://github.com/ozh/github-colors) e aggiunge nuovi linguaggi o aggiorna i colori esistenti. diff --git a/docs/content/automation/api/languages.pt-br.md b/docs/content/automation/api/languages.pt-br.md new file mode 100644 index 0000000000..33f5ea4afa --- /dev/null +++ b/docs/content/automation/api/languages.pt-br.md @@ -0,0 +1,39 @@ +--- +title: Idiomas e linhas de código +description: Importe dados de composição de linguagens para um Produto usando a ferramenta + cloc +weight: 3 +audience: opensource +aliases: +- /pt-br/en/open_source/languages +--- + +O DefectDojo pode exibir uma análise das linguagens de programação e das linhas de código de um Produto, preenchida a partir da importação de um relatório da ferramenta [cloc](https://github.com/AlDanial/cloc) (Count Lines of Code) via API. + +## Gerando o relatório do cloc + +Execute o `cloc` sobre sua base de código usando a flag `--json` para produzir um arquivo JSON no formato correto: + +```bash +cloc --json /path/to/your/project > cloc-report.json +``` + +## Importando via API + +Envie o relatório JSON para o DefectDojo via API. Ao importar, todos os dados de linguagem existentes para o Produto são substituídos pelo conteúdo do novo arquivo. + +O endpoint de importação está documentado em [DefectDojo API v2 docs](../api-v2-docs/). + +## Visualizando os resultados + +Após a importação, a análise das linguagens é exibida no lado esquerdo da página de detalhes do Produto, mostrando cada linguagem e sua contagem de linhas. As cores de cada linguagem são definidas por entradas na tabela `Language_Type`, pré-preenchida com dados do GitHub. + +## Atualizando as cores das linguagens + +O GitHub atualiza periodicamente as cores das linguagens conforme surgem novas linguagens. Para obter os dados de cor mais recentes, execute o seguinte comando de gerenciamento: + +```bash +./manage.py import_github_languages +``` + +Isso lê os dados de [ozh/github-colors](https://github.com/ozh/github-colors) e adiciona novas linguagens ou atualiza cores existentes. diff --git a/docs/content/automation/api/languages.zh-hans.md b/docs/content/automation/api/languages.zh-hans.md new file mode 100644 index 0000000000..f600dc18ef --- /dev/null +++ b/docs/content/automation/api/languages.zh-hans.md @@ -0,0 +1,38 @@ +--- +title: 语言与代码行数 +description: 使用 cloc 工具导入产品的语言组成数据 +weight: 3 +audience: opensource +aliases: +- /zh-hans/en/open_source/languages +--- + +DefectDojo 可以显示某个产品的编程语言构成和代码行数明细，这些数据通过 API 导入 [cloc](https://github.com/AlDanial/cloc)（Count Lines of Code）工具生成的报告来填充。 + +## Generating the cloc Report + +对您的代码库运行 `cloc`，并使用 `--json` 标志以生成格式正确的 JSON 文件： + +```bash +cloc --json /path/to/your/project > cloc-report.json +``` + +## Importing via the API + +通过 API 将该 JSON 报告上传到 DefectDojo。导入时，该产品现有的所有语言数据都会被新文件的内容替换。 + +该导入端点的文档参见 [DefectDojo API v2 文档](../api-v2-docs/)。 + +## Viewing Results + +导入完成后，语言构成明细会显示在产品详情页面的左侧，展示每种语言及其代码行数。每种语言的颜色由 `Language_Type` 表中的条目定义，该表预先填充了来自 GitHub 的数据。 + +## Updating Language Colors + +随着新语言的出现，GitHub 会定期更新语言颜色。要拉取最新的颜色数据，请运行以下管理命令： + +```bash +./manage.py import_github_languages +``` + +该命令会从 [ozh/github-colors](https://github.com/ozh/github-colors) 读取数据，并添加新语言或更新现有颜色。 diff --git a/docs/content/automation/api/notification_webhooks.it.md b/docs/content/automation/api/notification_webhooks.it.md new file mode 100644 index 0000000000..e4d7f9eccf --- /dev/null +++ b/docs/content/automation/api/notification_webhooks.it.md @@ -0,0 +1,346 @@ +--- +title: Webhook di notifica +description: Invia notifiche webhook HTTP a un server esterno sugli eventi di DefectDojo +weight: 8 +audience: opensource +aliases: +- /it/en/open_source/notification_webhooks/how_to +--- + +**Questa è una funzionalità Open Source sperimentale — il comportamento potrebbe cambiare nelle release future.** + +I webhook sono richieste HTTP in uscita inviate dalla tua istanza DefectDojo a un server definito dall'utente ogni volta che si verificano eventi specifici. + +## Configurazione + +Gli endpoint webhook vengono configurati dagli amministratori. Quando viene creato un webhook, DefectDojo invia un evento [`ping`](#ping) per verificare che l'endpoint sia raggiungibile e restituisca il codice di stato previsto. + +## Transizioni di stato dell'endpoint + +DefectDojo monitora il successo della consegna e disabiliterà temporaneamente o permanentemente un endpoint in base alle risposte HTTP o ai guasti di rete. È possibile anche la riattivazione manuale da parte di un amministratore. + +- **Stati a forma di stadio**: Active — i webhook possono essere inviati +- **Stati rettangolari**: Inactive — la consegna del webhook fallirà e non verrà ritentata +- **Transizioni guidate da**: risposte HTTP dal server di destinazione, automazione celery, o azione manuale dell'amministratore + +## Header della richiesta + +Ogni richiesta webhook include i seguenti header: + +```yaml +User-Agent: DefectDojo- +X-DefectDojo-Event: +X-DefectDojo-Instance: +``` + +## Eventi + +### product_type_added + +Attivato quando viene creato un nuovo Product Type. + +**Header:** +```yaml +X-DefectDojo-Event: product_type_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### product_added + +Attivato quando viene creato un nuovo Prodotto. + +**Header:** +```yaml +X-DefectDojo-Event: product_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### engagement_added + +Attivato quando viene creato un nuovo Engagement. + +**Header:** +```yaml +X-DefectDojo-Event: engagement_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### test_added + +Attivato quando viene creato un nuovo Test. + +**Header:** +```yaml +X-DefectDojo-Event: test_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### scan_added / scan_added_empty + +Attivato quando una scansione viene importata o reimportata. `scan_added_empty` si attiva quando una reimportazione non produce alcuna modifica (nessun riscontro creato o chiuso). + +**Headers:** +```yaml +X-DefectDojo-Event: scan_added +``` +```yaml +X-DefectDojo-Event: scan_added_empty +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "finding_count": 4, + "findings": { + "mitigated": [ + { + "id": 233, + "severity": "Medium", + "title": "Mitigated Finding", + "url_api": "http://localhost:8080/api/v2/findings/233/", + "url_ui": "http://localhost:8080/finding/233" + } + ], + "new": [ + { + "id": 232, + "severity": "Critical", + "title": "New Finding", + "url_api": "http://localhost:8080/api/v2/findings/232/", + "url_ui": "http://localhost:8080/finding/232" + } + ], + "reactivated": [ + { + "id": 234, + "severity": "Low", + "title": "Reactivated Finding", + "url_api": "http://localhost:8080/api/v2/findings/234/", + "url_ui": "http://localhost:8080/finding/234" + } + ], + "untouched": [ + { + "id": 235, + "severity": "Info", + "title": "Untouched Finding", + "url_api": "http://localhost:8080/api/v2/findings/235/", + "url_ui": "http://localhost:8080/finding/235" + } + ] + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### ping + +Inviato durante la configurazione del webhook per verificare che l'endpoint sia raggiungibile. + +**Header:** +```yaml +X-DefectDojo-Event: ping +``` + +**Body:** +```json +{ + "description": "Test webhook notification", + "title": "", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +## Roadmap + +Miglioramenti pianificati noti: + +- Eventi relativi agli SLA (non ancora supportati) +- Webhook definiti dall'utente (attualmente solo per amministratori) +- UI migliorata con filtri e paginazione per gli endpoint webhook diff --git a/docs/content/automation/api/notification_webhooks.pt-br.md b/docs/content/automation/api/notification_webhooks.pt-br.md new file mode 100644 index 0000000000..405c8dff5e --- /dev/null +++ b/docs/content/automation/api/notification_webhooks.pt-br.md @@ -0,0 +1,347 @@ +--- +title: Webhooks de notificação +description: Envie notificações de webhook HTTP para um servidor externo em eventos + do DefectDojo +weight: 8 +audience: opensource +aliases: +- /pt-br/en/open_source/notification_webhooks/how_to +--- + +**Este é um recurso experimental do Open Source — o comportamento pode mudar em versões futuras.** + +Webhooks são requisições HTTP de saída enviadas da sua instância do DefectDojo para um servidor definido pelo usuário sempre que ocorrem eventos específicos. + +## Configuração + +Os endpoints de webhook são configurados por administradores. Quando um webhook é criado, o DefectDojo envia um evento [`ping`](#ping) para verificar se o endpoint está acessível e retornando o código de status esperado. + +## Transições de estado do endpoint + +O DefectDojo monitora o sucesso das entregas e desabilitará um endpoint temporária ou permanentemente com base em respostas HTTP ou falhas de rede. A reativação manual por um administrador também é possível. + +- **Estados em formato de estádio**: Ativo — webhooks podem ser enviados +- **Estados em formato de retângulo**: Inativo — a entrega do webhook falhará e não será repetida +- **Transições motivadas por**: respostas HTTP do servidor de destino, automação do celery, ou ação manual de um administrador + +## Cabeçalhos da requisição + +Toda requisição de webhook inclui os seguintes cabeçalhos: + +```yaml +User-Agent: DefectDojo- +X-DefectDojo-Event: +X-DefectDojo-Instance: +``` + +## Eventos + +### product_type_added + +Disparado quando um novo Tipo de Produto é criado. + +**Cabeçalho:** +```yaml +X-DefectDojo-Event: product_type_added +``` + +**Corpo:** +```json +{ + "description": "", + "title": "", + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### product_added + +Disparado quando um novo Produto é criado. + +**Cabeçalho:** +```yaml +X-DefectDojo-Event: product_added +``` + +**Corpo:** +```json +{ + "description": "", + "title": "", + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### engagement_added + +Disparado quando um novo Engajamento é criado. + +**Cabeçalho:** +```yaml +X-DefectDojo-Event: engagement_added +``` + +**Corpo:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### test_added + +Disparado quando um novo Teste é criado. + +**Cabeçalho:** +```yaml +X-DefectDojo-Event: test_added +``` + +**Corpo:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### scan_added / scan_added_empty + +Disparado quando um scan é importado ou reimportado. `scan_added_empty` é disparado quando uma reimportação não resulta em nenhuma alteração (nenhum achado criado ou fechado). + +**Cabeçalhos:** +```yaml +X-DefectDojo-Event: scan_added +``` +```yaml +X-DefectDojo-Event: scan_added_empty +``` + +**Corpo:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "finding_count": 4, + "findings": { + "mitigated": [ + { + "id": 233, + "severity": "Medium", + "title": "Mitigated Finding", + "url_api": "http://localhost:8080/api/v2/findings/233/", + "url_ui": "http://localhost:8080/finding/233" + } + ], + "new": [ + { + "id": 232, + "severity": "Critical", + "title": "New Finding", + "url_api": "http://localhost:8080/api/v2/findings/232/", + "url_ui": "http://localhost:8080/finding/232" + } + ], + "reactivated": [ + { + "id": 234, + "severity": "Low", + "title": "Reactivated Finding", + "url_api": "http://localhost:8080/api/v2/findings/234/", + "url_ui": "http://localhost:8080/finding/234" + } + ], + "untouched": [ + { + "id": 235, + "severity": "Info", + "title": "Untouched Finding", + "url_api": "http://localhost:8080/api/v2/findings/235/", + "url_ui": "http://localhost:8080/finding/235" + } + ] + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### ping + +Enviado durante a configuração do webhook para verificar se o endpoint está acessível. + +**Cabeçalho:** +```yaml +X-DefectDojo-Event: ping +``` + +**Corpo:** +```json +{ + "description": "Test webhook notification", + "title": "", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +## Roteiro + +Melhorias planejadas conhecidas: + +- Eventos relacionados a SLA (ainda não suportado) +- Webhooks definidos pelo usuário (atualmente restrito a administradores) +- UI aprimorada com filtragem e paginação para endpoints de webhook diff --git a/docs/content/automation/api/notification_webhooks.zh-hans.md b/docs/content/automation/api/notification_webhooks.zh-hans.md new file mode 100644 index 0000000000..9ae38149df --- /dev/null +++ b/docs/content/automation/api/notification_webhooks.zh-hans.md @@ -0,0 +1,346 @@ +--- +title: 通知 Webhook +description: 在 DefectDojo 事件发生时向外部服务器发送 HTTP webhook 通知 +weight: 8 +audience: opensource +aliases: +- /zh-hans/en/open_source/notification_webhooks/how_to +--- + +**这是一项实验性的开源功能 — 其行为可能会在未来版本中发生变化。** + +Webhook 是在特定事件发生时，从您的 DefectDojo 实例发送到用户自定义服务器的出站 HTTP 请求。 + +## Setup + +Webhook 端点由管理员配置。创建 webhook 时，DefectDojo 会发送一个 [`ping`](#ping) 事件，以验证该端点是否可访问，并返回预期的状态码。 + +## Endpoint State Transitions + +DefectDojo 会监控投递成功情况，并根据 HTTP 响应或网络故障暂时或永久禁用某个端点。管理员也可以手动重新启用该端点。 + +- **体育场形状状态**：活动（Active）— 可以发送 webhook +- **矩形状态**：非活动（Inactive）— webhook 投递将失败，且不会重试 +- **状态转换由以下因素驱动**：目标服务器返回的 HTTP 响应、celery 自动化任务，或管理员的手动操作 + +## Request Headers + +每个 webhook 请求都包含以下请求头： + +```yaml +User-Agent: DefectDojo- +X-DefectDojo-Event: +X-DefectDojo-Instance: +``` + +## Events + +### product_type_added + +在创建新的产品类型时触发。 + +**Header:** +```yaml +X-DefectDojo-Event: product_type_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### product_added + +在创建新的产品时触发。 + +**Header:** +```yaml +X-DefectDojo-Event: product_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### engagement_added + +在创建新的测试活动时触发。 + +**Header:** +```yaml +X-DefectDojo-Event: engagement_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### test_added + +在创建新的测试时触发。 + +**Header:** +```yaml +X-DefectDojo-Event: test_added +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### scan_added / scan_added_empty + +在导入或重新导入扫描时触发。当重新导入未产生任何变化（未创建或关闭任何发现项）时，将触发 `scan_added_empty`。 + +**Headers:** +```yaml +X-DefectDojo-Event: scan_added +``` +```yaml +X-DefectDojo-Event: scan_added_empty +``` + +**Body:** +```json +{ + "description": "", + "title": "", + "engagement": { + "id": 7, + "name": "notif eng", + "url_api": "http://localhost:8080/api/v2/engagements/7/", + "url_ui": "http://localhost:8080/engagement/7" + }, + "finding_count": 4, + "findings": { + "mitigated": [ + { + "id": 233, + "severity": "Medium", + "title": "Mitigated Finding", + "url_api": "http://localhost:8080/api/v2/findings/233/", + "url_ui": "http://localhost:8080/finding/233" + } + ], + "new": [ + { + "id": 232, + "severity": "Critical", + "title": "New Finding", + "url_api": "http://localhost:8080/api/v2/findings/232/", + "url_ui": "http://localhost:8080/finding/232" + } + ], + "reactivated": [ + { + "id": 234, + "severity": "Low", + "title": "Reactivated Finding", + "url_api": "http://localhost:8080/api/v2/findings/234/", + "url_ui": "http://localhost:8080/finding/234" + } + ], + "untouched": [ + { + "id": 235, + "severity": "Info", + "title": "Untouched Finding", + "url_api": "http://localhost:8080/api/v2/findings/235/", + "url_ui": "http://localhost:8080/finding/235" + } + ] + }, + "product": { + "id": 4, + "name": "notif prod", + "url_api": "http://localhost:8080/api/v2/products/4/", + "url_ui": "http://localhost:8080/product/4" + }, + "product_type": { + "id": 4, + "name": "notif prod type", + "url_api": "http://localhost:8080/api/v2/product_types/4/", + "url_ui": "http://localhost:8080/product/type/4" + }, + "test": { + "id": 90, + "title": "notif test", + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90" + }, + "url_api": "http://localhost:8080/api/v2/tests/90/", + "url_ui": "http://localhost:8080/test/90", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +--- + +### ping + +在设置 webhook 期间发送，用于验证该端点是否可访问。 + +**Header:** +```yaml +X-DefectDojo-Event: ping +``` + +**Body:** +```json +{ + "description": "Test webhook notification", + "title": "", + "user": { + "id": 1, + "email": "admin@defectdojo.local", + "first_name": "Admin", + "last_name": "User", + "username": "admin", + "url_api": "http://localhost:8080/api/v2/users/1/", + "url_ui": "http://localhost:8080/user/1" + } +} +``` + +## Roadmap + +已知的计划改进项： + +- 与 SLA 相关的事件（尚不支持） +- 用户自定义的 webhook（目前仅限管理员使用） +- 改进 webhook 端点的用户界面，加入过滤和分页功能 diff --git a/docs/content/automation/api/rate_limiting.it.md b/docs/content/automation/api/rate_limiting.it.md new file mode 100644 index 0000000000..433a485588 --- /dev/null +++ b/docs/content/automation/api/rate_limiting.it.md @@ -0,0 +1,45 @@ +--- +title: Limitazione della frequenza +description: Configura la limitazione della frequenza nella pagina di accesso per + mitigare gli attacchi di forza bruta +weight: 4 +audience: opensource +aliases: +- /it/en/open_source/rate_limiting +--- + +DefectDojo include la limitazione della frequenza nella pagina di accesso per proteggere dagli attacchi di forza bruta, basata su [Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/index.html). + +## Configurazione + +La limitazione della frequenza viene configurata tramite le seguenti impostazioni (vedi [Configurazione](/get_started/open_source/configuration/) per come applicarle): + +```python +DD_RATE_LIMITER_ENABLED=(bool, True), +DD_RATE_LIMITER_RATE=(str, '5/m'), +DD_RATE_LIMITER_BLOCK=(bool, True), +DD_RATE_LIMITER_ACCOUNT_LOCKOUT=(bool, True), +``` + +### Frequenza limite (`DD_RATE_LIMITER_RATE`) + +Imposta la frequenza con cui le richieste verranno limitate. Unità supportate: + +- Secondi: `1s` +- Minuti: `5m` +- Ore: `100h` +- Giorni: `2400d` + +Consulta la [documentazione di Django Ratelimit sulle frequenze](https://django-ratelimit.readthedocs.io/en/stable/rates.html) per opzioni di configurazione estese. + +### Blocco delle richieste (`DD_RATE_LIMITER_BLOCK`) + +Per impostazione predefinita, la limitazione della frequenza registra le violazioni ma non blocca le richieste. Impostando `DD_RATE_LIMITER_BLOCK` su `True` verranno bloccate attivamente tutte le richieste in arrivo una volta superata la frequenza configurata. + +### Blocco account (`DD_RATE_LIMITER_ACCOUNT_LOCKOUT`) + +Se abilitato, un utente i cui tentativi di accesso attivano il limite di frequenza dovrà reimpostare la propria password prima di poter accedere di nuovo. Questo riduce il rischio di compromissione delle credenziali durante un attacco di forza bruta. + +## Comportamento multi-processo + +Quando si esegue con più processi `uwsgi`, il pacchetto di limitazione della frequenza utilizza una cache basata sulla memoria locale a ciascun processo. I contatori del limite di frequenza non sono condivisi tra i processi in questa configurazione predefinita. diff --git a/docs/content/automation/api/rate_limiting.pt-br.md b/docs/content/automation/api/rate_limiting.pt-br.md new file mode 100644 index 0000000000..46371053f6 --- /dev/null +++ b/docs/content/automation/api/rate_limiting.pt-br.md @@ -0,0 +1,45 @@ +--- +title: Limitação de taxa +description: Configure a limitação de taxa na página de login para mitigar ataques + de força bruta +weight: 4 +audience: opensource +aliases: +- /pt-br/en/open_source/rate_limiting +--- + +O DefectDojo inclui limitação de taxa (rate limiting) na página de login para proteger contra ataques de força bruta, com tecnologia do [Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/index.html). + +## Configuração + +A limitação de taxa é configurada por meio das seguintes definições (veja [Configuration](/get_started/open_source/configuration/) para saber como aplicá-las): + +```python +DD_RATE_LIMITER_ENABLED=(bool, True), +DD_RATE_LIMITER_RATE=(str, '5/m'), +DD_RATE_LIMITER_BLOCK=(bool, True), +DD_RATE_LIMITER_ACCOUNT_LOCKOUT=(bool, True), +``` + +### Rate Limit (`DD_RATE_LIMITER_RATE`) + +Define a frequência com que as requisições serão limitadas. Unidades suportadas: + +- Segundos: `1s` +- Minutos: `5m` +- Horas: `100h` +- Dias: `2400d` + +Consulte a [documentação de taxas do Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/rates.html) para opções de configuração estendidas. + +### Block Requests (`DD_RATE_LIMITER_BLOCK`) + +Por padrão, a limitação de taxa registra as ocorrências, mas não bloqueia as requisições. Definir `DD_RATE_LIMITER_BLOCK` como `True` bloqueará ativamente todas as requisições recebidas assim que a taxa configurada for excedida. + +### Account Lockout (`DD_RATE_LIMITER_ACCOUNT_LOCKOUT`) + +Quando habilitado, um usuário cujas tentativas de login acionarem o limite de taxa precisará redefinir sua senha antes de conseguir fazer login novamente. Isso reduz o risco de comprometimento de credenciais durante um ataque de força bruta. + +## Comportamento com múltiplos processos + +Ao executar com múltiplos processos `uwsgi`, o pacote de limitação de taxa usa um cache baseado em memória, local a cada processo. Os contadores de limite de taxa não são compartilhados entre processos nessa configuração padrão. diff --git a/docs/content/automation/api/rate_limiting.zh-hans.md b/docs/content/automation/api/rate_limiting.zh-hans.md new file mode 100644 index 0000000000..6f6ada5a4f --- /dev/null +++ b/docs/content/automation/api/rate_limiting.zh-hans.md @@ -0,0 +1,44 @@ +--- +title: 速率限制 +description: 在登录页面配置速率限制以缓解暴力破解攻击 +weight: 4 +audience: opensource +aliases: +- /zh-hans/en/open_source/rate_limiting +--- + +DefectDojo 内置了登录页面速率限制功能，以防范暴力破解攻击，该功能由 [Django Ratelimit](https://django-ratelimit.readthedocs.io/en/stable/index.html) 提供支持。 + +## Configuration + +速率限制通过以下设置进行配置（有关如何应用这些设置，请参阅[配置](/get_started/open_source/configuration/)）： + +```python +DD_RATE_LIMITER_ENABLED=(bool, True), +DD_RATE_LIMITER_RATE=(str, '5/m'), +DD_RATE_LIMITER_BLOCK=(bool, True), +DD_RATE_LIMITER_ACCOUNT_LOCKOUT=(bool, True), +``` + +### Rate Limit (`DD_RATE_LIMITER_RATE`) + +设置限制请求频率的方式。支持的单位有： + +- 秒：`1s` +- 分钟：`5m` +- 小时：`100h` +- 天：`2400d` + +有关更多配置选项，请参阅 [Django Ratelimit rates 文档](https://django-ratelimit.readthedocs.io/en/stable/rates.html)。 + +### Block Requests (`DD_RATE_LIMITER_BLOCK`) + +默认情况下，速率限制只会记录违规行为，而不会阻止请求。将 `DD_RATE_LIMITER_BLOCK` 设置为 `True` 后，一旦超过所配置的速率，就会主动阻止所有传入请求。 + +### Account Lockout (`DD_RATE_LIMITER_ACCOUNT_LOCKOUT`) + +启用后，若某个用户的登录尝试触发了速率限制，该用户必须重置密码才能再次登录。这可以降低在暴力破解攻击期间凭据被攻破的风险。 + +## Multi-Process Behaviour + +在运行多个 `uwsgi` 进程时，该速率限制软件包使用的是每个进程本地的基于内存的缓存。在此默认配置下，速率限制计数器不会跨进程共享。 diff --git a/docs/content/automation/rules_engine/_index.it.md b/docs/content/automation/rules_engine/_index.it.md new file mode 100644 index 0000000000..14d1a6ce7b --- /dev/null +++ b/docs/content/automation/rules_engine/_index.it.md @@ -0,0 +1,17 @@ +--- +title: Rules Engine +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 98 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +--- diff --git a/docs/content/automation/rules_engine/_index.pt-br.md b/docs/content/automation/rules_engine/_index.pt-br.md new file mode 100644 index 0000000000..14d1a6ce7b --- /dev/null +++ b/docs/content/automation/rules_engine/_index.pt-br.md @@ -0,0 +1,17 @@ +--- +title: Rules Engine +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 98 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +--- diff --git a/docs/content/automation/rules_engine/_index.zh-hans.md b/docs/content/automation/rules_engine/_index.zh-hans.md new file mode 100644 index 0000000000..7bc99259b3 --- /dev/null +++ b/docs/content/automation/rules_engine/_index.zh-hans.md @@ -0,0 +1,17 @@ +--- +title: 规则引擎 +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 98 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +--- diff --git a/docs/content/automation/rules_engine/about.it.md b/docs/content/automation/rules_engine/about.it.md new file mode 100644 index 0000000000..38121153e8 --- /dev/null +++ b/docs/content/automation/rules_engine/about.it.md @@ -0,0 +1,126 @@ +--- +title: Automazione di Rules Engine +description: Come utilizzare l'automazione di Rules Engine +weight: 1 +audience: pro +aliases: +- /it/en/customize_dojo/rules_engine +--- + +Nota: Rules Engine è una funzionalità disponibile solo in DefectDojo Pro. + +Il Rules Engine di DefectDojo consente di creare flussi di lavoro personalizzati e azioni collettive per gestire i Finding e altri oggetti. Rules Engine consente di creare azioni automatizzate che vengono attivate quando un oggetto corrisponde a una Regola. + +Rules Engine è accessibile solo tramite la [Pro UI](/get_started/about/ui_pro_vs_os/). + +**Cerchi l'editor a grafo?** [Rules Engine 2.0](/automation/rules_engine_2/about/) costruisce l'automazione come grafi di nodi visuali, e aggiunge la ramificazione, azioni in uscita come ticket e messaggi, tracce per ogni run e un registro delle consegne. I due motori funzionano in parallelo, e le regole esistenti possono essere [convertite](/automation/rules_engine_2/converting_from_rules_engine/). + +## Abilitare Rules Engine + +Rules Engine è in versione Beta ed è disattivato per impostazione predefinita. Un superuser può attivarlo da **Settings > Feature Flags**, sia sulle istanze Cloud sia On-Premise. Vedere [Feature Flags](/admin/feature_flags/pro__feature_flags/). + +Attualmente le Regole possono essere create solo per i Finding, ma in futuro saranno supportati altri tipi di oggetto. + +Le Regole possono essere attivate manualmente dalla pagina **All Rules**, oppure pianificate per l'esecuzione automatica secondo una ricorrenza. Quando una regola viene attivata, viene applicata a tutti i Finding esistenti che corrispondono alle condizioni di filtro impostate. + +## Possibili azioni delle regole +Ogni Regola può applicare una o più di queste modifiche a un Finding quando viene attivata con successo (ossia corrisponde alle condizioni di Filtro impostate). + +### Modifiche ai campi +* **Impostare un campo** su un Finding, tra cui Title, Description, Severity, CVSSv3 Vector, Active, Verified, Risk Accepted, False Positive, Mitigated +* **Aggiungere testo in coda o in testa** al Title o alla Description di un Finding +* **Impostare Priority** — sostituisce il valore di Priority calcolato su un Finding (sovrascrive il calcolo automatico della priorità) +* **Impostare Risk** — sostituisce il livello di Risk calcolato su un Finding (sovrascrive il calcolo automatico del rischio) +* **Sommare, sottrarre, moltiplicare o dividere** il valore di Priority su un Finding per un numero indicato + +### Assegnazioni e proprietà +* **Impostare un Utente per la revisione** di un Finding +* **Assegnare un Gruppo come proprietario** di un Finding +* **Impostare una Mitigation Policy** su un Finding — assegna al Finding una Mitigation Policy preconfigurata +* **Aggiungere a Risk Acceptance** — aggiunge un Finding a un record di Risk Acceptance esistente (imposta risk_accepted=True, active=False, e gestisce l'integrazione con Jira e gli stati degli endpoint) + +### Tag, note e avvisi +* **Aggiungere Tag** a un Finding +* **Aggiungere una Nota** a un Finding +* **Creare un Alert** in DefectDojo con testo personalizzato + +### Condizioni di filtro +Le Regole vengono attivate automaticamente quando un Finding soddisfa specifiche condizioni di Filtro. Per maggiori informazioni sui Filtri utilizzabili per creare Azioni delle Regole, vedere la pagina [Filter Index](/navigation/pro__filter_index). + +## Creare una nuova Regola +Avvia questo processo dalla pagina New Rule. Nella [Pro UI](/get_started/about/ui_pro_vs_os/), sotto **Manage Category**, espandi il menu a tendina **Rules Engine** e fai clic su **+ New Rule**. + +![image](images/rules_engine_1.png) + +### Passaggio 1: assegna un'etichetta alla tua Regola +Inserisci un'etichetta come identificatore per la nuova regola, quindi fai clic su Next. + +![image](images/rules_engine_2.png) + +### Passaggio 2: imposta le condizioni di attivazione con un Filtro +Vedrai una tabella All Findings. Utilizzando la tabella All Findings, imposta le condizioni di Filtro per filtrare l'insieme di Finding a cui vuoi che la tua regola si applichi. Per maggiori informazioni sull'applicazione dei Filtri a una tabella, vedere [la nostra guida alla Pro UI](/get_started/about/ui_pro_vs_os/#navigational-changes). + +La tabella mostrerà in anteprima l'elenco dei Finding esistenti che hai filtrato. + +Ad esempio, in questa schermata stiamo filtrando tutti i Finding che si trovano in 'Product One'. Una volta applicato questo filtro (facendo clic al di fuori del menu Filters), verrà aggiunto al nostro elenco di Filtri applicabili. + +![image](images/rules_engine_3.png) + +Nella schermata precedente, tutti i Finding che si trovano nel Prodotto 'Product One' subiranno le azioni impostate. + +Una volta definito l'insieme di Filtri che vuoi applicare, fai clic sul pulsante Next. + +### Passaggio 3: imposta le Azioni della Regola +Dal menu a tendina **Action**, seleziona l'Azione che vuoi applicare a un Finding che corrisponde a tutti i filtri del Passaggio 2. È possibile applicare più Azioni. + +Puoi impostare dei Valori Condizionali aggiuntivi che permettono di eseguire ulteriori azioni se vengono soddisfatti determinati criteri. + +![image](images/rules_engine_4.png) + + +Ad esempio, nella schermata precedente abbiamo impostato 4 Azioni della Regola. Due di queste azioni sono Condizionali. + +Tutti i Finding che corrispondono alle condizioni di filtro attiveranno queste Azioni non condizionali: + +* Il Finding verrà assegnato al gruppo utenti 'Group 1' +* Il Finding verrà taggato con `all_group_1` + +Eventuali Finding che corrispondono alle condizioni di filtro, più queste condizioni **aggiuntive**, attiveranno queste Azioni Condizionali in aggiunta alle due Azioni non condizionali elencate sopra: + +* **se il Finding ha Severity Critical**, verrà taggato con `critical_group_1`. +* **se il Finding ha Severity High**, verrà taggato con `high_group_1`. + +### Passaggio 4 - Anteprima della tua Regola + +La Rule Preview mostra tutti i Finding che verranno modificati da questa regola una volta eseguita, insieme a un'anteprima delle Azioni intraprese. Verifica di essere soddisfatto delle modifiche proposte, quindi fai clic su Submit per salvare la tua regola. + +Se ritieni che questa regola non sia stata applicata correttamente, puoi selezionare il pulsante Back e tornare a uno qualsiasi dei passaggi precedenti. + +![image](images/rules_engine_5.png) + +Ad esempio, nella schermata precedente abbiamo un elenco di Finding che verranno interessati dalla Regola una volta eseguita. Possiamo vedere che nuovi Tag e Owner verranno applicati a ciascuno di questi Finding dalle colonne a destra dell'elenco dei Finding. + +Ti verrà chiesto nuovamente di confermare che vuoi creare la tua Regola. Nota che **la Regola non verrà applicata immediatamente** e deve essere attivata manualmente. + +## Eseguire una Regola +Dalla pagina All Rules, puoi selezionare una Regola che desideri eseguire. Fai clic sul titolo della regola per visualizzarla in dettaglio. + +![image](images/rules_engine_6.png) + +In questa pagina, puoi vedere informazioni dettagliate su questa regola sotto **Metadata**, incluse informazioni su quando la regola è stata attivata l'ultima volta. Puoi anche vedere un'anteprima dei Finding che verranno interessati da una nuova esecuzione di questa Regola, sotto **Rule Preview**. + +Per eseguire la Regola, fai clic sul pulsante verde Run Rule. Dopo aver confermato che vuoi eseguire la regola, apparirà un messaggio che indica che la regola è in coda per l'esecuzione in background. + +Una volta che la Regola ha terminato con successo l'esecuzione, il numero di Items Changed verrà aggiornato nella sezione Rule Metadata della descrizione della Regola. + +## Riferimento ai metadati della Regola +* **Rule For**: gli oggetti governati dalla Regola. +* **Rule Name**: il nome della Regola. +* **Filters**: il numero di Filtri applicati da questa Regola. +* **Actions**: il numero di Azioni intraprese da questa Regola. +* **Owner**: l'Utente che ha creato questa Regola. +* **Status**: il resoconto dello Status dell'ultima esecuzione di questa Regola. + 'E' = 'Error', 'R' = 'Running', 'S' = 'Success'. +* **Last Run**: il timestamp dell'ultima esecuzione di questa Regola. +* **Items Changed:** conteggio degli oggetti modificati nell'ultima esecuzione della regola. +* **Items Skipped:** conteggio degli oggetti saltati nell'ultima esecuzione della regola. Se un oggetto filtrato corrisponde già al 'risultato' di un'Azione della Regola applicata su di esso (ad esempio, se ha già i Tag che verrebbero applicati da un'Azione della Regola), l'oggetto verrà semplicemente saltato. diff --git a/docs/content/automation/rules_engine/about.pt-br.md b/docs/content/automation/rules_engine/about.pt-br.md new file mode 100644 index 0000000000..fb7f2fc8d2 --- /dev/null +++ b/docs/content/automation/rules_engine/about.pt-br.md @@ -0,0 +1,126 @@ +--- +title: Automação do Rules Engine +description: Trabalhando com a automação do Rules Engine +weight: 1 +audience: pro +aliases: +- /pt-br/en/customize_dojo/rules_engine +--- + +Observação: o Rules Engine é um recurso exclusivo do DefectDojo Pro. + +O Rules Engine do DefectDojo permite construir workflows personalizados e ações em massa para tratar Findings e outros objetos. O Rules Engine permite construir ações automatizadas que são disparadas quando um objeto corresponde a uma Regra. + +O Rules Engine só pode ser acessado através da [Pro UI](/get_started/about/ui_pro_vs_os/). + +**Procurando o editor de grafos?** O [Rules Engine 2.0](/automation/rules_engine_2/about/) constrói automações como grafos visuais de nós, e adiciona ramificações, ações de saída como tickets e mensagens, rastros por execução e um livro-razão de entregas. Os dois mecanismos funcionam lado a lado, e regras existentes podem ser [convertidas](/automation/rules_engine_2/converting_from_rules_engine/). + +## Habilitando o Rules Engine + +O Rules Engine está em Beta e vem desativado por padrão. Um superusuário pode ativá-lo em **Settings > Feature Flags**, tanto em instâncias Cloud quanto On-Premise. Veja [Feature Flags](/admin/feature_flags/pro__feature_flags/). + +Atualmente, Regras só podem ser criadas para Findings, mas mais tipos de objeto serão suportados no futuro. + +As Regras podem ser disparadas manualmente na página **All Rules**, ou agendadas para rodar automaticamente em um cronograma recorrente. Quando uma regra é disparada, ela será aplicada a todos os Findings existentes que correspondam às condições de filtro definidas. + +## Ações de Regra possíveis +Cada Regra pode aplicar uma ou mais destas alterações a um Finding quando é disparada com sucesso (ou seja, corresponde às condições de Filtro definidas). + +### Modificações de campo +* **Definir um campo** em um Finding, incluindo Title, Description, Severity, CVSSv3 Vector, Active, Verified, Risk Accepted, False Positive, Mitigated +* **Anexar ou prefixar texto** ao Title ou Description de um Finding +* **Set Priority** — sobrescreve o valor de Priority calculado em um Finding (sobrepõe o cálculo automático de prioridade) +* **Set Risk** — sobrescreve o nível de Risk calculado em um Finding (sobrepõe o cálculo automático de risco) +* **Somar, Subtrair, Multiplicar ou Dividir** o valor de Priority em um Finding por um número informado + +### Atribuições e propriedade +* **Definir um usuário para revisar** um Finding +* **Atribuir um Grupo como Owners** de um Finding +* **Definir uma Mitigation Policy** em um Finding — atribui uma Mitigation Policy pré-configurada ao Finding +* **Adicionar a Risk Acceptance** — adiciona um Finding a um registro de Risk Acceptance existente (define risk_accepted=True, active=False, e trata a integração com Jira e os status de endpoint) + +### Tags, Notas e Alertas +* **Adicionar Tags** a um Finding +* **Adicionar uma Nota** a um Finding +* **Criar um Alerta** no DefectDojo com texto personalizado + +### Condições de filtro +As Regras são disparadas automaticamente quando um Finding atende a condições de Filtro específicas. Para mais informações sobre os Filtros que podem ser usados para criar Ações de Regra, veja a página [Filter Index](/navigation/pro__filter_index). + +## Criando uma nova Regra +Inicie este processo pela página New Rule. Na [Pro UI](/get_started/about/ui_pro_vs_os/), em **Manage Category**, expanda o menu suspenso **Rules Engine** e clique em **+ New Rule**. + +![image](images/rules_engine_1.png) + +### Etapa 1: Nomeie sua Regra +Digite um Label como identificador da nova regra e clique em Next. + +![image](images/rules_engine_2.png) + +### Etapa 2: Defina as condições de disparo com um Filtro +Você verá uma tabela All Findings. Usando essa tabela, defina as condições de Filtro para filtrar o conjunto de Findings ao qual sua regra deve se aplicar. Para mais informações sobre como aplicar Filtros a uma tabela, veja [nosso guia da Pro UI](/get_started/about/ui_pro_vs_os/#navigational-changes). + +A tabela mostrará uma prévia da lista de Findings existentes que você filtrou. + +Por exemplo, nesta captura de tela estamos filtrando todos os Findings que estão em 'Product One'. Depois de aplicarmos este filtro (clicando fora do menu de Filtros), ele será adicionado à nossa lista de Filtros aplicáveis. + +![image](images/rules_engine_3.png) + +Na captura de tela acima, todos os Findings que estão no Produto 'Product One' terão ações aplicadas a eles. + +Depois de ter o conjunto de Filtros que deseja aplicar, clique no botão Next. + +### Etapa 3: Defina as Ações da Regra +No menu suspenso **Action**, selecione a Ação que deseja aplicar a um Finding que corresponda a todos os filtros da Etapa 2. Várias Ações podem ser aplicadas. + +Você pode definir Valores Condicionais adicionais, que permitem executar ações extras caso certos critérios sejam atendidos. + +![image](images/rules_engine_4.png) + + +Por exemplo, na captura de tela acima temos 4 Ações de Regra definidas. Duas dessas ações são Condicionais. + +Todos os Findings que correspondem às condições de filtro disparam estas Ações Não Condicionais: + +* O Finding será atribuído ao grupo de usuários 'Group 1' +* O Finding será marcado com a tag `all_group_1` + +Quaisquer Findings que correspondam às condições de filtro, mais estas condições **adicionais**, disparam estas Ações Condicionais, além das duas Ações Não Condicionais listadas acima: + +* **se o Finding tiver Severidade Crítica**, ele será marcado com a tag `critical_group_1`. +* **se o Finding tiver Severidade Alta**, ele será marcado com a tag `high_group_1`. + +### Etapa 4 - Visualize a prévia da sua Regra + +O Rule Preview exibe todos os Findings que serão alterados por esta regra quando ela for executada, junto com uma prévia das Ações realizadas. Confirme que está satisfeito com as alterações propostas e clique em Submit para salvar sua regra. + +Se você acredita que esta regra não foi aplicada corretamente, pode clicar no botão Back e voltar a qualquer uma das etapas anteriores. + +![image](images/rules_engine_5.png) + +Por exemplo, na captura de tela acima temos uma lista de Findings que serão afetados pela Regra quando ela for executada. Podemos ver que novas Tags e Owners serão aplicados a cada um desses Findings, nas colunas à direita da lista de Findings. + +Você será solicitado novamente a confirmar que deseja criar sua Regra. Observe que a **Regra não será aplicada imediatamente**, e deve ser disparada manualmente. + +## Executando uma Regra +Na página All Rules, você pode selecionar a Regra que deseja executar. Clique no título da regra para vê-la em mais detalhes. + +![image](images/rules_engine_6.png) + +Nesta página, você pode ver informações detalhadas sobre esta regra em **Metadata**, incluindo informações sobre quando a regra foi disparada pela última vez. Você também pode ver uma prévia de quaisquer Findings que serão afetados por uma nova execução desta Regra, logo abaixo de **Rule Preview**. + +Para executar a Regra, clique no botão verde Run Rule. Depois de confirmar que deseja executar a regra, aparecerá uma mensagem informando que a regra foi enfileirada para execução em segundo plano. + +Assim que a Regra terminar de ser executada com sucesso, o número de Items Changed será atualizado na seção Rule Metadata da descrição da Regra. + +## Referência de Rule Metadata +* **Rule For**: os objetos governados pela Regra. +* **Rule Name**: o nome da Regra. +* **Filters**: o número de Filtros aplicados por esta Regra. +* **Actions**: o número de Ações realizadas por esta Regra. +* **Owner**: o Usuário que criou esta Regra. +* **Status**: o relatório de Status da última vez que esta Regra foi executada. + 'E' = 'Error', 'R' = 'Running', 'S' = 'Success'. +* **Last Run**: o timestamp da última vez que esta Regra foi executada. +* **Items Changed:** contagem de objetos que foram alterados na última execução da regra. +* **Items Skipped:** contagem de objetos que foram ignorados na última execução da regra. Se um objeto filtrado já corresponde ao 'resultado' de uma Ação de Regra aplicada a ele (por exemplo, se ele já tem as Tags que seriam aplicadas por uma Ação de Regra), o objeto simplesmente será ignorado. diff --git a/docs/content/automation/rules_engine/about.zh-hans.md b/docs/content/automation/rules_engine/about.zh-hans.md new file mode 100644 index 0000000000..efabbc53df --- /dev/null +++ b/docs/content/automation/rules_engine/about.zh-hans.md @@ -0,0 +1,126 @@ +--- +title: 规则引擎自动化 +description: 使用规则引擎自动化 +weight: 1 +audience: pro +aliases: +- /zh-hans/en/customize_dojo/rules_engine +--- + +注意：规则引擎是 DefectDojo Pro 专属功能。 + +DefectDojo 的规则引擎允许您构建自定义工作流和批量操作，用于处理发现项及其他对象。规则引擎允许您构建当某个对象匹配某条规则时被触发的自动化操作。 + +规则引擎只能通过 [Pro UI](/get_started/about/ui_pro_vs_os/) 访问。 + +**在寻找图形编辑器？** [规则引擎 2.0](/automation/rules_engine_2/about/) 以可视化节点图的形式构建自动化流程，并新增了分支、诸如工单和消息等出站操作、按运行记录的执行痕迹，以及投递台账。两套引擎并行运行，现有规则也可以[转换](/automation/rules_engine_2/converting_from_rules_engine/)到新引擎。 + +## 启用规则引擎 + +规则引擎目前处于测试版，默认关闭。超级用户可以在云端实例和本地部署实例上，通过**设置 > 功能开关**将其启用。参见[功能开关](/admin/feature_flags/pro__feature_flags/)。 + +目前，规则只能针对发现项创建，未来将支持更多对象类型。 + +规则可以在**所有规则**页面手动触发，也可以设置为按周期性排程自动运行。规则被触发后，会应用于所有匹配所设筛选条件的现有发现项。 + +## 可用的规则操作 +每条规则在成功触发时（即匹配所设的筛选条件时），可以对一个发现项应用以下一项或多项更改。 + +### 字段修改 +* **设置发现项的字段**，包括标题、描述、严重程度、CVSSv3 向量、活动、已验证、风险已接受、误报、已缓解 +* 在发现项的标题或描述中**追加或前置文本** +* **设置优先级** — 覆盖发现项上计算得出的优先级值（覆盖自动优先级计算） +* **设置风险** — 覆盖发现项上计算得出的风险级别（覆盖自动风险计算） +* 按给定的数值对发现项的优先级值进行**加、减、乘或除**运算 + +### 分配与归属 +* **设置负责复核发现项的用户** +* **将某个组指定为发现项的所有者** +* 在发现项上**设置缓解策略** — 为发现项分配一个预先配置好的缓解策略 +* **添加到风险接受** — 将发现项添加到现有的风险接受记录中（设置 risk_accepted=True、active=False，并处理 Jira 集成和端点状态） + +### 标签、备注和提醒 +* 为发现项**添加标签** +* 为发现项**添加备注** +* 在 DefectDojo 中使用自定义文本**创建提醒** + +### 筛选条件 +当一个发现项满足特定的筛选条件时，规则会自动被触发。有关可用于创建规则操作的筛选条件的更多信息，请参阅[筛选条件索引](/navigation/pro__filter_index)页面。 + +## 创建新规则 +从"新建规则"页面开始此流程。在 [Pro UI](/get_started/about/ui_pro_vs_os/) 中，在**管理类别**下，展开**规则引擎**下拉菜单，然后点击**+ 新建规则**。 + +![image](images/rules_engine_1.png) + +### 步骤 1：为规则命名 +输入一个标签，作为新规则的标识符，然后点击"下一步"。 + +![image](images/rules_engine_2.png) + +### 步骤 2：使用筛选条件设置触发条件 +您将看到一张"所有发现项"表格。使用该表格设置筛选条件，以筛选出您希望规则作用于的发现项集合。有关如何为表格应用筛选条件的更多信息，请参阅[我们的 Pro UI 指南](/get_started/about/ui_pro_vs_os/#navigational-changes)。 + +该表格会预览您筛选出的现有发现项列表。 + +例如，在这张截图中，我们正在筛选出所有属于"Product One"的发现项。一旦我们应用此筛选条件（通过点击筛选条件菜单外部），它就会被添加到我们的适用筛选条件列表中。 + +![image](images/rules_engine_3.png) + +在上面的截图中，所有属于产品"Product One"的发现项都将被执行相应操作。 + +设置好您想要应用的一组筛选条件后，点击"下一步"按钮。 + +### 步骤 3：设置规则操作 +从**操作**下拉菜单中，选择您希望应用于符合步骤 2 中所有筛选条件的发现项的操作。可以应用多个操作。 + +您还可以设置额外的条件值，以便在满足特定条件时执行额外的操作。 + +![image](images/rules_engine_4.png) + + +例如，在上面的截图中，我们设置了 4 个规则操作，其中两个是条件性操作。 + +所有符合筛选条件的发现项都会触发以下非条件性操作： + +* 该发现项将被分配给用户组"Group 1" +* 该发现项将被打上 `all_group_1` 标签 + +除了上面列出的两个非条件性操作之外，任何同时满足筛选条件和以下**附加**条件的发现项，还会触发这些条件性操作： + +* **如果发现项的严重程度为严重**，将被打上 `critical_group_1` 标签。 +* **如果发现项的严重程度为高**，将被打上 `high_group_1` 标签。 + +### 步骤 4 - 预览您的规则 + +"规则预览"会显示此规则一旦运行后将会更改的所有发现项，以及将要执行的操作的预览。确认您对拟议的更改感到满意后，点击"提交"以保存您的规则。 + +如果您认为此规则没有被正确应用，可以点击"返回"按钮，回到之前的任意一个步骤。 + +![image](images/rules_engine_5.png) + +例如，在上面的截图中，我们看到了一份此规则一旦运行后将受影响的发现项列表。从发现项列表右侧的列中可以看到，新的标签和所有者将被应用到这些发现项上。 + +系统会再次提示您确认要创建此规则。请注意，**该规则不会立即生效**，必须手动触发。 + +## 运行规则 +在"所有规则"页面中，您可以选择希望运行的规则。点击规则标题即可查看其详细信息。 + +![image](images/rules_engine_6.png) + +在此页面上，您可以在**元数据**下查看有关此规则的详细信息，包括该规则上次被触发的时间。您还可以在**规则预览**下查看此规则新一次运行将影响到的发现项预览。 + +要运行此规则，请点击绿色的"运行规则"按钮。确认要运行该规则后，会出现一条消息，提示该规则已排队，将在后台运行。 + +该规则成功运行完成后，规则描述中"规则元数据"部分的"已更改项目数"会随之更新。 + +## 规则元数据参考 +* **规则对象**：该规则所管理的对象。 +* **规则名称**：该规则的名称。 +* **筛选条件**：该规则所应用的筛选条件数量。 +* **操作**：该规则所执行的操作数量。 +* **所有者**：创建该规则的用户。 +* **状态**：该规则上一次执行时的状态报告。 + "E" = "Error"（错误），"R" = "Running"（运行中），"S" = "Success"（成功）。 +* **上次运行**：该规则上一次执行的时间戳。 +* **已更改项目数：** 上一次规则执行中被更改的对象数量。 +* **已跳过项目数：** 上一次规则执行中被跳过的对象数量。如果一个被筛选出的对象已经符合某个规则操作作用于它的"结果"（例如，它已经具有某个规则操作将要添加的标签），该对象就会被直接跳过。 diff --git a/docs/content/automation/rules_engine/scheduling.it.md b/docs/content/automation/rules_engine/scheduling.it.md new file mode 100644 index 0000000000..feae36b8d2 --- /dev/null +++ b/docs/content/automation/rules_engine/scheduling.it.md @@ -0,0 +1,55 @@ +--- +title: Pianificazione delle regole +description: Esegui automaticamente le regole di Rules Engine secondo una pianificazione + ricorrente o una tantum +weight: 2 +audience: pro +--- + +Nota: la pianificazione di Rules Engine è una funzionalità disponibile solo in DefectDojo Pro. + +Le Regole possono essere pianificate per l'esecuzione automatica invece di essere attivate manualmente ogni volta. Una regola pianificata verrà eseguita su tutti i Finding che corrispondono alle sue condizioni di filtro, all'orario configurato. + +La pianificazione è disattivata per impostazione predefinita e viene abilitata per singola istanza da DefectDojo, anziché dalla pagina Feature Flags. Contatta [DefectDojo Support](mailto:support@defectdojo.com) per far attivare lo **Scheduling Service**; l'opzione **Schedule Rule** compare una volta attivato. Vedere [Feature Flags](/admin/feature_flags/pro__feature_flags/) per come vengono mostrate le funzionalità che DefectDojo gestisce a livello centrale. + +L'utente che imposta la pianificazione deve disporre del permesso di configurazione **Change Scheduling Service Schedule**. + +## Tipi di pianificazione + +### Esecuzione singola + +Una pianificazione Single Run esegue la regola una sola volta in una data e ora specifiche. Al termine dell'esecuzione, la pianificazione non viene ripetuta. + +### Esecuzione ripetuta + +Una pianificazione Repeated Run consente di attivare una regola su base ricorrente — ad esempio, ogni giorno alle 9:00, oppure ogni lunedì alle 15:00. + +**Nota:** le pianificazioni di Rules Engine sono limitate ai quarti d'ora. Il campo dei minuti di una pianificazione cron deve essere uno tra: **0, 15, 30 o 45**. Altri valori dei minuti non sono ammessi. + +Esempi di pianificazioni valide: +- Ogni ora, allo scoccare dell'ora: `0 * * * *` +- Ogni giorno alle 9:15: `15 9 * * *` +- Ogni lunedì alle 15:00: `0 15 * * 1` +- Ogni 15 minuti: `0,15,30,45 * * * *` + +## Creare una pianificazione per una Regola + +1. Vai alla pagina **All Rules** dal menu **Rules Engine** nella barra laterale. +2. Trova la regola che vuoi pianificare e apri il suo menu delle azioni (**⋮**). +3. Fai clic su **Schedule Rule**. Questa opzione è visibile solo se lo Scheduling Service è abilitato e disponi del permesso richiesto. +4. Nella finestra modale **Schedule Rule**, compila i seguenti campi: + +| Campo | Descrizione | +|---|---| +| **Name** | Un nome univoco per questa pianificazione (obbligatorio, massimo 100 caratteri). | +| **Description** | Descrizione facoltativa dello scopo della pianificazione. | +| **Trigger Type** | Scegli **Single Run** per un'esecuzione una tantum, oppure **Repeated Run** per una pianificazione cron ricorrente. | +| **Frequency** | Per Repeated Run: usa il generatore cron per selezionare il periodo (orario, giornaliero, settimanale, ecc.) e i valori specifici di minuto, ora e giorno. Per Single Run: seleziona una data e un'ora usando il selettore di data. | +| **Enable Schedule** | Attiva o disattiva la pianificazione. Una pianificazione disattivata non verrà eseguita finché non viene riattivata. | + +5. Fai clic su **Submit** per salvare la pianificazione. La regola verrà eseguita automaticamente al prossimo orario pianificato. + + +## Permessi + +L'accesso alla pianificazione all'interno di Rules Engine richiede i permessi Superuser oppure l'appropriato Permesso di Configurazione. Vedere [User Permission Chart](/admin/user_management/user_permission_chart) per i dettagli. diff --git a/docs/content/automation/rules_engine/scheduling.pt-br.md b/docs/content/automation/rules_engine/scheduling.pt-br.md new file mode 100644 index 0000000000..02a3d6064e --- /dev/null +++ b/docs/content/automation/rules_engine/scheduling.pt-br.md @@ -0,0 +1,55 @@ +--- +title: Agendamento de regras +description: Execute regras do Rules Engine automaticamente em um agendamento recorrente + ou único +weight: 2 +audience: pro +--- + +Observação: o Agendamento do Rules Engine é um recurso exclusivo do DefectDojo Pro. + +As Regras podem ser agendadas para rodar automaticamente, em vez de serem disparadas manualmente todas as vezes. Uma regra agendada será executada contra todos os Findings que correspondam às suas condições de filtro no horário configurado. + +O agendamento vem desativado por padrão e é habilitado por instância pelo DefectDojo, em vez de pela página Feature Flags. Entre em contato com o [Suporte DefectDojo](mailto:support@defectdojo.com) para que o **Scheduling Service** seja ativado; a opção **Schedule Rule** aparece assim que ele estiver ativo. Veja [Feature Flags](/admin/feature_flags/pro__feature_flags/) para saber como são exibidos os recursos que o DefectDojo gerencia de forma centralizada. + +O usuário que configurar o agendamento precisa ter a permissão de configuração **Change Scheduling Service Schedule**. + +## Tipos de agendamento + +### Single Run + +Um agendamento Single Run executa a regra uma única vez, em uma data e hora específicas. Depois que a execução é concluída, o agendamento não se repete. + +### Repeated Run + +Um agendamento Repeated Run permite disparar uma regra de forma recorrente — por exemplo, todo dia às 9:00, ou toda segunda-feira às 15:00. + +**Observação:** os agendamentos do Rules Engine são limitados a marcas de quinze em quinze minutos. O campo de minuto de um agendamento cron deve ser um dos seguintes: **0, 15, 30 ou 45**. Outros valores de minuto não são permitidos. + +Exemplos de agendamentos válidos: +- Toda hora, na hora cheia: `0 * * * *` +- Todo dia às 9:15: `15 9 * * *` +- Toda segunda-feira às 15:00: `0 15 * * 1` +- A cada 15 minutos: `0,15,30,45 * * * *` + +## Criando um agendamento para uma Regra + +1. Navegue até a página **All Rules** pelo menu **Rules Engine** na barra lateral. +2. Encontre a regra que deseja agendar e abra seu menu de ações (**⋮**). +3. Clique em **Schedule Rule**. Esta opção só fica visível se o Scheduling Service estiver habilitado e você tiver a permissão necessária. +4. No modal **Schedule Rule**, preencha os seguintes campos: + +| Campo | Descrição | +|---|---| +| **Name** | Um nome único para este agendamento (obrigatório, máximo de 100 caracteres). | +| **Description** | Descrição opcional da finalidade do agendamento. | +| **Trigger Type** | Escolha **Single Run** para uma execução única, ou **Repeated Run** para um agendamento cron recorrente. | +| **Frequency** | Para Repeated Run: use o construtor de cron para selecionar o período (por hora, diário, semanal etc.) e os valores específicos de minuto, hora e dia. Para Single Run: selecione uma data e hora usando o seletor de data. | +| **Enable Schedule** | Alterna para habilitar ou desabilitar o agendamento. Um agendamento desabilitado não será executado até ser reabilitado. | + +5. Clique em **Submit** para salvar o agendamento. A regra será executada automaticamente no próximo horário agendado. + + +## Permissões + +O acesso ao agendamento dentro do Rules Engine requer permissões de Superusuário ou a Permissão de Configuração apropriada. Veja [User Permission Chart](/admin/user_management/user_permission_chart) para mais detalhes. diff --git a/docs/content/automation/rules_engine/scheduling.zh-hans.md b/docs/content/automation/rules_engine/scheduling.zh-hans.md new file mode 100644 index 0000000000..b98ce99dd4 --- /dev/null +++ b/docs/content/automation/rules_engine/scheduling.zh-hans.md @@ -0,0 +1,54 @@ +--- +title: 规则排程 +description: 按周期性或一次性排程自动运行规则引擎中的规则 +weight: 2 +audience: pro +--- + +注意：规则引擎排程功能是 DefectDojo Pro 专属功能。 + +规则可以设置为自动运行的排程，而不必每次都手动触发。已排程的规则会在配置的时间，针对所有匹配其筛选条件的发现项执行。 + +排程功能默认关闭，需要由 DefectDojo 按实例单独启用，而不是通过功能开关页面开启。请联系 [DefectDojo 支持团队](mailto:support@defectdojo.com)，请求开启**调度服务**；一旦开启，**排定规则**选项就会出现。有关 DefectDojo 集中管理的功能是如何呈现的，请参阅[功能开关](/admin/feature_flags/pro__feature_flags/)。 + +设置排程的用户必须拥有**更改调度服务排程（Change Scheduling Service Schedule）**这一配置权限。 + +## 排程类型 + +### 单次运行 + +"单次运行"排程会在指定的日期和时间执行一次该规则。运行完成后，该排程不会重复。 + +### 重复运行 + +"重复运行"排程允许您按周期性的方式触发规则 — 例如，每天上午 9:00，或每周一下午 15:00。 + +**注意：** 规则引擎的排程仅限于整刻钟触发。cron 排程的分钟字段必须是以下之一：**0、15、30 或 45**。不允许使用其他分钟数值。 + +有效排程示例： +- 每小时整点：`0 * * * *` +- 每天上午 9:15：`15 9 * * *` +- 每周一下午 3:00：`0 15 * * 1` +- 每 15 分钟一次：`0,15,30,45 * * * *` + +## 为规则创建排程 + +1. 从侧边栏的**规则引擎**菜单中，导航至**所有规则**页面。 +2. 找到您想要排程的规则，然后打开其操作菜单（**⋮**）。 +3. 点击**排定规则**。只有在调度服务已启用且您拥有所需权限的情况下，此选项才会显示。 +4. 在**排定规则**弹窗中，填写以下字段： + +| Field | Description | +|---|---| +| **名称** | 此排程的唯一名称（必填，最多 100 个字符）。 | +| **描述** | 关于此排程用途的可选描述。 | +| **触发类型** | 选择**单次运行**以进行一次性执行，或选择**重复运行**以设置周期性的 cron 排程。 | +| **频率** | 对于重复运行：使用 cron 构建器选择周期（每小时、每天、每周等）以及具体的分钟、小时和日期数值。对于单次运行：使用日期选择器选择日期和时间。 | +| **启用排程** | 切换以启用或禁用此排程。已禁用的排程在重新启用之前不会运行。 | + +5. 点击**提交**以保存该排程。规则将在下一个排定的时间自动运行。 + + +## 权限 + +访问规则引擎中的排程功能需要超级用户权限，或相应的配置权限。详情请参阅[用户权限表](/admin/user_management/user_permission_chart)。 diff --git a/docs/content/automation/rules_engine_2/_index.it.md b/docs/content/automation/rules_engine_2/_index.it.md new file mode 100644 index 0000000000..bc3d175a90 --- /dev/null +++ b/docs/content/automation/rules_engine_2/_index.it.md @@ -0,0 +1,18 @@ +--- +title: Rules Engine 2.0 +description: Crea automazioni come grafi di nodi visivi, con tracce per singola esecuzione + e un registro delle consegne +summary: '' +date: 2026-08-02 09:00:00+00:00 +lastmod: 2026-08-02 09:00:00+00:00 +draft: false +weight: 99 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +--- diff --git a/docs/content/automation/rules_engine_2/_index.pt-br.md b/docs/content/automation/rules_engine_2/_index.pt-br.md new file mode 100644 index 0000000000..56ad6d1ca7 --- /dev/null +++ b/docs/content/automation/rules_engine_2/_index.pt-br.md @@ -0,0 +1,18 @@ +--- +title: Motor de Regras 2.0 +description: Construa automações como grafos visuais de nós, com rastreamento por + execução e um registro de entregas +summary: '' +date: 2026-08-02 09:00:00+00:00 +lastmod: 2026-08-02 09:00:00+00:00 +draft: false +weight: 99 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +--- diff --git a/docs/content/automation/rules_engine_2/_index.zh-hans.md b/docs/content/automation/rules_engine_2/_index.zh-hans.md new file mode 100644 index 0000000000..34c138bbaa --- /dev/null +++ b/docs/content/automation/rules_engine_2/_index.zh-hans.md @@ -0,0 +1,17 @@ +--- +title: 规则引擎 2.0 +description: 以可视化节点图构建自动化，并提供每次运行的追踪记录和投递台账 +summary: '' +date: 2026-08-02 09:00:00+00:00 +lastmod: 2026-08-02 09:00:00+00:00 +draft: false +weight: 99 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +--- diff --git a/docs/content/automation/rules_engine_2/about.it.md b/docs/content/automation/rules_engine_2/about.it.md new file mode 100644 index 0000000000..f3851b80eb --- /dev/null +++ b/docs/content/automation/rules_engine_2/about.it.md @@ -0,0 +1,118 @@ +--- +title: Informazioni su Rules Engine 2.0 +description: Cos'è Rules Engine 2.0, come attivarlo e i concetti su cui si basa +weight: 1 +audience: pro +aliases: +- /it/automation/rules_engine_v2/about/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +Rules Engine 2.0 è un builder di automazione visuale. Invece di un filtro più un elenco piatto di azioni, una regola è un **grafo**: un nodo trigger che decide quando la regola si attiva, e un numero qualsiasi di nodi logici, Riscontro ed egress collegati tra loro per stabilire cosa succede dopo. + +Rules Engine 2.0 è accessibile solo tramite la [UI Pro](/get_started/about/ui_pro_vs_os/). + +## Cosa aggiunge rispetto a Rules Engine + +Il [Rules Engine](/automation/rules_engine/about/) originale applica un elenco ordinato di azioni a ogni Riscontro che corrisponde a un filtro. Rules Engine 2.0 mantiene questa capacità e aggiunge quattro cose: + +* **Ramificazione.** Un nodo **If / Filter** instrada gli elementi lungo un ramo vero e uno falso, così una regola può trattare i Riscontri Critica in modo diverso dal resto senza doverla dividere in due regole. +* **Egress.** Una regola può uscire da DefectDojo: aprire un ticket JIRA o un ticket a valle, pubblicare su Slack o Microsoft Teams, inviare un'email, chiamare un webhook, generare un avviso in-app o produrre un report. +* **Tracciabilità.** Ogni esecuzione viene registrata nodo per nodo come [Run](../runs/), e ogni invio in uscita viene registrato come [Delivery](../deliveries/) che indica esattamente cosa è stato inviato, dove è andato e come è terminato. +* **Una modalità di simulazione.** Una regola può registrare esattamente cosa avrebbe inviato senza inviare nulla, ed è così che la si testa in sicurezza prima che tocchi il mondo esterno. + +I due motori funzionano fianco a fianco. Attivare Rules Engine 2.0 non disabilita né converte le regole esistenti, ed esiste un [convertitore](../converting_from_rules_engine/) per quando si vuole spostarle. + +## Abilitare Rules Engine 2.0 + +Rules Engine 2.0 è in Beta ed è disattivato per impostazione predefinita. Un superuser lo attiva da **Settings > Feature Flags**, sia sulle istanze Cloud che On-Premise. Vedere [Feature Flags](/admin/feature_flags/pro__feature_flags/). + +Una volta attivato il flag, nella barra laterale compare una sezione **Rules Engine 2.0** con tre pagine: + +| Pagina | A cosa serve | +|------|----------------| +| **All Rules** | L'elenco delle regole. Da qui si creano, modificano, abilitano, eseguono ed eliminano le regole. | +| **Runs** | Ogni esecuzione, con la sua traccia per nodo. | +| **Deliveries** | Il registro di tutto ciò che le regole hanno inviato verso l'esterno. | + +### Permessi + +L'accesso è governato da due permessi di ruolo globali, condivisi con il Rules Engine originale: + +* **Rule View** è necessario per vedere la sezione nella barra laterale e tutto ciò che contiene. +* **Rule Edit** è necessario per creare, modificare, eseguire, eliminare, convertire, assumere la proprietà e rieseguire. + +Rule Edit è vicino a un permesso amministrativo. Un autore di regole può raggiungere qualsiasi Riscontro che il proprietario della sua regola può vedere, e può indirizzare l'output verso sistemi esterni, quindi va concesso con attenzione. + +## I concetti + +### Regole e grafi + +Una regola è un nome, una descrizione, un proprietario, una modalità, un interruttore di abilitazione e un grafo. Il grafo è un insieme di **nodi** e degli **archi** tra di essi. Deve contenere esattamente un nodo trigger e non deve contenere cicli. Tutto il resto è a discrezione dell'autore, incluso lasciare un nodo non collegato, il che significa semplicemente che viene eseguito senza nulla su cui lavorare. + +Le nuove regole vengono sempre create **disabilitate**, quindi abilitarne una è un atto deliberato. + +### Elementi + +Ciò che viaggia lungo gli archi di un grafo è un **elemento**: uno snapshot JSON di un Riscontro più il contesto circostante. + +```json +{ + "finding": { "id": 1234, "title": "...", "severity": "High", "...": "..." }, + "test": { "id": 12, "title": "...", "scan_type": "..." }, + "engagement": { "id": 5, "name": "..." }, + "product": { "id": 3, "name": "..." }, + "product_type": { "id": 1, "name": "..." }, + "ctx": { "trigger": "finding.created", "depth": 0, "source": "app" } +} +``` + +Le condizioni e i template dei messaggi vengono scritti sui percorsi presenti in questa struttura, ad esempio `finding.severity` o `product.name`. L'elenco completo dei campi si trova in [Building Rules](../building_rules/). + +### Proprietario + +Ogni regola viene eseguita **come il suo proprietario**. Vede esattamente i Riscontri che quell'utente può vedere, attraverso la stessa autorizzazione usata ovunque altrove nel prodotto. Due conseguenze vale la pena conoscere: + +* Restringere l'accesso del proprietario di una regola restringe la regola. +* Una regola il cui account proprietario è stato eliminato non ha proprietario, quindi non corrisponde a nulla e non fa nulla. Assegnare un nuovo proprietario, oppure usare **Take Ownership** dall'elenco delle regole, per ripristinarla. + +### Modalità: Simulate o Live + +La modalità è impostata per regola, non per nodo. + +* **Simulate** (predefinita) esegue l'intero grafo realmente, incluse tutte le modifiche ai Riscontri, ma i nodi egress registrano cosa *avrebbero* inviato e si fermano lì. Nulla lascia DefectDojo. +* **Live** esegue effettivamente gli invii. + +Gli invii simulati compaiono comunque nel registro Deliveries, contrassegnati come `simulated`, con il loro payload completo. Questo è il modo previsto per rivedere una regola prima di renderla operativa. + +La modalità si applica deliberatamente all'intera regola. Un grafo in cui alcuni invii sono reali e altri no è più difficile da comprendere rispetto a due regole separate. + +### Run + +Una singola esecuzione di una regola è un [Run](../runs/). Un run registra l'evento che lo ha attivato, il suo stato, la traccia per nodo e qualsiasi errore. Una regola può avere un solo run in corso alla volta, quindi una regola occupata si accoda invece di correre contro sé stessa. + +### Deliveries + +Ogni effetto collaterale in uscita è una riga nel registro [Deliveries](../deliveries/), scritta **prima** che avvenga qualsiasi chiamata di rete. La riga contiene il payload, la destinazione risolta, lo stato, il conteggio dei tentativi e qualsiasi risposta della destinazione. Anche le omissioni vengono registrate, così "la regola non ha fatto nulla" e "la regola non ha fatto nulla perché il Riscontro aveva già un ticket" sono distinguibili. + +### Provenienza + +Ogni modifica che una regola apporta a un Riscontro viene attribuita alla regola, al run e al nodo che l'ha effettuata. Questa cronologia è visibile sul Riscontro stesso, così si può rispondere a "perché questo Riscontro è cambiato?" senza dover leggere le definizioni delle regole. + +### Scala + +Una regola elabora tutto ciò che il suo scope include. Non c'è un limite al numero di Riscontri che un run può gestire: li elabora a blocchi in modo che sia la memoria a rimanere limitata, non la copertura. Solo Preview impone un limite, e lo segnala quando lo fa. + +### Conservazione + +Run e delivery vengono entrambi mantenuti per 180 giorni per impostazione predefinita, poi eliminati. Il prodotto mostra la finestra e la data in cui un dato record verrà eliminato invece di lasciarla implicita, ed entrambe le finestre sono configurabili. Vedere [Configuration](../configuration/#retention). + +## Dove andare dopo + +* [Building Rules](../building_rules/) tratta l'editor, i trigger, lo scope, le condizioni e i template. +* [Node Reference](../node_reference/) documenta tutti i 25 nodi. +* [Runs](../runs/) tratta l'esecuzione, le tracce, la propagazione a cascata e i limiti. +* [Deliveries](../deliveries/) tratta i canali, gli stati, i tentativi e la riesecuzione. +* [Converting from Rules Engine](../converting_from_rules_engine/) tratta lo spostamento delle regole esistenti. +* [Configuration](../configuration/) tratta le impostazioni a livello di deployment. diff --git a/docs/content/automation/rules_engine_2/about.pt-br.md b/docs/content/automation/rules_engine_2/about.pt-br.md new file mode 100644 index 0000000000..a249e0d62d --- /dev/null +++ b/docs/content/automation/rules_engine_2/about.pt-br.md @@ -0,0 +1,118 @@ +--- +title: Sobre o Rules Engine 2.0 +description: O que é o Rules Engine 2.0, como ativá-lo e os conceitos em que se baseia +weight: 1 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/about/ +--- + +Nota: O Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +Rules Engine 2.0 é um construtor visual de automação. Em vez de um filtro mais uma lista simples de ações, uma regra é um **grafo**: um nó de gatilho que decide quando a regra é ativada, e qualquer número de nós de lógica, de Achado e de saída (egress) conectados entre si para dizer o que acontece a seguir. + +O Rules Engine 2.0 só pode ser acessado pela [Pro UI](/get_started/about/ui_pro_vs_os/). + +## O que ele adiciona em relação ao Rules Engine + +O [Rules Engine](/automation/rules_engine/about/) original aplica uma lista ordenada de ações a cada Achado que corresponde a um filtro. O Rules Engine 2.0 mantém essa capacidade e adiciona quatro coisas: + +* **Ramificação (branching).** Um nó **If / Filter** encaminha os itens por um ramo verdadeiro e um ramo falso, de modo que uma única regra possa tratar Achados Críticos de forma diferente do restante sem precisar ser dividida em duas regras. +* **Saída (egress).** Uma regra pode sair do DefectDojo: abrir um chamado no JIRA ou em um sistema de tickets externo, publicar no Slack ou no Microsoft Teams, enviar um e-mail, chamar um webhook, disparar um alerta no aplicativo ou gerar um relatório. +* **Rastreabilidade.** Cada execução é registrada nó a nó como uma [Execução](../runs/), e cada envio de saída é registrado como uma [Entrega](../deliveries/) que informa exatamente o que foi enviado, para onde foi e como terminou. +* **Um modo de simulação.** Uma regra pode registrar exatamente o que enviaria sem enviar nada de fato, o que permite testá-la com segurança antes de deixá-la tocar o mundo externo. + +Os dois mecanismos funcionam lado a lado. Ativar o Rules Engine 2.0 não desativa nem converte suas regras existentes, e há um [conversor](../converting_from_rules_engine/) para quando você quiser migrá-las. + +## Ativando o Rules Engine 2.0 + +O Rules Engine 2.0 está em Beta e vem desativado por padrão. Um superusuário o ativa em **Settings > Feature Flags**, tanto em instâncias Cloud quanto On-Premise. Veja [Feature Flags](/admin/feature_flags/pro__feature_flags/). + +Assim que a flag é ativada, uma seção **Rules Engine 2.0** aparece na barra lateral com três páginas: + +| Página | Para que serve | +|------|----------------| +| **All Rules** | A lista de regras. Crie, edite, ative, execute e exclua regras a partir daqui. | +| **Runs** | Cada execução, com seu rastreamento por nó. | +| **Deliveries** | O registro de tudo o que as regras enviaram para fora. | + +### Permissões + +O acesso é regido por duas permissões globais de função, compartilhadas com o Rules Engine original: + +* **Rule View** é necessária para ver a seção na barra lateral e tudo o que está nela. +* **Rule Edit** é necessária para criar, alterar, executar, excluir, converter, assumir a propriedade e reproduzir. + +Rule Edit está próxima de ser uma permissão administrativa. Um autor de regra pode alcançar qualquer Achado que o proprietário da regra consiga ver, e pode direcionar a saída para sistemas externos, portanto conceda-a com cautela. + +## Os conceitos + +### Regras e grafos + +Uma regra é um nome, uma descrição, um proprietário, um modo, uma chave de ativação e um grafo. O grafo é um conjunto de **nós** e as **arestas** entre eles. Ele deve conter exatamente um nó de gatilho e não pode conter um ciclo. Tudo o mais fica a seu critério, inclusive deixar um nó desconectado, o que simplesmente significa que ele é executado sem nada para processar. + +Novas regras são sempre criadas **desativadas**, portanto ativar uma é um ato deliberado. + +### Itens + +O que trafega pelas arestas de um grafo é um **item**: um snapshot em JSON de um Achado mais o contexto ao seu redor. + +```json +{ + "finding": { "id": 1234, "title": "...", "severity": "High", "...": "..." }, + "test": { "id": 12, "title": "...", "scan_type": "..." }, + "engagement": { "id": 5, "name": "..." }, + "product": { "id": 3, "name": "..." }, + "product_type": { "id": 1, "name": "..." }, + "ctx": { "trigger": "finding.created", "depth": 0, "source": "app" } +} +``` + +As condições e os modelos de mensagem são escritos com base nos caminhos dessa estrutura, por exemplo `finding.severity` ou `product.name`. A lista completa de campos está em [Building Rules](../building_rules/). + +### Proprietário + +Toda regra é executada **como o seu proprietário**. Ela vê exatamente os Achados que esse usuário consegue ver, através da mesma autorização usada em todo o restante do produto. Duas consequências valem a pena conhecer: + +* Restringir o acesso do proprietário de uma regra restringe a regra. +* Uma regra cujo proprietário teve a conta excluída fica sem proprietário, portanto não corresponde a nada e não faz nada. Atribua um novo proprietário, ou use **Take Ownership** na lista de regras, para trazê-la de volta. + +### Modo: Simulate ou Live + +O modo é definido por regra, não por nó. + +* **Simulate** (o padrão) executa o grafo inteiro de verdade, incluindo toda edição de Achado, mas os nós de saída registram o que *teriam* enviado e param por aí. Nada sai do DefectDojo. +* **Live** realiza os envios de fato. + +Os envios simulados ainda aparecem no registro de Deliveries, marcados como `simulated`, com sua carga (payload) completa. Essa é a forma pretendida de revisar uma regra antes de liberá-la. + +O modo se aplica deliberadamente à regra inteira. Um grafo em que alguns envios são reais e outros não é mais difícil de entender do que duas regras separadas. + +### Execuções (Runs) + +Uma execução de uma regra é uma [Execução](../runs/). Uma execução registra o evento que a disparou, seu status, seu rastreamento por nó e qualquer erro. Uma regra só pode ter uma execução em andamento por vez, portanto uma regra ocupada entra em fila em vez de competir consigo mesma. + +### Entregas (Deliveries) + +Todo efeito colateral de saída é uma linha no registro de [Entregas](../deliveries/), gravada **antes** de qualquer chamada de rede acontecer. A linha contém a carga (payload), o destino resolvido, o status, o número de tentativas e o que quer que o destino tenha respondido. As omissões (skips) também são registradas, de modo que "a regra não fez nada" e "a regra não fez nada porque o Achado já tinha um chamado aberto" são situações distinguíveis. + +### Proveniência + +Toda alteração que uma regra faz em um Achado é atribuída de volta à regra, à execução e ao nó que a realizou. Essa linha do tempo fica visível no próprio Achado, de modo que você pode responder "por que esse Achado mudou?" sem precisar ler as definições das regras. + +### Escala + +Uma regra processa tudo o que seu escopo corresponde. Não há limite para quantos Achados uma execução processa: ela os percorre em blocos (chunks) para que o consumo de memória permaneça limitado, e não a cobertura. Somente o Preview impõe limites, e ele avisa quando o faz. + +### Retenção + +Execuções e entregas são mantidas por 180 dias por padrão, e depois são removidas. O produto mostra a janela e a data em que um determinado registro será excluído, em vez de deixar isso implícito, e ambas as janelas são configuráveis. Veja [Configuration](../configuration/#retention). + +## Para onde ir a seguir + +* [Building Rules](../building_rules/) aborda o editor, gatilhos, escopo, condições e modelos. +* [Node Reference](../node_reference/) documenta todos os 25 nós. +* [Runs](../runs/) aborda execução, rastreamentos, encadeamento (cascading) e limites. +* [Deliveries](../deliveries/) aborda canais, status, novas tentativas e reprodução (replay). +* [Converting from Rules Engine](../converting_from_rules_engine/) aborda a migração de regras existentes. +* [Configuration](../configuration/) aborda as configurações em nível de implantação. diff --git a/docs/content/automation/rules_engine_2/about.zh-hans.md b/docs/content/automation/rules_engine_2/about.zh-hans.md new file mode 100644 index 0000000000..4b88870e68 --- /dev/null +++ b/docs/content/automation/rules_engine_2/about.zh-hans.md @@ -0,0 +1,118 @@ +--- +title: 关于 Rules Engine 2.0 +description: Rules Engine 2.0 是什么、如何启用它，以及它所基于的核心概念 +weight: 1 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/about/ +--- + +注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。 + +Rules Engine 2.0 是一个可视化自动化构建器。规则不再是“一个过滤器加一份扁平的动作列表”，而是一个**图（graph）**：一个决定规则何时被唤醒的触发器节点，以及任意数量相互连接的逻辑、发现项和出站（egress）节点，用来说明接下来会发生什么。 + +Rules Engine 2.0 只能通过 [Pro UI](/get_started/about/ui_pro_vs_os/) 访问。 + +## 相较于 Rules Engine 新增了什么 + +原有的 [Rules Engine](/automation/rules_engine/about/) 会将一份有序的动作列表应用到匹配某个过滤器的每一个发现项上。Rules Engine 2.0 保留了这一能力，并新增了四项内容： + +* **分支。** **If / Filter** 节点会将条目分流到“真”分支和“假”分支，因此一条规则就能对严重发现项与其他发现项采取不同处理方式，而无需拆分成两条规则。 +* **出站（Egress）。** 规则可以离开 DefectDojo：打开一个 JIRA 问题单或下游工单、发布到 Slack 或 Microsoft Teams、发送邮件、调用 Webhook、发出应用内提醒，或生成报告。 +* **可追溯性。** 每次执行都会作为一次[运行（Run）](../runs/)按节点逐一记录，每次出站发送都会作为一条[投递记录（Delivery）](../deliveries/)记录下来，准确说明发送了什么、发到了哪里、结果如何。 +* **模拟模式。** 规则可以精确记录它本会发送的内容而不实际发送，这就是在让规则接触外部世界之前安全测试它的方式。 + +两套引擎并行运行。启用 Rules Engine 2.0 不会禁用或转换您现有的规则，并且提供了一个[转换器](../converting_from_rules_engine/)，供您在想要迁移规则时使用。 + +## 启用 Rules Engine 2.0 + +Rules Engine 2.0 处于 Beta 阶段，默认关闭。超级用户可以在 **Settings > Feature Flags** 中启用它，云端和本地部署实例均适用。参见[功能标志](/admin/feature_flags/pro__feature_flags/)。 + +标志启用后，侧边栏会出现一个 **Rules Engine 2.0** 区块，下面有三个页面： + +| Page | What it is for | +|------|----------------| +| **All Rules** | 规则列表。可在此创建、编辑、启用、运行和删除规则。 | +| **Runs** | 每一次执行，及其按节点的追踪记录。 | +| **Deliveries** | 规则对外发送的所有内容的台账。 | + +### 权限 + +访问权限由两个全局角色权限控制，与原有 Rules Engine 共用： + +* **Rule View** 用于查看侧边栏该区块及其下的所有内容。 +* **Rule Edit** 用于创建、修改、运行、删除、转换、接管所有权以及重放。 + +Rule Edit 接近于管理权限。规则作者可以触及其规则所有者能看到的任何发现项，并能将输出定向到外部系统，因此请谨慎授予。 + +## 核心概念 + +### 规则与图 + +一条规则由名称、描述、所有者、模式、启用开关和一张图组成。图是一组**节点（node）**及节点之间的**边（edge）**。图中必须恰好包含一个触发器节点，且不能包含环。除此之外的一切都由您决定，包括让某个节点保持未连接——这只是意味着它在没有任何输入的情况下运行。 + +新建规则总是以**禁用**状态创建，因此启用规则是一个需要主动执行的操作。 + +### 条目（Items） + +沿着图的边流动的是一个**条目（item）**：一份发现项及其周边上下文的 JSON 快照。 + +```json +{ + "finding": { "id": 1234, "title": "...", "severity": "High", "...": "..." }, + "test": { "id": 12, "title": "...", "scan_type": "..." }, + "engagement": { "id": 5, "name": "..." }, + "product": { "id": 3, "name": "..." }, + "product_type": { "id": 1, "name": "..." }, + "ctx": { "trigger": "finding.created", "depth": 0, "source": "app" } +} +``` + +条件和消息模板都是针对该结构中的路径来编写的，例如 `finding.severity` 或 `product.name`。完整字段列表见[构建规则](../building_rules/)。 + +### 所有者 + +每条规则都**以其所有者的身份**运行。它所能看到的发现项，与该用户本人能看到的完全一致，使用的是产品中其他地方通用的同一套授权机制。有两点后果值得了解： + +* 缩小规则所有者的访问权限，也会缩小该规则的作用范围。 +* 若规则所有者的账户被删除，规则就没有了所有者，因此它将不匹配任何内容，也不会执行任何操作。为其指定一个新的所有者，或在规则列表中使用**接管所有权（Take Ownership）**，即可恢复它。 + +### 模式：模拟（Simulate）或实时（Live） + +模式按规则设置，而非按节点设置。 + +* **Simulate**（默认）会真实运行整张图，包括每一次发现项编辑，但出站节点只会记录它本*会*发送的内容，到此为止。不会有任何内容离开 DefectDojo。 +* **Live** 会真正执行发送。 + +模拟发送仍会出现在 Deliveries 台账中，标记为 `simulated`，并附带完整载荷。这正是在放出规则之前对其进行审查的预期方式。 + +模式是有意针对整条规则生效的。一张图里部分发送是真实的、部分不是，会比拆成两条规则更难推理。 + +### 运行（Runs） + +规则的一次执行就是一次[运行（Run）](../runs/)。一次运行会记录触发它的事件、其状态、按节点的追踪记录，以及任何错误。一条规则同一时刻只能有一次运行在进行中，因此繁忙的规则会排队，而不会与自身竞争。 + +### 投递记录（Deliveries） + +每一次出站副作用都是[投递记录（Deliveries）](../deliveries/)台账中的一行，会在任何网络调用发生**之前**写入。该行保存载荷、解析出的目的地、状态、重试次数，以及目的地返回的任何内容。跳过操作也会被记录，因此“规则什么都没做”和“规则什么都没做是因为该发现项已经开过工单”是可以区分的。 + +### 溯源（Provenance） + +规则对发现项所做的每一次更改都会被追溯到具体的规则、运行和执行更改的节点。这条时间线在发现项本身上即可查看，因此您无需阅读规则定义就能回答“这个发现项为什么会变化？”。 + +### 规模 + +规则会处理其作用范围（scope）匹配到的一切内容。一次运行能处理多少发现项没有上限：它会分块处理，以便让内存占用保持有界，而不是牺牲覆盖面。只有 Preview 会设置上限，并且在触发上限时会明确告知您。 + +### 保留期 + +运行记录和投递记录默认都保留 180 天，之后会被清理。产品会向您展示保留窗口以及某条记录将被删除的具体日期，而不是让这一点变得隐晦，并且两个窗口都是可配置的。参见[配置](../configuration/#retention)。 + +## 接下来可以阅读 + +* [构建规则](../building_rules/)介绍编辑器、触发器、作用范围、条件和模板。 +* [节点参考](../node_reference/)记录了全部 25 个节点。 +* [运行（Runs）](../runs/)介绍执行、追踪、级联和限制。 +* [投递记录（Deliveries）](../deliveries/)介绍渠道、状态、重试和重放。 +* [从 Rules Engine 转换](../converting_from_rules_engine/)介绍如何迁移现有规则。 +* [配置](../configuration/)介绍部署层面的设置。 diff --git a/docs/content/automation/rules_engine_2/building_rules.it.md b/docs/content/automation/rules_engine_2/building_rules.it.md new file mode 100644 index 0000000000..4eb558f5ff --- /dev/null +++ b/docs/content/automation/rules_engine_2/building_rules.it.md @@ -0,0 +1,198 @@ +--- +title: Costruire regole +description: L'editor a grafo, i trigger, lo scope, le condizioni e i template dei + messaggi +weight: 2 +audience: pro +aliases: +- /it/automation/rules_engine_v2/building_rules/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +Una regola si costruisce su una canvas. Si trascinano nodi da una palette, si collegano tra loro e si configura ciascuno in un pannello laterale. Questa pagina tratta le parti di questo processo che sono le stesse indipendentemente dai nodi usati. I nodi stessi sono descritti in [Node Reference](../node_reference/). + +## L'editor + +Aprire **Rules Engine 2.0 > All Rules** e scegliere **New Rule**, oppure aprire una regola esistente per modificarla. + +La palette è raggruppata in quattro categorie, che rappresentano anche l'ordine in cui gli elementi attraversano un grafo tipico: + +| Categoria | Cosa fanno i nodi | +|----------|-------------------| +| **Triggers** | Decidono quando la regola si attiva e quali Riscontri vi entrano. Esattamente uno per grafo. | +| **Logic** | Instradano, limitano e deduplicano gli elementi che vi passano attraverso. | +| **Findings** | Modificano i Riscontri. | +| **Egress** | Inviano qualcosa verso l'esterno: un ticket, un messaggio, un report. | + +La palette viene generata dal motore stesso, quindi ciò che si vede nell'editor è sempre esattamente ciò che il motore può eseguire. + +### Regole del grafo + +Un grafo viene verificato al salvataggio, e di nuovo prima di ogni run. Deve soddisfare tutte le condizioni seguenti: + +* Ha almeno un nodo. +* Ha **esattamente un** nodo trigger. +* Ogni nodo ha un id univoco e non vuoto di 100 caratteri o meno. +* Ogni nodo è di un tipo che il motore conosce. +* Ogni arco collega due nodi esistenti. +* Non contiene cicli. + +Un nodo senza nulla collegato in ingresso è ammesso. Viene eseguito con un elenco di input vuoto, il che di norma significa che non fa nulla. + +Un nodo con più archi in ingresso riceve tutti i loro output concatenati. + +### Anteprima prima di salvare + +**Preview** esegue a secco il grafo attualmente presente sulla canvas e mostra la traccia per nodo che produrrebbe: quanti elementi sono entrati in ciascun nodo, quanti sono usciti da ciascuna uscita e cosa ciascun nodo avrebbe modificato. + +Preview esegue il motore reale, non una sua simulazione, e poi annulla tutto. Non viene scritto nulla, non viene registrato alcun run, e l'egress è forzato a simulare qualunque cosa dica la modalità della regola. È il modo più rapido per verificare che le condizioni corrispondano a quanto ci si aspettava. + +Preview è l'unica esecuzione che limita quanti Riscontri esamina, in modo da restare veloce. Quando tronca, lo segnala nella traccia. Un run reale non ha un limite del genere. + +## Trigger e scope + +Ogni grafo inizia con uno dei tre trigger. + +* **On Finding Event** attiva la regola quando i Riscontri vengono creati, aggiornati, chiusi o riaperti. Scegliere quale di questi nell'impostazione **Event** del nodo, oppure `any` per tutti e quattro. +* **On a Schedule** esamina i Riscontri secondo una pianificazione ricorrente. +* **Manual Run** esamina i Riscontri quando si preme **Run** sulla regola. + +### Scope + +Tutti e tre i trigger accettano uno **Scope**, ed è tramite lo scope che si restringe ciò che la regola considera. È lo stesso vocabolario di filtri usato dal Rules Engine originale, circa sessanta filtri che coprono i Riscontri e gli oggetti che li circondano, quindi un filtro che si sa già scrivere lì significa la stessa cosa qui. + +Due cose sullo scope vale la pena capire: + +* **Lo scope si applica sopra l'autorizzazione, mai al suo posto.** La regola viene eseguita come il suo proprietario, quindi lo scope restringe un insieme di Riscontri già autorizzato. Lasciare lo scope vuoto non significa "tutti i Riscontri dell'istanza", significa "tutti i Riscontri che il proprietario della regola può vedere". +* **Uno scope non valido fa fallire il run invece di ampliarlo.** Se una chiave di filtro non esiste, o un valore è tale che il filtro lo scarterebbe silenziosamente, il run termina con un errore. Una regola che non fa nulla è recuperabile. Una regola che modifica silenziosamente ogni Riscontro dell'istanza non lo è. + +Per un trigger a evento, lo scope funge da secondo cancello: i Riscontri indicati nell'evento vengono confrontati con esso, e solo quelli che passano entrano nel grafo. + +### Pianificazione + +Una regola il cui trigger è **On a Schedule** viene pianificata dalla regola stessa. Impostare la pianificazione richiede Rule Edit, lo stesso permesso richiesto per modificare la regola, perché una regola attivata da pianificazione non fa nulla finché non ne ha una. + +Le pianificazioni sono limitate a intervalli di un quarto d'ora. Il campo dei minuti di un'espressione cron deve essere `0`, `15`, `30` o `45`. + +Esempi validi: + +``` +0 * * * * every hour, on the hour +15 9 * * * every day at 09:15 +0 15 * * 1 every Monday at 15:00 +30 2 * * * every day at 02:30 +``` + +## Fare riferimento ai dati di un Riscontro + +Due punti di una regola leggono valori dall'elemento che vi passa attraverso: le **condizioni** e i **template**. Entrambi usano gli stessi percorsi puntati. + +``` +finding.severity +finding.title +finding.vulnerability_ids.0 +product.name +product_type.name +test.scan_type +ctx.rule_name +``` + +Un percorso che non si risolve produce l'assenza di valore, non un errore. + +### Campi disponibili + +Ogni elemento porta con sé un insieme fisso di campi del Riscontro. Questo elenco è un contratto, quindi cambia solo in modo deliberato. + +| Gruppo | Campi | +|-------|--------| +| Identità | `id`, `title`, `hash_code`, `unique_id_from_tool` | +| Gravità e punteggio | `severity`, `numerical_severity`, `cvssv3`, `cvssv3_score`, `epss_score`, `epss_percentile`, `priority`, `risk`, `risk_score` | +| Testo | `description`, `mitigation`, `impact` | +| Stato | `active`, `verified`, `false_p`, `duplicate`, `is_mitigated`, `out_of_scope`, `risk_accepted`, `under_review` | +| Date | `date`, `mitigated`, `last_status_update`, `sla_expiration_date` | +| Posizione | `file_path`, `line`, `component_name`, `component_version`, `service` | +| Classificazione | `cwe`, `vulnerability_ids`, `tags` | + +Oltre a `finding`, ogni elemento porta con sé `test` (`id`, `title`, `scan_type`), `engagement` (`id`, `name`), `product` (`id`, `name`), `product_type` (`id`, `name`) e `ctx`. + +Le date sono stringhe ISO-8601. Ciò è deliberato: significa che `gt` e `lt` le ordinano correttamente come testo, quindi `2026-07-28` è correttamente maggiore di `2026-01-01`. + +`priority`, `risk` e `risk_score` provengono dalla prioritizzazione di Pro. Un Riscontro non ancora valutato non porta alcun valore per essi. + +### Condizioni + +Un nodo **If / Filter** contiene un elenco di righe di condizione. Ogni riga è un percorso, un operatore e un valore. **Match** decide se ogni riga deve essere vera (`all`) oppure basta che lo sia una sola (`any`). + +| Operatore | Significato | +|----------|---------| +| `eq` | è uguale a | +| `neq` | non è uguale a | +| `contains` | contiene | +| `not_contains` | non contiene | +| `in` | è uno tra | +| `not_in` | non è uno tra | +| `gt` | è maggiore di | +| `gte` | è maggiore o uguale a | +| `lt` | è minore di | +| `lte` | è minore o uguale a | +| `startswith` | inizia con | +| `endswith` | finisce con | +| `exists` | è impostato | +| `not_exists` | non è impostato | + +I confronti sono **permissivi**. Si prova prima come numero, e se fallisce i valori vengono confrontati come testo con spazi rimossi e senza distinzione tra maiuscole e minuscole. Quindi una condizione scritta come `finding.severity eq high` corrisponde a un Riscontro la cui gravità è `High`, che è quasi sempre ciò che l'autore intendeva. + +#### Trasformazioni + +Una riga di condizione può post-elaborare il valore letto prima di confrontarlo. + +| Trasformazione | Effetto | +|-----------|--------| +| `int` | numero intero | +| `float` | numero decimale | +| `str` | testo | +| `first` | primo elemento di una lista | +| `list` | come lista | +| `join` | unito con virgole | +| `upper` | MAIUSCOLO | +| `lower` | minuscolo | +| `strip` | con spazi rimossi | +| `cwe_int` | numero CWE | +| `severity` | gravità normalizzata, così valori in stile `critical`, `error` e `warning` provenienti da scanner diversi vengono mappati sui cinque livelli di DefectDojo | +| `numerical_severity` | codice di gravità ordinabile, per i confronti di ordinamento | + +### Template + +Qualsiasi impostazione etichettata come messaggio, nota, titolo o valore accetta segnaposto `{{ percorso }}`, risolti per ciascun elemento: + +``` +{{finding.severity}}: {{finding.title}} ({{product.name}}) +``` + +Un percorso senza valore viene reso come stringa vuota. Una lista viene resa unita da virgole. + +I template vedono anche un blocco `ctx` che porta dettagli sul run stesso. Le chiavi disponibili dipendono dal nodo, ma quelle comuni sono: + +| Segnaposto | Significato | +|-------------|---------| +| `{{ctx.rule_name}}` | Il nome della regola | +| `{{ctx.count}}` | Quanti Riscontri copre il messaggio | +| `{{ctx.trigger}}` | L'evento che ha avviato il run | +| `{{ctx.findings_html}}` | L'elenco dei Riscontri renderizzato, nel nodo email | +| `{{ctx.report_url}}` | Il link di download, nel nodo report | +| `{{ctx.template_name}}` | Il nome del template di report, nel nodo report | + +I template sono pura sostituzione. Non c'è valutazione di espressioni, non c'è esecuzione di codice, e non c'è accesso ad attributi di oggetti in nessun punto della configurazione di una regola. + +## Testare una regola in sicurezza + +L'ordine consigliato per una regola che invia qualcosa: + +1. Costruire il grafo e usare **Preview** finché i conteggi degli elementi non sembrano corretti. +2. Salvarla. Le nuove regole vengono create disabilitate. +3. Lasciare la modalità su **Simulate** e abilitare la regola. +4. Farla eseguire, poi leggere **Deliveries** e verificare che i payload registrati siano quelli previsti. +5. Passare la modalità a **Live**. + +Simulate non è un'esecuzione parziale. Ogni modifica a un Riscontro nel grafo avviene realmente in modalità simulate. Vengono trattenuti solo gli invii in uscita. diff --git a/docs/content/automation/rules_engine_2/building_rules.pt-br.md b/docs/content/automation/rules_engine_2/building_rules.pt-br.md new file mode 100644 index 0000000000..5277501325 --- /dev/null +++ b/docs/content/automation/rules_engine_2/building_rules.pt-br.md @@ -0,0 +1,197 @@ +--- +title: Construindo Regras +description: O editor de grafos, gatilhos, escopo, condições e modelos de mensagem +weight: 2 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/building_rules/ +--- + +Nota: O Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +Uma regra é construída em uma tela (canvas). Você arrasta nós de uma paleta, os conecta entre si e configura cada um em um painel lateral. Esta página aborda as partes desse processo que são iguais independentemente dos nós usados. Os próprios nós estão descritos em [Node Reference](../node_reference/). + +## O editor + +Abra **Rules Engine 2.0 > All Rules** e escolha **New Rule**, ou abra uma regra existente para editá-la. + +A paleta é agrupada em quatro categorias, que também é a ordem em que os itens fluem por um grafo típico: + +| Categoria | O que os nós fazem | +|----------|-------------------| +| **Triggers** | Decidem quando a regra é ativada e quais Achados entram nela. Exatamente um por grafo. | +| **Logic** | Roteiam, limitam e removem duplicidades dos itens que fluem por ela. | +| **Findings** | Alteram os Achados. | +| **Egress** | Enviam algo para fora: um chamado, uma mensagem, um relatório. | + +A paleta é gerada a partir do próprio mecanismo, portanto o que você vê no editor é sempre exatamente o que o mecanismo consegue executar. + +### Regras do grafo + +Um grafo é verificado quando você o salva, e novamente antes de cada execução. Ele deve satisfazer todas as condições a seguir: + +* Tem pelo menos um nó. +* Tem **exatamente um** nó de gatilho. +* Cada nó tem um id único e não vazio de até 100 caracteres. +* Cada nó é de um tipo conhecido pelo mecanismo. +* Cada aresta conecta dois nós que existem. +* Não contém ciclos. + +Um nó sem nada conectado a ele é válido. Ele é executado com uma lista de entrada vazia, o que geralmente significa que não faz nada. + +Um nó com várias arestas de entrada recebe todas as saídas delas concatenadas. + +### Pré-visualizando antes de salvar + +O **Preview** executa a seco (dry-run) o grafo que você tem atualmente na tela e mostra o rastreamento por nó que ele produziria: quantos itens entraram em cada nó, quantos saíram por cada saída, e o que cada nó teria alterado. + +O Preview executa o mecanismo real, não uma simulação dele, e depois desfaz tudo. Nada é gravado, nenhuma execução é registrada, e a saída (egress) é forçada a simular o que quer que o modo da regra determine. É a forma mais rápida de verificar se suas condições correspondem ao que você esperava. + +O Preview é a única execução que limita quantos Achados ele examina, para permanecer rápido. Quando trunca, ele informa isso no rastreamento. Uma execução real não tem esse limite. + +## Gatilhos e escopo + +Todo grafo começa com um dos três gatilhos. + +* **On Finding Event** ativa a regra quando Achados são criados, atualizados, fechados ou reabertos. Escolha qual desses eventos na configuração **Event** do nó, ou `any` para os quatro. +* **On a Schedule** varre os Achados em uma programação recorrente. +* **Manual Run** varre os Achados quando você pressiona **Run** na regra. + +### Escopo + +Os três gatilhos aceitam um **Scope**, e o escopo é a forma de restringir o que a regra considera. É o mesmo vocabulário de filtros usado pelo Rules Engine original, cerca de sessenta filtros que abrangem os Achados e os objetos ao seu redor, portanto um filtro que você já sabe escrever lá significa a mesma coisa aqui. + +Duas coisas sobre o escopo valem a pena entender: + +* **O escopo é aplicado por cima da autorização, nunca no lugar dela.** A regra é executada como seu proprietário, portanto o escopo restringe um conjunto de Achados já autorizado. Deixar o escopo vazio não significa "todo Achado na instância", significa "todo Achado que o proprietário da regra consegue ver". +* **Um escopo inválido faz a execução falhar, em vez de ampliá-la.** Se uma chave de filtro não existir, ou um valor for algo que o filtro descartaria silenciosamente, a execução termina com erro. Uma regra que não faz nada é recuperável. Uma regra que silenciosamente edita todo Achado na instância não é. + +Para um gatilho de evento, o escopo funciona como um segundo portão: os Achados indicados no evento são comparados a ele, e somente os que passam entram no grafo. + +### Agendamento + +Uma regra cujo gatilho é **On a Schedule** é agendada a partir da própria regra. Definir a programação exige Rule Edit, a mesma permissão usada para editar a regra, porque uma regra disparada por agendamento não faz absolutamente nada até ter uma programação definida. + +As programações se limitam a marcas de quinze em quinze minutos. O campo de minutos de uma expressão cron deve ser `0`, `15`, `30` ou `45`. + +Exemplos válidos: + +``` +0 * * * * every hour, on the hour +15 9 * * * every day at 09:15 +0 15 * * 1 every Monday at 15:00 +30 2 * * * every day at 02:30 +``` + +## Referindo-se aos dados do Achado + +Dois lugares em uma regra leem valores do item que passa por ela: **condições** e **modelos**. Ambos usam os mesmos caminhos com pontos (dot paths). + +``` +finding.severity +finding.title +finding.vulnerability_ids.0 +product.name +product_type.name +test.scan_type +ctx.rule_name +``` + +Um caminho que não resolve produz nenhum valor, em vez de um erro. + +### Campos disponíveis + +Cada item carrega um conjunto fixo de campos do Achado. Esta lista é um contrato, portanto só muda de forma deliberada. + +| Grupo | Campos | +|-------|--------| +| Identidade | `id`, `title`, `hash_code`, `unique_id_from_tool` | +| Severidade e pontuação | `severity`, `numerical_severity`, `cvssv3`, `cvssv3_score`, `epss_score`, `epss_percentile`, `priority`, `risk`, `risk_score` | +| Texto | `description`, `mitigation`, `impact` | +| Status | `active`, `verified`, `false_p`, `duplicate`, `is_mitigated`, `out_of_scope`, `risk_accepted`, `under_review` | +| Datas | `date`, `mitigated`, `last_status_update`, `sla_expiration_date` | +| Localização | `file_path`, `line`, `component_name`, `component_version`, `service` | +| Classificação | `cwe`, `vulnerability_ids`, `tags` | + +Além de `finding`, cada item carrega `test` (`id`, `title`, `scan_type`), `engagement` (`id`, `name`), `product` (`id`, `name`), `product_type` (`id`, `name`), e `ctx`. + +As datas são strings ISO-8601. Isso é proposital: significa que `gt` e `lt` as ordenam corretamente como texto, portanto `2026-07-28` é corretamente maior que `2026-01-01`. + +`priority`, `risk` e `risk_score` vêm da priorização do Pro. Um Achado que ainda não foi pontuado não carrega valor para eles. + +### Condições + +Um nó **If / Filter** contém uma lista de linhas de condição. Cada linha é um caminho, um operador e um valor. **Match** decide se todas as linhas precisam ser verdadeiras (`all`) ou apenas uma delas (`any`). + +| Operador | Significado | +|----------|---------| +| `eq` | igual a | +| `neq` | diferente de | +| `contains` | contém | +| `not_contains` | não contém | +| `in` | é um de | +| `not_in` | não é um de | +| `gt` | é maior que | +| `gte` | é maior ou igual a | +| `lt` | é menor que | +| `lte` | é menor ou igual a | +| `startswith` | começa com | +| `endswith` | termina com | +| `exists` | está definido | +| `not_exists` | não está definido | + +As comparações são **flexíveis (loose)**. Primeiro tenta-se um número, e se isso falhar os valores são comparados como texto, sem espaços nas bordas e sem diferenciar maiúsculas de minúsculas. Assim, uma condição escrita como `finding.severity eq high` corresponde a um Achado cuja severidade é `High`, que é quase sempre o que o autor pretendia. + +#### Transformações + +Uma linha de condição pode pós-processar o valor lido antes de compará-lo. + +| Transformação | Efeito | +|-----------|--------| +| `int` | número inteiro | +| `float` | número decimal | +| `str` | texto | +| `first` | primeiro item de uma lista | +| `list` | como lista | +| `join` | unido com vírgulas | +| `upper` | MAIÚSCULAS | +| `lower` | minúsculas | +| `strip` | sem espaços nas bordas | +| `cwe_int` | número do CWE | +| `severity` | severidade normalizada, de modo que valores como `critical`, `error` e `warning` vindos de diferentes scanners são mapeados para os cinco níveis do DefectDojo | +| `numerical_severity` | código de severidade ordenável, para comparações de ordenação | + +### Modelos (Templates) + +Qualquer configuração identificada como mensagem, nota, título ou valor aceita placeholders `{{ path }}`, resolvidos por item: + +``` +{{finding.severity}}: {{finding.title}} ({{product.name}}) +``` + +Um caminho sem valor é renderizado como uma string vazia. Uma lista é renderizada unida por vírgulas. + +Os modelos também enxergam um bloco `ctx` que carrega detalhes sobre a própria execução. As chaves disponíveis dependem do nó, mas as mais comuns são: + +| Placeholder | Significado | +|-------------|---------| +| `{{ctx.rule_name}}` | O nome da regra | +| `{{ctx.count}}` | Quantos Achados a mensagem cobre | +| `{{ctx.trigger}}` | O evento que iniciou a execução | +| `{{ctx.findings_html}}` | A lista de Achados renderizada, no nó de e-mail | +| `{{ctx.report_url}}` | O link de download, no nó de relatório | +| `{{ctx.template_name}}` | O nome do modelo de relatório, no nó de relatório | + +Os modelos fazem substituição simples. Não há avaliação de expressões, execução de código, nem acesso a atributos de objetos em nenhum lugar da configuração de uma regra. + +## Testando uma regra com segurança + +A ordem recomendada para uma regra que envia algo: + +1. Construa o grafo e use o **Preview** até que a contagem de itens pareça correta. +2. Salve-a. Novas regras são criadas desativadas. +3. Deixe o modo em **Simulate** e ative a regra. +4. Deixe-a executar, depois leia **Deliveries** e verifique se as cargas (payloads) registradas são as que você pretendia. +5. Mude o modo para **Live**. + +Simulate não é uma execução parcial. Toda edição de Achado no grafo acontece de verdade no modo de simulação. Somente os envios de saída são retidos. diff --git a/docs/content/automation/rules_engine_2/building_rules.zh-hans.md b/docs/content/automation/rules_engine_2/building_rules.zh-hans.md new file mode 100644 index 0000000000..f63b104054 --- /dev/null +++ b/docs/content/automation/rules_engine_2/building_rules.zh-hans.md @@ -0,0 +1,197 @@ +--- +title: 构建规则 +description: 图形编辑器、触发器、作用范围、条件和消息模板 +weight: 2 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/building_rules/ +--- + +注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。 + +规则是在画布上构建的。您从调色板中拖出节点，将它们连接起来，并在侧边面板中配置每一个节点。本页介绍的是这一过程中不论使用哪些节点都相同的部分。节点本身的说明请见[节点参考](../node_reference/)。 + +## 编辑器 + +打开 **Rules Engine 2.0 > All Rules**，选择 **New Rule**，或打开一条已有规则进行编辑。 + +调色板分为四个类别，这也是条目在典型图中流动的顺序： + +| Category | What the nodes do | +|----------|-------------------| +| **Triggers（触发器）** | 决定规则何时被唤醒，以及哪些发现项会进入规则。每张图恰好一个。 | +| **Logic（逻辑）** | 对流经的条目进行路由、限流和去重。 | +| **Findings（发现项）** | 更改发现项。 | +| **Egress（出站）** | 向外发送内容：工单、消息、报告。 | + +调色板是由引擎本身生成的，因此您在编辑器中看到的内容，始终与引擎能够执行的内容完全一致。 + +### 图的规则 + +图会在您保存时被检查，并在每次运行前再次检查。它必须满足以下所有条件： + +* 至少包含一个节点。 +* **恰好包含一个**触发器节点。 +* 每个节点都有一个唯一、非空、长度不超过 100 个字符的 id。 +* 每个节点都是引擎能识别的类型。 +* 每条边连接的两个节点都真实存在。 +* 不包含环。 + +一个没有任何连线接入的节点是合法的。它会以空输入列表运行，通常这意味着它不会执行任何操作。 + +拥有多条入边的节点，会收到这些入边所有输出拼接后的结果。 + +### 保存前进行预览 + +**Preview（预览）**会对您当前画布上的图进行一次空跑，并向您展示它会产生的按节点追踪结果：有多少条目进入每个节点、有多少从每个输出离开，以及每个节点原本会做出哪些更改。 + +Preview 运行的是真实引擎，而不是它的模拟版本，然后会将整个过程回滚。不会写入任何内容，不会记录任何运行，且无论规则的模式如何设置，出站都会被强制模拟。这是检验您的条件是否符合预期的最快方式。 + +Preview 是唯一会限制其查看的发现项数量的执行方式，以保持速度。当它发生截断时，会在追踪记录中说明这一点。真实运行没有这样的上限。 + +## 触发器与作用范围 + +每张图都以三种触发器之一开始。 + +* **On Finding Event（发现项事件触发）**会在发现项被创建、更新、关闭或重新打开时唤醒规则。可在节点的 **Event** 设置中选择这四者中的哪一个，或选择 `any` 表示全部四种。 +* **On a Schedule（按计划触发）**会按照重复的计划周期扫描发现项。 +* **Manual Run（手动运行）**会在您对该规则按下 **Run** 时扫描发现项。 + +### 作用范围（Scope） + +三种触发器都接受一个**作用范围（Scope）**，作用范围就是您用来缩小规则考虑范围的方式。它使用的过滤器词汇表与原有 Rules Engine 相同，涵盖发现项及其周边对象的大约六十个过滤器，因此您在那里已经会写的过滤器，在这里含义相同。 + +关于作用范围，有两点值得了解： + +* **作用范围是叠加在授权之上的，绝不会取代授权。** 规则以其所有者的身份运行，因此作用范围是在一组已获授权的发现项之上做进一步缩小。将作用范围留空，并不意味着“实例中的每一个发现项”，而是意味着“规则所有者能看到的每一个发现项”。 +* **无效的作用范围会导致运行失败，而不是放宽范围。** 如果某个过滤器键不存在，或某个值是该过滤器会默默丢弃的值，运行就会报错退出。什么都不做的规则是可以恢复的；悄悄编辑实例中每一个发现项的规则则不可以。 + +对于事件触发器，作用范围充当第二道关卡：事件中指定的发现项会先与作用范围进行匹配，只有通过的那些才会进入图中。 + +### 计划调度 + +触发器为 **On a Schedule** 的规则，其计划是在该规则自身上设置的。设置计划需要 Rule Edit 权限，与编辑规则所需的权限相同，因为一条以计划触发的规则在拥有计划之前完全不会执行任何操作。 + +计划仅限设置在每刻钟的整点上。cron 表达式的分钟字段必须是 `0`、`15`、`30` 或 `45`。 + +有效示例： + +``` +0 * * * * every hour, on the hour +15 9 * * * every day at 09:15 +0 15 * * 1 every Monday at 15:00 +30 2 * * * every day at 02:30 +``` + +## 引用发现项数据 + +规则中有两个地方会从流经它的条目中读取值：**条件（conditions）**和**模板（templates）**。两者使用相同的点号路径。 + +``` +finding.severity +finding.title +finding.vulnerability_ids.0 +product.name +product_type.name +test.scan_type +ctx.rule_name +``` + +无法解析的路径不会产生错误，而是不产生任何值。 + +### 可用字段 + +每个条目都携带一组固定的发现项字段。这份列表是一份契约，因此只会经过深思熟虑之后才会更改。 + +| Group | Fields | +|-------|--------| +| 标识 | `id`, `title`, `hash_code`, `unique_id_from_tool` | +| 严重程度与评分 | `severity`, `numerical_severity`, `cvssv3`, `cvssv3_score`, `epss_score`, `epss_percentile`, `priority`, `risk`, `risk_score` | +| 文本 | `description`, `mitigation`, `impact` | +| 状态 | `active`, `verified`, `false_p`, `duplicate`, `is_mitigated`, `out_of_scope`, `risk_accepted`, `under_review` | +| 日期 | `date`, `mitigated`, `last_status_update`, `sla_expiration_date` | +| 位置 | `file_path`, `line`, `component_name`, `component_version`, `service` | +| 分类 | `cwe`, `vulnerability_ids`, `tags` | + +除 `finding` 外，每个条目还携带 `test`（`id`、`title`、`scan_type`）、`engagement`（`id`、`name`）、`product`（`id`、`name`）、`product_type`（`id`、`name`）以及 `ctx`。 + +日期是 ISO-8601 字符串。这是刻意为之的：这意味着 `gt` 和 `lt` 作为文本比较时也能正确排序，因此 `2026-07-28` 会被正确判定为大于 `2026-01-01`。 + +`priority`、`risk` 和 `risk_score` 来自 Pro 的优先级排序功能。尚未被评分的发现项不会携带这些值。 + +### 条件 + +**If / Filter** 节点保存一份条件行的列表。每一行由一个路径、一个运算符和一个值组成。**Match** 决定是要求每一行都成立（`all`），还是只要其中一行成立即可（`any`）。 + +| Operator | Meaning | +|----------|---------| +| `eq` | 等于 | +| `neq` | 不等于 | +| `contains` | 包含 | +| `not_contains` | 不包含 | +| `in` | 属于其中之一 | +| `not_in` | 不属于其中任何一个 | +| `gt` | 大于 | +| `gte` | 大于或等于 | +| `lt` | 小于 | +| `lte` | 小于或等于 | +| `startswith` | 以……开头 | +| `endswith` | 以……结尾 | +| `exists` | 已设置 | +| `not_exists` | 未设置 | + +比较是**宽松的**。会先尝试按数字比较，如果失败，则将两个值作为去除首尾空白、不区分大小写的文本进行比较。因此写成 `finding.severity eq high` 的条件，能匹配到严重程度为 `High` 的发现项，这几乎总是作者原本的意图。 + +#### 转换（Transforms） + +条件行可以在比较之前，对读取到的值做后处理。 + +| Transform | Effect | +|-----------|--------| +| `int` | 整数 | +| `float` | 小数 | +| `str` | 文本 | +| `first` | 列表的第一项 | +| `list` | 作为列表 | +| `join` | 用逗号连接 | +| `upper` | 转为大写 | +| `lower` | 转为小写 | +| `strip` | 去除首尾空白 | +| `cwe_int` | CWE 编号 | +| `severity` | 归一化的严重程度，使不同扫描器中 `critical`、`error`、`warning` 之类的值映射到 DefectDojo 的五个等级上 | +| `numerical_severity` | 可排序的严重程度代码，用于比较排序 | + +### 模板 + +任何标记为消息、备注、标题或值的设置项，都接受 `{{ path }}` 占位符，并按每个条目分别解析： + +``` +{{finding.severity}}: {{finding.title}} ({{product.name}}) +``` + +没有值的路径会渲染为空字符串。列表会以逗号连接的形式渲染。 + +模板还能看到一个 `ctx` 区块，携带关于本次运行自身的详情。可用的键取决于具体节点，但常见的有： + +| Placeholder | Meaning | +|-------------|---------| +| `{{ctx.rule_name}}` | 规则的名称 | +| `{{ctx.count}}` | 该消息涵盖的发现项数量 | +| `{{ctx.trigger}}` | 启动本次运行的事件 | +| `{{ctx.findings_html}}` | 渲染后的发现项列表，用于邮件节点 | +| `{{ctx.report_url}}` | 下载链接，用于报告节点 | +| `{{ctx.template_name}}` | 报告模板名称，用于报告节点 | + +模板只是纯粹的替换。规则配置中的任何地方都不存在表达式求值、代码执行或对象属性访问。 + +## 安全地测试规则 + +对于任何会发送内容的规则，建议按以下顺序操作： + +1. 构建图，并使用 **Preview** 直到条目数量看起来正确为止。 +2. 保存。新建的规则是禁用状态。 +3. 将模式保持为 **Simulate**，并启用该规则。 +4. 让它运行，然后查看 **Deliveries**，检查记录下来的载荷是否符合您的预期。 +5. 将模式切换为 **Live**。 + +Simulate 不是部分运行。图中的每一次发现项编辑在模拟模式下都会真实发生，只有出站发送会被拦截。 diff --git a/docs/content/automation/rules_engine_2/configuration.it.md b/docs/content/automation/rules_engine_2/configuration.it.md new file mode 100644 index 0000000000..2b5f8c26c7 --- /dev/null +++ b/docs/content/automation/rules_engine_2/configuration.it.md @@ -0,0 +1,141 @@ +--- +title: Configurazione +description: Impostazioni a livello di deployment per Rules Engine 2.0 +weight: 7 +audience: pro +aliases: +- /it/automation/rules_engine_v2/configuration/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +Rules Engine 2.0 funziona subito, senza configurazione. Le impostazioni di questa pagina servono ai deployment che devono ottimizzare il throughput, la conservazione o la politica di rete in uscita. Tutte vengono applicate allo stesso modo di qualsiasi altra impostazione di DefectDojo (vedere [Configuration](/get_started/open_source/configuration/)). + +Rules Engine 2.0 viene configurato separatamente dal Rules Engine originale. I due motori non condividono alcuna impostazione: un'impostazione `DD_RULES_ENGINE_*` non influisce su Rules Engine 2.0 e un'impostazione `DD_RULES_V2_*` non influisce sul motore originale. + +```python +DD_RULES_V2_EVENT_BATCH=(int, 500), +DD_RULES_V2_CHUNK_SIZE=(int, 1000), +DD_RULES_V2_STALLED_AFTER_MINUTES=(int, 30), +DD_RULES_V2_RUN_TIME_LIMIT_MINUTES=(int, 360), +DD_RULES_V2_ALLOW_PRIVATE_EGRESS=(bool, False), +DD_RULES_V2_DELIVERY_RETENTION_DAYS=(int, 180), +DD_RULES_V2_RUN_RETENTION_DAYS=(int, 180), +DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS=(int, 8000), +DD_RULES_V2_MAX_PER_ITEM_SENDS=(int, 1000), +``` + +## Throughput + +### Riscontri per evento (`DD_RULES_V2_EVENT_BATCH`) + +**Predefinito: 500.** + +Quanti id di Riscontro porta un singolo evento. Gli eventi attraversano un confine asincrono, quindi vengono mantenuti abbastanza piccoli da restare un messaggio economico. Una scrittura più grande si suddivide in più eventi, ciascuno dei quali diventa un run a sé. + +Aumentare questo valore produce run più grandi e meno numerosi. Abbassarlo ne produce di più piccoli e più numerosi. + +### Riscontri per blocco (`DD_RULES_V2_CHUNK_SIZE`) + +**Predefinito: 1000.** + +Quanti Riscontri un run mantiene in memoria alla volta. Un run viene elaborato a blocchi, quindi questo è un parametro di memoria e **non** un tetto a ciò che una regola gestisce: una regola elabora sempre tutto ciò che il suo scope include. + +Un envelope pesa circa 2,7KB per Riscontro, quindi il valore predefinito mantiene in memoria pochi megabyte alla volta. Aumentarlo scambia memoria per un minor numero di andirivieni. Abbassarlo fa il contrario. + +### Limite di testo dell'envelope (`DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS`) + +**Predefinito: 8000. Impostare a 0 per disattivarlo.** + +Quanti caratteri di `description`, `mitigation` e `impact` porta un elemento. + +Quei tre campi rappresentano la maggior parte delle dimensioni di un envelope. Il limite esiste per il caso insolito di un Riscontro con una descrizione molto grande, dove un blocco pieno di questi sarebbe molto più grande di quanto suggerisca la dimensione del blocco. È abbastanza generoso da non farsi mai notare in un'istanza ordinaria. + +Si noti che questo influisce su ciò che condizioni e template possono vedere. Una condizione che confronta la coda di una descrizione molto lunga non vedrà il testo oltre il limite. + +## Durata del run + +### Finestra di stallo (`DD_RULES_V2_STALLED_AFTER_MINUTES`) + +**Predefinito: 30.** + +Per quanto tempo un run può restare senza heartbeat prima di essere considerato abbandonato, contrassegnato come in errore, con il rilascio del suo lock per-regola. + +Un run genera un heartbeat dopo ogni blocco, quindi questo si misura dall'ultimo heartbeat e non dall'inizio. Una scansione lunga che sta ancora facendo progressi non viene mai scambiata per un worker bloccato, ed è questo che permette alla finestra di restare breve. + +### Limite di tempo del run (`DD_RULES_V2_RUN_TIME_LIMIT_MINUTES`) + +**Predefinito: 360, ovvero sei ore.** + +Il tempo massimo che un singolo run può impiegare prima che il worker lo interrompa. + +È una protezione contro una regola che non finirebbe mai, tenendo occupati uno slot del worker e il lock di esecuzione della sua regola. È deliberatamente generoso, perché una scansione a blocchi su uno scope molto ampio è esattamente il carico di lavoro per cui questo motore è stato costruito. + +## Conservazione + +Due job limitano le tre tabelle che questa funzionalità fa crescere. Entrambi hanno come predefinito **180 giorni**, ed entrambi accettano `0` per disattivare completamente l'eliminazione. + +La conservazione è resa visibile nel prodotto invece di restare implicita: l'API restituisce sia la finestra sia la data in cui un dato record verrà eliminato, e le pagine che mostrano un run o una delivery lo indicano in una frase. La data viene calcolata in lettura, quindi modificare la finestra ha effetto immediato invece di applicarsi solo ai nuovi record. + +### `DD_RULES_V2_DELIVERY_RETENTION_DAYS` + +**Predefinito: 180.** + +Per quanti giorni viene conservata una delivery conclusa. + +Questa è la tabella che cresce più rapidamente in questa funzionalità. Un nodo egress per-Riscontro scrive fino a un blocco intero di righe per run, anche in modalità Simulate. Aumentarlo se serve una traccia di controllo in uscita più lunga, abbassarlo se il volume è un problema. + +### `DD_RULES_V2_RUN_RETENTION_DAYS` + +**Predefinito: 180.** + +Per quanti giorni viene conservato un run concluso, insieme alle sue righe per nodo e alla provenienza dei Riscontri. + +Il lato run cresce più rapidamente delle delivery, perché la provenienza è una riga per Riscontro per nodo di modifica per run. Una regola oraria su uno scope ampio ne genera molte. + +Un run che detiene ancora delle delivery viene conservato finché queste non vengono eliminate, quindi impostare una finestra del run più corta di quella delle delivery non lascia nulla orfano. + +## Validazione della destinazione in uscita + +Due impostazioni dei nodi accettano una destinazione come testo libero invece che da un oggetto configurato: l'**URL** su Call a Webhook, e il campo **To** su Send an Email. Entrambe vengono validate al salvataggio della regola. + +Per gli URL dei webhook: + +* Sono accettati solo `http` e `https`. Altri schemi vengono rifiutati direttamente. +* L'URL deve avere un host. +* Per impostazione predefinita, un host che si risolve in un indirizzo loopback, link-local, privato, riservato o multicast viene rifiutato. + +Per gli indirizzi email, un indirizzo vuoto viene rifiutato, così come uno che contiene un a-capo, che costituisce un'iniezione di intestazione. + +Il motivo del controllo di rete è che il worker che invia la richiesta di solito si trova all'interno del cluster e può raggiungere una parte molto più ampia della rete interna rispetto a chi scrive la regola. Senza il controllo, un URL in testo libero è un primitivo di request forgery: puntarlo verso un servizio di metadati o una porta di amministrazione interna, e la risposta torna indietro attraverso il registro delle delivery. + +Questo è un livello di difesa in profondità, non l'unico controllo. Rule Edit è comunque vicino a un permesso amministrativo. Vale la pena averlo affinché il raggio d'azione di un ruolo concesso in modo troppo ampio non sia "leggere qualsiasi endpoint HTTP interno", e affinché un errore di battitura fallisca al salvataggio con un messaggio chiaro invece che all'invio con un errore di connessione. + +### Consentire indirizzi privati (`DD_RULES_V2_ALLOW_PRIVATE_EGRESS`) + +**Predefinito: disattivato.** + +Disattiva il controllo dell'indirizzo di rete, così i webhook possono pubblicare verso indirizzi loopback, link-local e privati. La validazione di schema e formato continua ad applicarsi. + +Attivarlo se effettivamente si invia un webhook verso qualcosa su un indirizzo privato, che è normalmente il caso di una chat o di un ricevitore di webhook self-hosted. + +## Tetto di invii per Riscontro + +### `DD_RULES_V2_MAX_PER_ITEM_SENDS` + +**Predefinito: 1000. Impostare a 0 per rimuovere il tetto.** + +Il numero massimo di invii per Riscontro che un singolo nodo egress registrerà in un run. + +Un nodo con **One Message per Finding** attivato produce una riga di delivery e un task in coda per ogni Riscontro. Poiché un run non ha un limite di elementi, una regola con uno scope molto ampio e l'invio per-Riscontro attivo produrrebbe altrimenti un numero illimitato di entrambi. + +Oltre questo tetto il nodo registra un'**omissione visibile** che indica quanti Riscontri non ha inviato. Non fa fallire il run, e non si ferma silenziosamente. + +## Impostazioni correlate + +Alcuni nodi di Rules Engine 2.0 usano la configurazione di integrazione a livello di sistema invece della propria: + +* **Send a Slack Message** usa il token Slack di sistema, e ricade sul canale Slack di sistema quando il nodo non ne indica uno. +* **Send a Microsoft Teams Message** usa il webhook Microsoft Teams dalle impostazioni di sistema. +* **Create a JIRA Issue** usa la configurazione JIRA del prodotto per il riepilogo, la descrizione e la priorità. +* **Raise an In-App Alert** rispetta l'impostazione di notifica **Rules Engine Match** di ciascun destinatario. diff --git a/docs/content/automation/rules_engine_2/configuration.pt-br.md b/docs/content/automation/rules_engine_2/configuration.pt-br.md new file mode 100644 index 0000000000..a7347f07c8 --- /dev/null +++ b/docs/content/automation/rules_engine_2/configuration.pt-br.md @@ -0,0 +1,141 @@ +--- +title: Configuração +description: Configurações em nível de implantação para o Rules Engine 2.0 +weight: 7 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/configuration/ +--- + +Nota: O Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +O Rules Engine 2.0 funciona pronto para uso. As configurações desta página são para implantações que precisam ajustar throughput, retenção ou a política de rede de saída. Todas elas são aplicadas da mesma forma que qualquer outra configuração do DefectDojo (veja [Configuration](/get_started/open_source/configuration/)). + +O Rules Engine 2.0 é configurado separadamente do Rules Engine original. Os dois mecanismos não compartilham nenhum ajuste, portanto uma configuração `DD_RULES_ENGINE_*` não afeta o Rules Engine 2.0, e uma configuração `DD_RULES_V2_*` não afeta o mecanismo original. + +```python +DD_RULES_V2_EVENT_BATCH=(int, 500), +DD_RULES_V2_CHUNK_SIZE=(int, 1000), +DD_RULES_V2_STALLED_AFTER_MINUTES=(int, 30), +DD_RULES_V2_RUN_TIME_LIMIT_MINUTES=(int, 360), +DD_RULES_V2_ALLOW_PRIVATE_EGRESS=(bool, False), +DD_RULES_V2_DELIVERY_RETENTION_DAYS=(int, 180), +DD_RULES_V2_RUN_RETENTION_DAYS=(int, 180), +DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS=(int, 8000), +DD_RULES_V2_MAX_PER_ITEM_SENDS=(int, 1000), +``` + +## Throughput + +### Achados por evento (`DD_RULES_V2_EVENT_BATCH`) + +**Padrão: 500.** + +Quantos ids de Achado um único evento carrega. Os eventos atravessam uma fronteira assíncrona, portanto são mantidos pequenos o suficiente para continuar sendo uma mensagem barata. Uma gravação maior se espalha em vários eventos, cada um dos quais se torna sua própria execução. + +Aumentar esse valor produz execuções mais raras e maiores. Diminuí-lo produz execuções mais frequentes e menores. + +### Achados por bloco (`DD_RULES_V2_CHUNK_SIZE`) + +**Padrão: 1000.** + +Quantos Achados uma execução mantém na memória de uma vez. Uma execução é processada em blocos (chunks), portanto isso é um ajuste de memória e **não** um limite para o que uma regra processa: uma regra sempre processa tudo o que seu escopo corresponde. + +Um envelope tem aproximadamente 2,7 KB por Achado, portanto o padrão ocupa alguns megabytes de cada vez. Aumentá-lo troca memória por menos idas e voltas. Diminuí-lo faz o oposto. + +### Limite de texto do envelope (`DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS`) + +**Padrão: 8000. Defina como 0 para desativar.** + +Quantos caracteres de `description`, `mitigation` e `impact` um item carrega. + +Esses três campos correspondem à maior parte do tamanho de um envelope. O limite existe para o caso incomum de um Achado com uma descrição muito grande, em que um bloco cheio deles seria muito maior do que o tamanho do bloco sugere. Ele é generoso o suficiente para que uma instância comum nunca perceba isso. + +Observe que isso afeta o que condições e modelos conseguem ver. Uma condição que compara com o final de uma descrição muito longa não verá texto além do limite. + +## Ciclo de vida da execução + +### Janela de estagnação (`DD_RULES_V2_STALLED_AFTER_MINUTES`) + +**Padrão: 30.** + +Por quanto tempo uma execução pode ficar sem uma pulsação (heartbeat) antes de ser tratada como abandonada, marcada como com erro, e ter seu bloqueio por regra liberado. + +Uma execução registra uma pulsação após cada bloco, portanto isso é medido a partir da última pulsação, e não do início. Uma varredura longa que ainda está progredindo nunca é confundida com um worker travado, o que é o que permite manter a janela curta. + +### Limite de tempo de execução (`DD_RULES_V2_RUN_TIME_LIMIT_MINUTES`) + +**Padrão: 360, que são seis horas.** + +O tempo máximo que uma única execução pode levar antes de o worker encerrá-la. + +Isso é uma proteção contra uma regra que nunca terminaria enquanto ocupa um slot de worker e o bloqueio de execução da sua regra. É deliberadamente generoso, porque uma varredura em blocos sobre um escopo muito grande é exatamente o tipo de carga de trabalho para o qual este mecanismo foi construído. + +## Retenção + +Duas tarefas limitam as três tabelas que este recurso faz crescer. Ambas usam **180 dias** por padrão, e ambas aceitam `0` para desativar completamente a limpeza (pruning). + +A retenção é exposta no produto, em vez de ficar implícita: a API fornece tanto a janela quanto a data em que um determinado registro será excluído, e as páginas que mostram uma execução ou uma entrega informam isso em uma frase. A data é calculada no momento da leitura, portanto alterar a janela tem efeito imediato, em vez de se aplicar apenas a novos registros. + +### `DD_RULES_V2_DELIVERY_RETENTION_DAYS` + +**Padrão: 180.** + +Por quantos dias uma entrega concluída é mantida. + +Esta é a tabela que mais cresce no recurso. Um nó de saída por Achado grava até o equivalente a um bloco de linhas por execução, inclusive no modo Simulate. Aumente-a se precisar de uma trilha de auditoria de saída mais longa, e diminua-a se o volume for um problema. + +### `DD_RULES_V2_RUN_RETENTION_DAYS` + +**Padrão: 180.** + +Por quantos dias uma execução concluída é mantida, junto com suas linhas por nó e sua proveniência de Achados. + +O lado das execuções cresce mais rápido do que o das entregas, porque a proveniência é uma linha por Achado por nó de mutação por execução. Uma regra que roda de hora em hora sobre um escopo grande gera muito disso. + +Uma execução que ainda contém entregas é mantida até que essas sejam removidas, portanto definir uma janela de execução mais curta do que a janela de entrega não deixa nada órfão. + +## Validação de destino de saída + +Duas configurações de nó recebem um destino como texto livre, em vez de a partir de um objeto configurado: a **URL** em Call a Webhook, e o **To** em Send an Email. Ambas são validadas quando a regra é salva. + +Para URLs de webhook: + +* Somente `http` e `https` são aceitos. Outros esquemas são rejeitados de imediato. +* A URL precisa ter um host. +* Por padrão, um host que resolve para um endereço loopback, link-local, privado, reservado ou multicast é rejeitado. + +Para endereços de e-mail, um endereço vazio é rejeitado, assim como um que contenha uma quebra de linha, o que caracteriza injeção de cabeçalho. + +O motivo dessa verificação de rede é que o worker que envia a requisição geralmente fica dentro do seu cluster e consegue alcançar uma parte muito maior da rede interna do que a pessoa que escreve a regra consegue. Sem essa verificação, uma URL em texto livre é um primitivo de falsificação de requisição: aponte-a para um serviço de metadados ou uma porta administrativa interna, e a resposta volta através do registro de entregas. + +Isso é defesa em profundidade, e não o único controle. Rule Edit já está próxima de ser uma permissão administrativa de qualquer forma. Vale a pena tê-la para que o raio de alcance de uma função concedida em excesso não seja "ler qualquer endpoint HTTP interno", e para que um erro de digitação falhe no momento de salvar, com uma mensagem clara, em vez de no momento do envio, com um erro de conexão. + +### Permitindo endereços privados (`DD_RULES_V2_ALLOW_PRIVATE_EGRESS`) + +**Padrão: desativado.** + +Desativa a verificação de endereço de rede, de modo que os webhooks possam enviar para endereços loopback, link-local e privados. A validação de esquema e formato continua se aplicando. + +Ative isso se você realmente usa webhook para algo em um endereço privado, o que geralmente é o caso de um chat ou receptor de webhook auto-hospedado. + +## Limite de envios por Achado + +### `DD_RULES_V2_MAX_PER_ITEM_SENDS` + +**Padrão: 1000. Defina como 0 para remover o limite.** + +O número máximo de envios por Achado que um único nó de saída registrará em uma execução. + +Um nó com **One Message per Finding** ativado produz uma linha de entrega e uma tarefa enfileirada por Achado. Como uma execução não tem limite de itens, uma regra com um escopo muito amplo e envio por Achado ativado significaria, de outra forma, um número ilimitado de ambos. + +Após esse limite, o nó registra uma **omissão visível (visible skip)** informando quantos Achados não tiveram envio realizado. Isso não faz a execução falhar, nem para silenciosamente. + +## Configurações relacionadas + +Alguns nós do Rules Engine 2.0 usam a configuração de integração de todo o sistema, em vez da própria: + +* **Send a Slack Message** usa o token do Slack do sistema, e recorre ao canal do Slack do sistema quando o nó não indica nenhum. +* **Send a Microsoft Teams Message** usa o webhook do Microsoft Teams das configurações do sistema. +* **Create a JIRA Issue** usa a configuração do JIRA do produto para o resumo, a descrição e a prioridade. +* **Raise an In-App Alert** respeita a própria configuração de notificação **Rules Engine Match** de cada destinatário. diff --git a/docs/content/automation/rules_engine_2/configuration.zh-hans.md b/docs/content/automation/rules_engine_2/configuration.zh-hans.md new file mode 100644 index 0000000000..e43bd7ec36 --- /dev/null +++ b/docs/content/automation/rules_engine_2/configuration.zh-hans.md @@ -0,0 +1,141 @@ +--- +title: 配置 +description: Rules Engine 2.0 的部署层面设置 +weight: 7 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/configuration/ +--- + +注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。 + +Rules Engine 2.0 开箱即用。本页的设置面向那些需要调整吞吐量、保留期或出站网络策略的部署环境。所有这些设置的应用方式都与其他任何 DefectDojo 设置相同（参见[配置](/get_started/open_source/configuration/)）。 + +Rules Engine 2.0 与原有的 Rules Engine 分开配置。两套引擎不共享任何调优参数，因此 `DD_RULES_ENGINE_*` 设置不会影响 Rules Engine 2.0，`DD_RULES_V2_*` 设置也不会影响原有引擎。 + +```python +DD_RULES_V2_EVENT_BATCH=(int, 500), +DD_RULES_V2_CHUNK_SIZE=(int, 1000), +DD_RULES_V2_STALLED_AFTER_MINUTES=(int, 30), +DD_RULES_V2_RUN_TIME_LIMIT_MINUTES=(int, 360), +DD_RULES_V2_ALLOW_PRIVATE_EGRESS=(bool, False), +DD_RULES_V2_DELIVERY_RETENTION_DAYS=(int, 180), +DD_RULES_V2_RUN_RETENTION_DAYS=(int, 180), +DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS=(int, 8000), +DD_RULES_V2_MAX_PER_ITEM_SENDS=(int, 1000), +``` + +## 吞吐量 + +### 每个事件的发现项数量（`DD_RULES_V2_EVENT_BATCH`） + +**默认值：500。** + +一个事件携带多少个发现项 id。事件要跨越一个异步边界，因此要保持足够小，以维持消息的低成本。较大的写入会分散成多个事件，每个事件都会成为一次独立的运行。 + +调高该值会产生更少、更大的运行；调低则会产生更多、更小的运行。 + +### 每个分块的发现项数量（`DD_RULES_V2_CHUNK_SIZE`） + +**默认值：1000。** + +一次运行同时在内存中保留多少个发现项。运行是按分块处理的，因此这是一个内存旋钮，而**不是**规则处理量的上限：规则始终会处理其作用范围匹配到的全部内容。 + +每个发现项的信封（envelope）大小大约是 2.7KB，因此默认值一次会占用几兆字节的内存。调高它是用内存换取更少的往返次数；调低则相反。 + +### 信封文本上限（`DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS`） + +**默认值：8000。设为 0 可禁用。** + +条目携带的 `description`、`mitigation` 和 `impact` 字符数上限。 + +这三个字段占据了信封大小的大部分。设置该上限是为了应对一种特殊情况：某个发现项的描述非常长，以至于满满一个分块的大小会远超分块大小设置暗示的规模。这个上限相当宽松，一般实例根本不会察觉到它的存在。 + +请注意，这会影响条件和模板所能看到的内容。针对一段很长描述的末尾进行匹配的条件，将看不到超出该上限的文本。 + +## 运行生命周期 + +### 停滞窗口（`DD_RULES_V2_STALLED_AFTER_MINUTES`） + +**默认值：30。** + +一次运行在被视为已放弃、标记为出错、并释放其按规则加的锁之前，可以有多久没有心跳。 + +运行在每个分块处理完后都会打一次心跳，因此这个时长是从最近一次心跳开始计算的，而不是从运行开始时计算。一次仍在推进的长时间扫描永远不会被误判为已崩溃的工作进程，这正是该窗口得以保持较短的原因。 + +### 运行时长上限（`DD_RULES_V2_RUN_TIME_LIMIT_MINUTES`） + +**默认值：360，即六小时。** + +单次运行在被工作进程终止之前，最长可以运行多久。 + +这是为了防范某条规则永远无法完成、却一直占用工作进程槽位及其规则执行锁的情况。这个值被有意设得比较宽松，因为对一个非常大的作用范围进行分块扫描，正是本引擎所要应对的工作负载类型。 + +## 保留期 + +有两个任务负责限制该功能所产生的三张表的大小。两者默认都是 **180 天**，都可以设为 `0` 以完全禁用清理。 + +保留期在产品中是明确呈现的，而非隐晦不明的：API 会同时提供保留窗口以及某条记录将被删除的具体日期，展示某次运行或某条投递记录的页面也会用一句话说明这一点。日期是在读取时计算的，因此更改窗口会立即生效，而不是只对新记录生效。 + +### `DD_RULES_V2_DELIVERY_RETENTION_DAYS` + +**默认值：180。** + +一条已完成的投递记录会被保留多少天。 + +这是该功能中增长最快的表。一个按发现项处理的出站节点，每次运行都可能写入多达一整个分块数量的行，模拟模式下也不例外。如果您需要更长的出站审计轨迹就调高它，如果数据量成为问题就调低它。 + +### `DD_RULES_V2_RUN_RETENTION_DAYS` + +**默认值：180。** + +一次已完成的运行，连同其按节点的记录行及其发现项溯源信息，会被保留多少天。 + +运行这一侧的增长比投递记录更快，因为溯源信息是“每次运行、每个更改类节点、每个发现项”各一行。一条针对大范围作用域每小时运行一次的规则，会产生大量此类数据。 + +一次仍持有投递记录的运行，会一直保留到那些投递记录被清理为止，因此将运行的保留窗口设得比投递记录的保留窗口短，并不会产生孤立数据。 + +## 出站目的地校验 + +有两个节点设置以自由文本形式接受目的地，而不是从已配置的对象中选择：Call a Webhook 节点上的 **URL**，以及 Send an Email 节点上的 **To**。两者都会在保存规则时进行校验。 + +对于 Webhook URL： + +* 只接受 `http` 和 `https`。其他协议一律拒绝。 +* URL 必须包含主机（host）。 +* 默认情况下，解析到回环地址、链路本地地址、私有地址、保留地址或组播地址的主机会被拒绝。 + +对于电子邮件地址，空地址会被拒绝，包含换行符的地址也会被拒绝，因为那属于请求头注入。 + +之所以要做网络校验，是因为发送请求的工作进程通常位于您的集群内部，能够触及的内部网络范围，远超编写该规则的人所能触及的范围。如果没有这项检查，一个自由文本形式的 URL 就是一个请求伪造原语：把它指向某个元数据服务或内部管理端口，响应就会通过投递记录台账被带回来。 + +这是纵深防御，而非唯一的控制手段。反正 Rule Edit 本来就接近于管理权限。设置这项检查的价值在于，让某个被过度授予的角色所造成的影响范围，不至于是“可读取任意内部 HTTP 端点”，也让一次拼写错误能在保存时就以清晰的错误信息失败，而不是在发送时以连接错误的形式失败。 + +### 允许私有地址（`DD_RULES_V2_ALLOW_PRIVATE_EGRESS`） + +**默认值：关闭。** + +关闭网络地址检查，使 Webhook 可以向回环地址、链路本地地址和私有地址发送请求。协议和格式校验仍然适用。 + +如果您确实需要向某个私有地址上的服务发送 Webhook——自托管的聊天或 Webhook 接收端通常就是这种情况——可以开启此项。 + +## 每个发现项的发送上限 + +### `DD_RULES_V2_MAX_PER_ITEM_SENDS` + +**默认值：1000。设为 0 可取消上限。** + +单个出站节点在一次运行中，针对每个发现项最多记录的发送次数。 + +启用了**每个发现项一条消息（One Message per Finding）**的节点，会为每个发现项产生一条投递记录行和一个排队任务。由于一次运行没有条目数量上限，作用范围非常宽、又开启了按发现项发送的规则，否则会导致两者的数量都变得没有边界。 + +超过该上限后，节点会记录一次**可见的跳过（visible skip）**，说明有多少个发现项没有被发送。它不会导致运行失败，也不会悄无声息地停止。 + +## 相关设置 + +部分 Rules Engine 2.0 节点使用的是系统级的集成配置，而不是节点自身的配置： + +* **Send a Slack Message** 使用系统级的 Slack 令牌，如果节点未指定频道，则回退使用系统级的 Slack 频道。 +* **Send a Microsoft Teams Message** 使用系统设置中的 Microsoft Teams Webhook。 +* **Create a JIRA Issue** 使用产品的 JIRA 配置来填写摘要、描述和优先级。 +* **Raise an In-App Alert** 会遵循每位接收者自己的 **Rules Engine Match** 通知设置。 diff --git a/docs/content/automation/rules_engine_2/converting_from_rules_engine.it.md b/docs/content/automation/rules_engine_2/converting_from_rules_engine.it.md new file mode 100644 index 0000000000..bb464e3ab1 --- /dev/null +++ b/docs/content/automation/rules_engine_2/converting_from_rules_engine.it.md @@ -0,0 +1,90 @@ +--- +title: Conversione da Rules Engine +description: Spostare le regole esistenti di Rules Engine nei grafi di Rules Engine + 2.0 +weight: 6 +audience: pro +aliases: +- /it/automation/rules_engine_v2/converting_from_rules_engine/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +I due motori funzionano fianco a fianco. Attivare Rules Engine 2.0 non cambia nulla delle regole [Rules Engine](/automation/rules_engine/about/) esistenti, e non c'è una scadenza entro cui spostarle. + +Quando si vuole spostarle, esiste un convertitore. Traduce una regola di Rules Engine (un filtro più un elenco ordinato di azioni) in un grafo Rules Engine 2.0 equivalente. + +## Cosa garantisce il convertitore + +**Una regola o si converte in modo pulito, o non si converte affatto.** Ogni conversione riporta due tipi di esito: + +* I **Problemi** significano che la regola non è stata scritta. Non viene salvato nulla di parziale. +* Gli **Avvisi** significano che la regola si è convertita, ma qualcosa in essa è cambiato e va controllato. + +Nulla viene approssimato silenziosamente. Tutto il valore del convertitore sta nel poter fidarsi di una regola convertita senza segnalazioni, e nel controllare a mano una che non lo è stata. + +**Le regole convertite vengono sempre create disabilitate.** Entrambi i motori sono in esecuzione, e avere due regole che fanno la stessa cosa sugli stessi Riscontri è l'unico esito che un convertitore non deve mai produrre da solo. Rivedere ogni regola convertita e abilitarla deliberatamente. + +**Una regola si converte una sola volta.** Ogni regola convertita ricorda da quale regola proviene, quindi eseguire il convertitore due volte salta ciò che ha già fatto invece di creare duplicati. Usare l'opzione di sovrascrittura per sostituire deliberatamente un grafo convertito in precedenza. + +## Eseguire il convertitore + +### Dalla UI + +L'elenco delle regole offre un'azione di conversione, che riporta per ogni regola cosa si è convertito, cosa è stato saltato e cosa è fallito. + +### Dalla riga di comando + +```bash +python manage.py convert_rules_to_v2 +``` + +| Opzione | Effetto | +|--------|--------| +| `--dry-run` | Stampa il grafo che ogni regola produrrebbe e non scrive nulla. | +| `--rule-ids 1,2,3` | Converte solo queste regole. Le converte tutte se omesso. | +| `--overwrite` | Sostituisce il grafo di una regola già convertita e ne incrementa la versione, invece di saltarla. | +| `--activate-schedules` | Copia anche ogni pianificazione sulla regola convertita corrispondente. Disattivato per impostazione predefinita. | +| `--drop-invalid-filters` | Elimina i filtri di scope che il set di filtri non riconosce più e avvisa, invece di far fallire la regola. | +| `--json` | Stampa il report come JSON invece che come testo. | + +Il comando termina con un codice diverso da zero solo quando una regola non riesce a convertirsi. Le omissioni vengono riportate ma non sono fallimenti. + +Iniziare con `--dry-run` sull'intero set per vedere a cosa si va incontro, poi convertire per davvero. + +## Cosa produce la conversione + +| Concetto di Rules Engine | Diventa | +|----------------------|---------| +| Il filtro della regola | Lo **Scope** sul nodo trigger. | +| Una regola con una pianificazione | Un trigger **On a Schedule**. | +| Una regola senza pianificazione | Un trigger **Manual Run**. | +| Ogni azione, in ordine | Un nodo, concatenato nello stesso ordine. | +| Un'azione condizionata da una condizione | Un nodo **If / Filter** davanti a quel nodo. | + +Il vocabolario dei filtri è condiviso tra i due motori, quindi uno scope si converte senza traduzione. Questo è deliberato: è lo stesso set di filtri, con un'unica implementazione. + +I grafi convertiti vengono validati allo stesso modo di un grafo costruito a mano, inclusa la configurazione per nodo e i valori consentiti di ogni menu a tendina. Una regola che contiene un valore di gravità o di rischio da cui il prodotto è nel frattempo passato oltre viene intercettata alla conversione invece che in fase di esecuzione. + +## Cosa non viene trasferito + +Quattro cose da tenere presenti. Il convertitore le riporta come note a ogni esecuzione. + +* **La cronologia dei run resta dov'è.** La cronologia di esecuzione esistente, e i relativi record interessati e saltati, rimangono nella UI di Rules Engine. Non vengono copiati. +* **Le pianificazioni non vengono attivate per impostazione predefinita.** Una regola attivata da pianificazione si converte, ma la sua pianificazione non viene copiata a meno di passare `--activate-schedules`. Questo mantiene la proprietà esclusiva delle pianificazioni attive nel motore originale finché entrambi sono in esecuzione, così una regola convertita non può iniziare a scattare di nascosto. Quando si copia effettivamente una pianificazione, alla copia viene dato un nome distinto in modo che non collida con l'originale. +* **Il modello di concorrenza è diverso.** Rules Engine ha un unico lock di esecuzione a livello di istanza. Rules Engine 2.0 serializza per regola, quindi regole distinte vengono eseguite in concorrenza. Un insieme di regole che prima si alternava ora si sovrapporrà. +* **Un'azione non ha equivalente.** Un'azione "imposta falso positivo a falso" non può essere espressa come nodo di Rules Engine 2.0 e deve essere convertita a mano. + +Una regola il cui proprietario non è impostato si converte, con un avviso. Ricordare che una regola senza proprietario non vede alcun Riscontro, quindi assegnarne uno prima di abilitarla. + +## Un ordine suggerito + +1. Attivare Rules Engine 2.0 e lasciare in esecuzione le regole esistenti. +2. Eseguire il convertitore con `--dry-run` e leggere il report. +3. Convertire. Tutto viene creato disabilitato. +4. Aprire ogni regola convertita, controllare il grafo, e lasciare la modalità su **Simulate**. +5. Abilitare la regola convertita, e lasciarla in esecuzione insieme all'originale per un po'. Simulate significa che modifica i Riscontri ma non invia nulla, quindi confrontare le sue esecuzioni con quanto faceva l'originale. +6. Quando si è soddisfatti, disabilitare la regola originale e passare quella convertita a **Live**. +7. Copiare la pianificazione per ultima, una volta che nulla sta più eseguendo la vecchia regola. + +Il passaggio 5 è quello che vale la pena non saltare. Vedere i due motori modificare gli stessi Riscontri va bene, ma si vuole essere chi decide quando iniziano gli invii. diff --git a/docs/content/automation/rules_engine_2/converting_from_rules_engine.pt-br.md b/docs/content/automation/rules_engine_2/converting_from_rules_engine.pt-br.md new file mode 100644 index 0000000000..60ecb42c85 --- /dev/null +++ b/docs/content/automation/rules_engine_2/converting_from_rules_engine.pt-br.md @@ -0,0 +1,89 @@ +--- +title: Migrando do Rules Engine +description: Migre regras existentes do Rules Engine para grafos do Rules Engine 2.0 +weight: 6 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/converting_from_rules_engine/ +--- + +Nota: O Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +Os dois mecanismos funcionam lado a lado. Ativar o Rules Engine 2.0 não muda nada em suas regras existentes do [Rules Engine](/automation/rules_engine/about/), e não há um prazo até o qual você precise migrá-las. + +Quando você quiser migrá-las, existe um conversor. Ele traduz uma regra do Rules Engine (um filtro mais uma lista ordenada de ações) em um grafo equivalente do Rules Engine 2.0. + +## O que o conversor garante + +**Uma regra é convertida por completo ou não é convertida de forma alguma.** Toda conversão relata dois tipos de resultado: + +* **Problems** significam que a regra não foi escrita. Nada parcial é salvo. +* **Warnings** significam que a regra foi convertida, mas algo nela mudou e você deveria dar uma olhada. + +Nada é aproximado silenciosamente. Todo o valor do conversor está em você poder confiar em uma regra que converteu sem ressalvas, e verificar manualmente uma que não converteu. + +**Regras convertidas são sempre criadas desativadas.** Os dois mecanismos estão em execução, e duas regras fazendo a mesma coisa com os mesmos Achados é o único resultado que um conversor nunca deve produzir por conta própria. Revise cada regra convertida e ative-a deliberadamente. + +**Uma regra converte uma única vez.** Cada regra convertida lembra de qual regra ela veio, portanto executar o conversor duas vezes ignora o que já foi feito, em vez de criar duplicatas. Use a opção de sobrescrever para substituir deliberadamente um grafo convertido anteriormente. + +## Executando o conversor + +### Pela interface (UI) + +A lista de regras oferece uma ação de conversão, que informa, por regra, o que foi convertido, o que foi ignorado e o que falhou. + +### Pela linha de comando + +```bash +python manage.py convert_rules_to_v2 +``` + +| Opção | Efeito | +|--------|--------| +| `--dry-run` | Imprime o grafo que cada regra produziria e não grava nada. | +| `--rule-ids 1,2,3` | Converte somente essas regras. Converte todas as regras quando omitido. | +| `--overwrite` | Substitui o grafo de uma regra já convertida e incrementa sua versão, em vez de ignorá-la. | +| `--activate-schedules` | Também copia cada programação para a sua regra convertida. Desativado por padrão. | +| `--drop-invalid-filters` | Descarta os filtros de escopo que o conjunto de filtros não reconhece mais e emite um aviso, em vez de falhar a regra. | +| `--json` | Imprime o relatório em JSON em vez de texto. | + +O comando termina com código diferente de zero somente quando uma regra falha ao converter. Itens ignorados são relatados, mas não são falhas. + +Comece com `--dry-run` no conjunto completo para ver no que você está se metendo, depois converta de verdade. + +## O que a conversão produz + +| Conceito do Rules Engine | Torna-se | +|----------------------|---------| +| O filtro da regra | O **Scope** no nó de gatilho. | +| Uma regra com uma programação | Um gatilho **On a Schedule**. | +| Uma regra sem programação | Um gatilho **Manual Run**. | +| Cada ação, em ordem | Um nó, encadeado na mesma ordem. | +| Uma ação protegida por uma condição | Um nó **If / Filter** na frente desse nó. | + +O vocabulário de filtros é compartilhado entre os dois mecanismos, portanto um escopo é convertido sem tradução. Isso é proposital: é o mesmo conjunto de filtros, com uma única implementação. + +Os grafos convertidos são validados da mesma forma que um grafo construído manualmente, incluindo a configuração por nó e os valores permitidos de cada menu suspenso. Uma regra que contém um valor de severidade ou de risco que o produto já deixou de usar é detectada na conversão, e não em tempo de execução. + +## O que não é migrado + +Quatro coisas para planejar. O conversor relata essas informações como notas em cada execução. + +* **O histórico de execuções permanece onde está.** O histórico de execuções existente, junto com seus registros afetados e ignorados, permanece na interface do Rules Engine. Eles não são copiados. +* **As programações não são ativadas por padrão.** Uma regra disparada por agendamento é convertida, mas sua programação não é copiada a menos que você passe `--activate-schedules`. Isso mantém a propriedade exclusiva das programações ativas com o mecanismo original enquanto os dois estão em execução, de modo que uma regra convertida não pode começar a disparar sem você perceber. Quando você copia uma programação, a cópia recebe um nome distinto para não colidir com a original. +* **O modelo de concorrência é diferente.** O Rules Engine tem um único bloqueio de execução para toda a instância. O Rules Engine 2.0 serializa por regra, portanto regras distintas são executadas simultaneamente. Um conjunto de regras que costumava se revezar agora vai se sobrepor. +* **Uma ação não tem equivalente.** Uma ação de "definir falso positivo como falso" não pode ser expressa como um nó do Rules Engine 2.0 e precisa ser convertida manualmente. + +Uma regra cujo proprietário não está definido é convertida, com um aviso. Lembre-se de que uma regra sem proprietário não vê nenhum Achado, portanto atribua um antes de ativá-la. + +## Uma ordem sugerida + +1. Ative o Rules Engine 2.0 e deixe suas regras existentes em execução. +2. Execute o conversor com `--dry-run` e leia o relatório. +3. Converta. Tudo é criado desativado. +4. Abra cada regra convertida, verifique o grafo e deixe o modo em **Simulate**. +5. Ative a regra convertida e deixe-a rodar ao lado da original por um tempo. Simulate significa que ela altera Achados, mas não envia nada, portanto compare suas execuções com o que a original fez. +6. Quando estiver satisfeito, desative a regra original e mude a convertida para **Live**. +7. Copie a programação por último, quando nada mais estiver executando a regra antiga. + +O passo 5 é o que mais vale a pena não pular. Os dois mecanismos editando os mesmos Achados é algo tranquilo de observar, mas você quer ser quem decide quando os envios começam. diff --git a/docs/content/automation/rules_engine_2/converting_from_rules_engine.zh-hans.md b/docs/content/automation/rules_engine_2/converting_from_rules_engine.zh-hans.md new file mode 100644 index 0000000000..1bf859d475 --- /dev/null +++ b/docs/content/automation/rules_engine_2/converting_from_rules_engine.zh-hans.md @@ -0,0 +1,89 @@ +--- +title: 从 Rules Engine 转换 +description: 将现有的 Rules Engine 规则迁移为 Rules Engine 2.0 的图 +weight: 6 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/converting_from_rules_engine/ +--- + +注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。 + +两套引擎并行运行。启用 Rules Engine 2.0 不会改变您现有的 [Rules Engine](/automation/rules_engine/about/) 规则中的任何内容，也没有必须迁移它们的截止时间。 + +当您确实想要迁移时，有一个转换器可以使用。它会将一条 Rules Engine 规则（一个过滤器加一份有序的动作列表）转换为一张等价的 Rules Engine 2.0 图。 + +## 转换器的保证 + +**规则要么完整地转换成功，要么完全不转换。** 每一次转换都会报告两类结果： + +* **问题（Problems）**表示该规则未被写入。不会保存任何部分结果。 +* **警告（Warnings）**表示规则转换成功了，但其中有些内容发生了变化，值得您查看一下。 + +不会有任何内容被悄悄地近似处理。转换器的全部价值就在于：您可以信任一条转换后没有任何附带说明的规则，而对有说明的规则进行人工核查。 + +**转换后的规则始终以禁用状态创建。** 两套引擎都在运行，而两条规则对相同的发现项做相同的事情，正是转换器绝不能自行产生的结果。请对每一条转换后的规则进行审查，并有意识地去启用它。 + +**一条规则只会被转换一次。** 每条转换后的规则都会记住它来源于哪条规则，因此第二次运行转换器会跳过已经转换过的规则，而不会产生重复项。若要有意替换之前转换出的图，请使用覆盖（overwrite）选项。 + +## 运行转换器 + +### 通过 UI + +规则列表提供了一个转换操作，它会按规则报告哪些转换成功、哪些被跳过、哪些失败。 + +### 通过命令行 + +```bash +python manage.py convert_rules_to_v2 +``` + +| Option | Effect | +|--------|--------| +| `--dry-run` | 打印每条规则本会产生的图，不写入任何内容。 | +| `--rule-ids 1,2,3` | 仅转换这些规则。省略时会转换所有规则。 | +| `--overwrite` | 替换某条已转换规则的图并提升其版本号，而不是跳过它。 | +| `--activate-schedules` | 同时将每个计划复制到其转换后的规则上。默认关闭。 | +| `--drop-invalid-filters` | 丢弃过滤器集合已不再识别的作用范围过滤器并发出警告，而不是让该规则转换失败。 | +| `--json` | 以 JSON 而非文本形式打印报告。 | + +只有当某条规则转换失败时，该命令才会以非零状态退出。跳过会被报告，但不算失败。 + +先对全部规则用 `--dry-run` 了解一下情况，再进行真正的转换。 + +## 转换会产生什么 + +| Rules Engine concept | Becomes | +|----------------------|---------| +| 规则的过滤器 | 触发器节点上的 **Scope（作用范围）**。 | +| 带有计划的规则 | 一个 **On a Schedule** 触发器。 | +| 没有计划的规则 | 一个 **Manual Run** 触发器。 | +| 按顺序排列的每个动作 | 一个节点，按相同顺序串联。 | +| 由条件守护的动作 | 该节点前面的一个 **If / Filter** 节点。 | + +过滤器词汇表是两套引擎共用的，因此作用范围无需转译即可转换。这是有意为之的：这是同一套过滤器集合，只是有一套实现。 + +转换后的图会按照与手工构建的图相同的方式进行校验，包括每个节点的配置以及每个下拉菜单的允许取值。某条规则若持有一个产品后来已经弃用的严重程度或风险值，会在转换时就被发现，而不是等到运行时。 + +## 哪些内容不会被带过来 + +有四件事需要提前规划。转换器会在每次运行时以说明的形式报告这些内容。 + +* **运行历史留在原处。** 现有的运行历史及其受影响和被跳过的记录，仍保留在 Rules Engine 的 UI 中，不会被复制。 +* **计划默认不会被激活。** 一条以计划触发的规则可以转换，但除非您传入 `--activate-schedules`，否则其计划不会被复制。这样做是为了在两套引擎同时运行期间，让生效中的计划始终唯一归属于原有引擎，从而使转换后的规则不会在您不知情的情况下开始触发。当您确实复制某个计划时，副本会被赋予一个不同的名称，以免与原计划冲突。 +* **并发模型不同。** Rules Engine 只有一把实例级的运行锁。Rules Engine 2.0 则按规则各自串行化，因此不同的规则会并发运行。原本轮流执行的一组规则，现在会出现重叠。 +* **有一个动作没有对应项。** “将误报状态设为 false”这个动作无法用 Rules Engine 2.0 的节点表达，必须手动转换。 + +所有者未设置的规则也能转换，但会附带警告。请记住，没有所有者的规则看不到任何发现项，因此请在启用之前为其指定一个所有者。 + +## 建议的操作顺序 + +1. 启用 Rules Engine 2.0，并让您现有的规则继续运行。 +2. 用 `--dry-run` 运行转换器，并阅读报告。 +3. 执行转换。所有结果都会以禁用状态落地。 +4. 打开每一条转换后的规则，检查其图，并将模式保持为 **Simulate**。 +5. 启用转换后的规则，让它与原规则并行运行一段时间。Simulate 意味着它会更改发现项但不发送任何内容，因此可以将它的运行结果与原规则的结果进行比对。 +6. 在您确认满意后，禁用原规则，并将转换后的规则切换为 **Live**。 +7. 最后再复制计划，确保此时已经没有任何东西在运行旧规则。 + +第 5 步是尤其不该跳过的一步。两套引擎同时编辑相同的发现项，观察起来没有问题，但您希望是自己来决定发送何时开始。 diff --git a/docs/content/automation/rules_engine_2/deliveries.it.md b/docs/content/automation/rules_engine_2/deliveries.it.md new file mode 100644 index 0000000000..9104b44364 --- /dev/null +++ b/docs/content/automation/rules_engine_2/deliveries.it.md @@ -0,0 +1,120 @@ +--- +title: Consegne +description: Il registro di tutto ciò che le regole inviano verso l'esterno, e come + funzionano i nuovi tentativi e i reinvii +weight: 5 +audience: pro +aliases: +- /it/automation/rules_engine_v2/deliveries/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +Ogni effetto collaterale in uscita prodotto da una regola corrisponde a una riga nel registro delle consegne. **Rules Engine 2.0 > Consegne** le elenca. + +La riga viene scritta **prima** che avvenga qualsiasi chiamata di rete e contiene esattamente ciò che verrà, o è stato, inviato. Questo è ciò che rende l'uscita dei dati verificabile, invece di essere una riga di log che si spera qualcuno abbia conservato, ed è il motivo per cui **Simulazione** non è un percorso di codice separato: un invio simulato è la stessa riga con il passaggio di dispatch saltato. + +## Cosa registra una consegna + +| Campo | Significato | +|-------|---------| +| **Esecuzione** e **Nodo** | L'esecuzione e il nodo di uscita che l'hanno prodotta. | +| **Riscontro** | Il Riscontro a cui si riferisce, per un invio per singolo Riscontro. Gli invii in batch registrano invece il gruppo. | +| **Canale** | Il tipo di invio. | +| **Destinazione** | La destinazione risolta: una chiave di progetto JIRA, un canale, un URL, un indirizzo. | +| **Titolo** | Una descrizione dell'invio su una riga. | +| **Payload** | Esattamente ciò che verrà, o è stato, inviato. | +| **Modalità** | `simulate` o `live`. | +| **Stato** | A che punto è arrivata la consegna. | +| **Tentativi** | Quanti invii sono stati tentati, rispetto al massimo consentito. | +| **Ultimo errore** | Il motivo per cui l'ultimo tentativo non è riuscito, o per cui la consegna è stata saltata. | +| **Risposta** | Cosa ha risposto la destinazione. | +| **Riferimento esterno** e **URL** | La chiave del ticket, l'ID del messaggio o il percorso del file restituiti dalla destinazione, e un link ad esso quando disponibile. | + +## Canali + +| Canale | Prodotto da | +|---------|-------------| +| **JIRA** | Crea un problema JIRA | +| **Connettore downstream** | Crea un ticket downstream | +| **Slack** | Invia un messaggio Slack e annunci di report inviati a Slack | +| **Microsoft Teams** | Invia un messaggio Microsoft Teams | +| **Email** | Invia un'email e annunci di report inviati via email | +| **Webhook** | Chiama un webhook | +| **Report** | Genera un report | +| **Avviso in-app** | Genera un avviso in-app | + +## Stati + +| Stato | Significato | +|--------|---------| +| `simulated` | La regola era in modalità Simulazione. Non è stato inviato nulla, e nulla verrà mai inviato. | +| `skipped` | Qualcos'altro copriva già questo invio, oppure il gating lo ha rifiutato. Il motivo si trova nel campo dell'ultimo errore. | +| `pending` | Registrata in modalità Live, in attesa del task di consegna. | +| `dispatched` | Passata al servizio di integrazione, in attesa di conferma. | +| `sent` | Consegna confermata. | +| `failed` | Rifiutata in modo permanente, ad esempio un errore 4xx o un errore del vendor. Può essere reinviata. | +| `dead` | Tentativi esauriti, oppure non è mai arrivata alcuna conferma. Può essere reinviata. | + +Vale la pena soffermarsi su `skipped`. I salti vengono registrati invece di passare inosservati, perché "la regola non ha fatto nulla" e "la regola non ha fatto nulla perché questo Riscontro aveva già un ticket" sono risposte diverse, e solo una delle due è un problema. + +Ci sono tre motivi comuni per un salto, e il campo dell'ultimo errore indica sempre quale: + +* **Idempotenza.** Qualcos'altro copriva già questo invio. +* **Il canale è disattivato.** Una regola con un nodo Slack su un'istanza in cui Slack è disabilitato registra un salto che lo spiega, invece di fallire. Una regola salvata mentre un canale era attivo non dovrebbe iniziare a generare errori quando qualcuno lo disattiva. Vedere [disponibilità dei nodi](../node_reference/#when-a-channel-is-unavailable). +* **È stato raggiunto il limite di invio per singolo Riscontro.** Un nodo che invia un messaggio per ogni Riscontro si ferma per impostazione predefinita dopo 1.000 invii in una singola esecuzione, e registra per quanti Riscontri non ha inviato nulla. + +### Fedeltà del payload + +Il registro è trasparente su quanto il payload registrato sia vicino al corpo effettivamente trasmesso, perché questo varia in base al canale. + +| Fedeltà | Significato | +|----------|---------| +| `exact` | Byte-equivalente a ciò che è stato inviato. | +| `rendered` | Renderizzato dagli helper reali, ma il gating al momento dell'invio può comunque ridurlo. | +| `dojo request` | La richiesta esatta passata al servizio di integrazione. Il payload specifico del vendor viene composto a valle. | +| `summary` | Una descrizione dell'invio piuttosto che una sua riproduzione. Un report generato ne è l'esempio: il file viene costruito con dati live al momento dell'invio, quindi una copia salvata sarebbe errata non appena qualcosa cambiasse. | + +## La protezione contro i doppi invii + +Può esistere una sola consegna **attiva** per chiave di idempotenza, imposto a livello di database piuttosto che per convenzione. Attiva significa `pending`, `dispatched` o `sent`. + +Un secondo invio che entrerebbe in collisione con uno attivo diventa una riga `skipped` con il motivo registrato. Non è mai un'operazione nulla silenziosa, e non è mai un ticket duplicato. + +Poiché le righe `simulated`, `skipped`, `failed` e `dead` non mantengono una prenotazione, una consegna non riuscita può essere reinviata al suo posto senza che una seconda riga la contenda per la stessa chiave. + +## Nuovi tentativi + +Una consegna live viene ritentata automaticamente. Ogni riga porta con sé il proprio conteggio dei tentativi e il proprio limite massimo, sei tentativi per impostazione predefinita, in modo che una destinazione che fallisce non possa trascinare con sé le altre. I nuovi tentativi vengono distanziati progressivamente tra un tentativo e l'altro. + +Quando l'ultimo tentativo è stato consumato, la riga viene contrassegnata come `dead` invece di rimanere ferma su `pending`. L'esaurimento dei tentativi è visibile, non silenzioso. + +Se un worker viene interrotto a metà dell'invio, il messaggio viene riconsegnato. La riga viene bloccata e il suo stato viene ricontrollato prima che venga inviato nuovamente qualcosa, in modo che una riconsegna non possa trasformarsi in un doppio invio. + +Le consegne passate al servizio di integrazione passano a `dispatched` e attendono un callback di conferma. Se non arriva alcun callback entro sei ore, la riga viene contrassegnata come `dead` in modo che possa essere reinviata. Questa finestra temporale è deliberatamente ampia: un accumulo nella coda a valle per un'ora è normale, e archiviare una riga con troppa fretta trasformerebbe un reinvio in un ticket duplicato. + +## Reinviare una consegna + +Una consegna `failed` o `dead` può essere reinviata dalla pagina Consegne. Il registro riporta quando è stata reinviata e da chi. + +Il reinvio richiede il permesso **Modifica regola**. + +Il reinvio invia nuovamente il payload registrato. Per un report, questo rigenera il report a partire dai dati correnti, perché il payload è una descrizione di cosa generare piuttosto che il file stesso. + +## Simulazione + +In modalità Simulazione, ogni nodo di uscita scrive la propria riga di consegna con stato `simulated`, payload completo e destinazione risolta, quindi si ferma. Non viene registrato alcun dispatch, quindi nulla può essere inviato in seguito, indipendentemente da come si conclude l'esecuzione. L'anteprima si comporta allo stesso modo, e non inserisce nemmeno le righe. + +Questo è il modo previsto per rivedere una regola prima di renderla operativa: abilitarla in modalità Simulazione, lasciarla eseguire su Riscontri reali, quindi leggere i payload che ha registrato. + +Da tenere presente che la Simulazione blocca **solo** gli invii in uscita. I nodi sui Riscontri continuano comunque a modificare i Riscontri. + +## Conservazione + +Le consegne vengono conservate per **180 giorni** per impostazione predefinita, dopodiché un job di conservazione le elimina. + +Questa è la tabella che cresce più velocemente in questa funzionalità, perché un nodo che invia un messaggio per ogni Riscontro scrive una riga per ogni Riscontro, sia in modalità Simulazione sia in Live. Il valore predefinito è una finestra reale anziché "conserva tutto", in modo che la crescita non diventi silenziosamente un problema per l'utente. + +L'utente ne viene informato invece di doverlo scoprire da solo. Il dettaglio di una consegna mostra la finestra di conservazione e la data in cui quella riga verrà eliminata, e la data viene ricalcolata a ogni lettura, quindi modificare la finestra ha effetto immediatamente. + +Impostare una finestra più lunga se è necessaria una traccia di controllo delle uscite più estesa, oppure `0` per conservare tutto. Vedere [Configurazione](../configuration/#retention). diff --git a/docs/content/automation/rules_engine_2/deliveries.pt-br.md b/docs/content/automation/rules_engine_2/deliveries.pt-br.md new file mode 100644 index 0000000000..11f004f1b6 --- /dev/null +++ b/docs/content/automation/rules_engine_2/deliveries.pt-br.md @@ -0,0 +1,120 @@ +--- +title: Entregas +description: O registro de tudo que as regras enviam para fora, e como funcionam as + tentativas e a reprodução +weight: 5 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/deliveries/ +--- + +Nota: o Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +Cada efeito colateral de saída produzido por uma regra é uma linha no registro de entregas. **Rules Engine 2.0 > Entregas** as lista. + +A linha é gravada **antes** de qualquer chamada de rede acontecer, e contém exatamente o que seria, ou foi, enviado. É isso que torna a saída auditável, em vez de uma linha de log que você espera que alguém tenha guardado, e é por isso que **Simulate** não é um caminho de código separado: um envio simulado é a mesma linha com a etapa de despacho pulada. + +## O que uma entrega registra + +| Field | Meaning | +|-------|---------| +| **Run** e **Node** | Qual execução e qual nó de saída a produziu. | +| **Finding** | O Achado a que ela se refere, em um envio por Achado. Envios em lote registram o grupo em vez disso. | +| **Channel** | Que tipo de envio é. | +| **Target** | O destino resolvido: uma chave de projeto do JIRA, um canal, uma URL, um endereço. | +| **Title** | Uma descrição de uma linha do envio. | +| **Payload** | Exatamente o que seria, ou foi, enviado. | +| **Mode** | `simulate` ou `live`. | +| **Status** | Até onde a entrega chegou. | +| **Attempts** | Quantos envios já foram tentados, em relação ao máximo permitido. | +| **Last error** | Por que a última tentativa falhou, ou por que a entrega foi ignorada. | +| **Response** | O que o destino respondeu. | +| **External reference** e **URL** | A chave do chamado, o id da mensagem ou o caminho do arquivo que o destino retornou, e um link para ele quando existir. | + +## Canais + +| Canal | Produzido por | +|---------|-------------| +| **JIRA** | Criar uma Issue do JIRA | +| **Downstream connector** | Criar um Ticket Downstream | +| **Slack** | Enviar uma Mensagem no Slack, e anúncios de relatórios enviados ao Slack | +| **Microsoft Teams** | Enviar uma Mensagem no Microsoft Teams | +| **Email** | Enviar um E-mail, e anúncios de relatórios enviados por e-mail | +| **Webhook** | Chamar um Webhook | +| **Report** | Gerar um Relatório | +| **In-app alert** | Emitir um Alerta no Aplicativo | + +## Status + +| Status | Significado | +|--------|---------| +| `simulated` | A regra estava no modo Simulate. Nada foi enviado, e nada nunca será. | +| `skipped` | Algo já cobriu esse envio, ou o controle o recusou. O motivo está no campo de último erro. | +| `pending` | Registrada no modo Live, aguardando sua tarefa de entrega. | +| `dispatched` | Repassada ao serviço de integração, aguardando confirmação. | +| `sent` | Entrega confirmada. | +| `failed` | Rejeitada permanentemente, por exemplo um 4xx ou um erro do fornecedor. Pode ser reproduzida. | +| `dead` | Tentativas esgotadas, ou nenhuma confirmação jamais chegou. Pode ser reproduzida. | + +Vale a pena examinar melhor o `skipped`. Entradas ignoradas são registradas em vez de silenciosas, porque "a regra não fez nada" e "a regra não fez nada porque este Achado já tinha um chamado" são respostas diferentes, e apenas uma delas é um problema. + +Há três motivos comuns para uma entrada ser ignorada, e o campo de último erro sempre diz qual: + +* **Idempotência.** Algo já cobriu esse envio. +* **O canal está desligado.** Uma regra com um nó do Slack em uma instância onde o Slack está desabilitado registra uma entrada ignorada explicando isso, em vez de falhar. Uma regra salva enquanto um canal estava ativo não deveria passar a apresentar erros quando alguém o desativa. Veja [disponibilidade do nó](../node_reference/#when-a-channel-is-unavailable). +* **O limite de envio por Achado foi atingido.** Um nó que envia uma mensagem por Achado para por padrão após 1.000 em uma única execução, e registra quantos Achados ficaram de fora do envio. + +### Fidelidade do payload + +O registro é honesto sobre o quão próximo o payload registrado está do corpo real transmitido, porque isso varia conforme o canal. + +| Fidelity | Significado | +|----------|---------| +| `exact` | Equivalente byte a byte ao que foi enviado. | +| `rendered` | Renderizado pelos helpers reais, mas o controle no momento do envio ainda pode reduzi-lo. | +| `dojo request` | A requisição exata entregue ao serviço de integração. O payload específico do fornecedor é composto downstream. | +| `summary` | Uma descrição do envio em vez de uma reprodução dele. Um relatório gerado é o exemplo: o arquivo é construído a partir de dados ao vivo no momento do envio, então uma cópia armazenada dele estaria errada no instante em que qualquer coisa mudasse. | + +## A proteção contra envio duplicado + +Apenas uma entrega **ativa** pode existir por chave de idempotência, imposto no banco de dados em vez de por convenção. Ativa significa `pending`, `dispatched` ou `sent`. + +Um segundo envio que colidiria com um ativo se torna uma linha `skipped` com seu motivo registrado. Nunca é um no-op silencioso, e nunca é um chamado duplicado. + +Como as linhas `simulated`, `skipped`, `failed` e `dead` não mantêm nenhuma reserva, uma entrega com falha pode ser reproduzida no lugar sem que uma segunda linha dispute a mesma chave. + +## Tentativas + +Uma entrega ao vivo é repetida automaticamente. Cada linha carrega sua própria contagem de tentativas e seu próprio limite, seis tentativas por padrão, de modo que um destino com falha não consegue arrastar seus vizinhos junto. As repetições aguardam um intervalo crescente entre as tentativas. + +Quando a última tentativa é consumida, a linha é marcada como `dead` em vez de ficar parada em `pending`. O esgotamento é visível, não silencioso. + +Se um worker for encerrado no meio de um envio, a mensagem é reentregue. A linha é bloqueada e seu status é reverificado antes que qualquer coisa seja enviada novamente, de modo que uma reentrega não pode se tornar um envio duplicado. + +Entregas repassadas ao serviço de integração passam para `dispatched` e aguardam um callback de confirmação. Se nenhum callback chegar em até seis horas, a linha é marcada como `dead` para que possa ser reproduzida. Essa janela é deliberadamente generosa: uma fila downstream congestionada por uma hora é normal, e marcar uma linha como morta cedo demais transformaria uma reprodução em um chamado duplicado. + +## Reproduzindo uma entrega + +Uma entrega `failed` ou `dead` pode ser reenviada a partir da página Entregas. O registro anota quando ela foi reproduzida e por quem. + +Reproduzir exige **Rule Edit**. + +Reproduzir reenvia o payload registrado. Para um relatório, isso regenera o relatório a partir dos dados atuais, porque o payload é uma descrição do que gerar, e não o arquivo em si. + +## Simulate + +No modo Simulate, cada nó de saída grava sua linha de entrega com status `simulated`, payload completo e destino resolvido, e então para. Nenhum despacho é registrado, então nada pode ser enviado depois, não importa como a execução termine. O Preview se comporta da mesma forma, e nem sequer insere as linhas. + +Essa é a forma indicada de revisar uma regra antes de colocá-la em produção: ative-a em Simulate, deixe-a rodar contra Achados reais, e depois leia os payloads que ela registrou. + +Lembre-se de que o Simulate contém **apenas** os envios de saída. Nós de Achados continuam alterando Achados. + +## Retenção + +As entregas são mantidas por **180 dias** por padrão, após os quais um job de retenção as remove. + +Esta é a tabela que mais cresce no recurso, porque um nó que envia uma mensagem por Achado grava uma linha por Achado, tanto no modo Simulate quanto no Live. O padrão é uma janela real em vez de "guardar tudo", então o crescimento não vira seu problema silenciosamente. + +Você é avisado sobre isso em vez de ser deixado para descobrir sozinho. O detalhe de uma entrega mostra a janela de retenção e a data em que aquela linha será excluída, e a data é recalculada a cada leitura, de modo que alterar a janela tem efeito imediato. + +Defina a janela mais longa se precisar de uma trilha de auditoria de saída mais longa, ou `0` para manter tudo. Veja [Configuração](../configuration/#retention). diff --git a/docs/content/automation/rules_engine_2/deliveries.zh-hans.md b/docs/content/automation/rules_engine_2/deliveries.zh-hans.md new file mode 100644 index 0000000000..b03b85af0f --- /dev/null +++ b/docs/content/automation/rules_engine_2/deliveries.zh-hans.md @@ -0,0 +1,119 @@ +--- +title: 投递记录 +description: 记录规则所有对外发送内容的台账，以及重试和重放机制的工作原理 +weight: 5 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/deliveries/ +--- + +注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。 + +规则产生的每一个对外副作用，都会在投递台账中生成一行记录。**Rules Engine 2.0 > Deliveries** 页面会列出这些记录。 + +该记录会在发生任何网络调用之**前**写入，其中保存的正是即将发送或已经发送的确切内容。正因如此，出站发送才是可审计的，而不是一条只能寄希望于有人保留下来的日志；这也是**模拟**并非另一条独立代码路径的原因：模拟发送使用的是同一条记录，只是跳过了实际派发步骤。 + +## 一条投递记录包含哪些内容 + +| 字段 | 含义 | +|------|------| +| **运行** 和 **节点** | 产生该记录的运行以及出站节点。 | +| **发现项** | 对于按发现项逐条发送的记录，指其对应的发现项；批量发送记录的则是该批次分组。 | +| **渠道** | 该发送的类型。 | +| **目标** | 解析后的目的地：JIRA 项目键、频道、URL 或地址。 | +| **标题** | 对该次发送的一行简要描述。 | +| **负载** | 即将发送或已发送的确切内容。 | +| **模式** | `simulate` 或 `live`。 | +| **状态** | 该投递记录当前所处的阶段。 | +| **尝试次数** | 已尝试发送的次数，以及允许的最大次数。 | +| **最后错误** | 上一次尝试失败的原因，或该记录被跳过的原因。 | +| **响应** | 目标返回的内容。 | +| **外部引用** 和 **URL** | 目标返回的工单编号、消息 ID 或文件路径，以及指向它的链接（如果有）。 | + +## 渠道 + +| 渠道 | 产生方式 | +|------|--------| +| **JIRA** | 创建 JIRA 问题 | +| **下游连接器** | 创建下游工单 | +| **Slack** | 发送 Slack 消息，以及发送到 Slack 的报告通知 | +| **Microsoft Teams** | 发送 Microsoft Teams 消息 | +| **Email** | 发送电子邮件，以及通过电子邮件发送的报告通知 | +| **Webhook** | 调用 Webhook | +| **报告** | 生成报告 | +| **应用内提醒** | 触发应用内提醒 | + +## 状态 + +| 状态 | 含义 | +|-----|-----| +| `simulated` | 该规则处于模拟模式。没有发送任何内容，以后也不会发送。 | +| `skipped` | 已有其他记录覆盖了此次发送，或该发送被门控逻辑拒绝。原因记录在“最后错误”字段中。 | +| `pending` | 已在正式模式下记录，正在等待其投递任务执行。 | +| `dispatched` | 已交给集成服务，正在等待确认。 | +| `sent` | 已确认送达。 | +| `failed` | 被永久性拒绝，例如收到 4xx 或供应商返回的错误。可以重放。 | +| `dead` | 重试次数已耗尽，或始终未收到确认。可以重放。 | + +`skipped` 值得多说一句。跳过操作会被记录下来，而不是悄无声息地发生，因为“规则什么都没做”和“规则什么都没做，是因为该发现项已经有工单了”是两种不同的情况，其中只有一种才是问题。 + +造成跳过的常见原因有三种，“最后错误”字段总会说明具体是哪一种： + +* **幂等性。** 已有其他记录覆盖了此次发送。 +* **渠道已关闭。** 如果某个实例上的 Slack 已被禁用，其中包含 Slack 节点的规则会记录一条说明该情况的跳过记录，而不是报错失败。在渠道开启时保存的规则，不应该在有人关闭该渠道后就开始出错。参见[节点可用性](../node_reference/#when-a-channel-is-unavailable)。 +* **达到了按发现项发送的上限。** 按发现项逐条发送消息的节点，默认在单次运行中发送满 1,000 条后就会停止，并记录还有多少条未发送。 + +### 负载保真度 + +台账会如实反映所记录的负载与实际线上发送内容之间的接近程度，因为这一点会因渠道而异。 + +| 保真度 | 含义 | +|-------|-----| +| `exact` | 与实际发送内容逐字节一致。 | +| `rendered` | 由实际使用的渲染逻辑生成，但发送时的门控逻辑仍可能对其进行裁剪。 | +| `dojo request` | 交给集成服务的确切请求内容。特定于供应商的负载内容是在下游组装的。 | +| `summary` | 对该次发送的描述，而非其原样重现。生成的报告就是一个例子：该文件是在发送时根据实时数据生成的，因此一旦有任何变化，存储下来的副本就会失真。 | + +## 防止重复发送的保护机制 + +每个幂等键最多只能存在一条**活动中**的投递记录，这一点由数据库强制保证，而不仅仅是约定。“活动中”指的是 `pending`、`dispatched` 或 `sent`。 + +如果第二次发送会与一条活动中的记录冲突，它就会变成一条 `skipped` 记录，并记录下具体原因。它绝不会是一次悄无声息的空操作，也绝不会产生重复的工单。 + +由于 `simulated`、`skipped`、`failed` 和 `dead` 状态的记录不会占用该幂等键，失败的投递记录可以原地重放，不会有第二条记录为同一个键相互冲突。 + +## 重试 + +正式模式下的投递记录会自动重试。每条记录都有各自独立的尝试次数和上限（默认六次），因此某个目的地的发送失败不会拖累其他记录。多次重试之间会有退避等待。 + +当最后一次重试用完后，该记录会被标记为 `dead`，而不是一直停留在 `pending` 状态。重试耗尽的情况是可见的，不会被悄悄隐藏。 + +如果某个工作进程在发送过程中被终止，消息会被重新投递。在再次发送之前，该记录会被锁定并重新检查其状态，因此重新投递不会变成重复发送。 + +交给集成服务的投递记录会进入 `dispatched` 状态，等待确认回调。如果六小时内没有收到回调，该记录会被标记为 `dead`，以便重放。这个等待窗口特意设置得比较宽松：下游队列积压一个小时是很正常的情况，如果过早地判定记录失败，重放就可能变成重复的工单。 + +## 重放投递记录 + +状态为 `failed` 或 `dead` 的投递记录，可以在“投递记录”页面重新发送。台账会记录该记录是何时、由谁重放的。 + +重放需要具备**规则编辑**权限。 + +重放会重新发送已记录的负载内容。对于报告而言，这意味着会根据当前数据重新生成报告，因为负载内容描述的是应生成什么，而不是文件本身。 + +## 模拟 + +在模拟模式下，每个出站节点都会写入一条状态为 `simulated`、包含完整负载内容和解析后目标的投递记录，然后停止执行。系统不会登记任何派发操作，因此无论该次运行后续如何展开，都不会有内容被发送出去。预览的行为与此相同，甚至连记录都不会插入。 + +这正是在正式启用一条规则之前对其进行审查的推荐方式：先以模拟模式启用它，让它针对真实的发现项运行，然后查看它所记录下的负载内容。 + +请注意，模拟模式**只会**拦截对外发送的动作。发现项节点仍然会照常修改发现项。 + +## 数据保留 + +投递记录默认保留 **180 天**，超过之后会由保留期清理任务将其清除。 + +这是该功能中增长最快的数据表，因为按发现项逐条发送消息的节点，无论在模拟模式还是正式模式下，都会为每个发现项写入一行记录。默认设置是一个真实存在的保留窗口，而不是“全部保留”，因此数据增长不会在不知不觉中变成你的负担。 + +系统会主动告知你这一点，而不是让你自己去发现。每条投递记录的详情中都会显示保留窗口以及该记录将被删除的日期，且该日期在每次读取时都会重新计算，因此更改保留窗口会立即生效。 + +如果你需要更长的对外发送审计追溯期，可以将该窗口设置得更长，或设为 `0` 以保留全部记录。参见[配置](../configuration/#retention)。 diff --git a/docs/content/automation/rules_engine_2/node_reference.it.md b/docs/content/automation/rules_engine_2/node_reference.it.md new file mode 100644 index 0000000000..8052328ab0 --- /dev/null +++ b/docs/content/automation/rules_engine_2/node_reference.it.md @@ -0,0 +1,347 @@ +--- +title: Riferimento dei nodi +description: Tutti i nodi inclusi in Rules Engine 2.0, e cosa fa ciascuno +weight: 3 +audience: pro +aliases: +- /it/automation/rules_engine_v2/node_reference/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +Rules Engine 2.0 include 25 nodi suddivisi in quattro categorie. Questa pagina li documenta tutti. + +Salvo diversa indicazione, un nodo accetta un input, produce un output chiamato `out` e passa a quell'output ogni elemento ricevuto. Questo è rilevante quando si concatenano i nodi: un nodo sui Riscontri modifica il Riscontro e poi passa l'elemento avanti, quindi più nodi in sequenza vengono applicati tutti. + +## Trigger + +Ogni grafo ha esattamente un trigger, e solo un trigger può avviare un'esecuzione. Tutti e tre producono elementi Riscontro e tutti e tre accettano un **Ambito** che restringe quali Riscontri producono. Vedere [Creazione delle regole](../building_rules/) per il funzionamento dell'ambito. + +### Al verificarsi di un evento sul Riscontro + +`trigger.finding` + +Viene eseguito quando i Riscontri vengono creati, aggiornati, chiusi o riaperti. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Evento** | `created` | Quale modifica al Riscontro attiva questa regola: `created`, `updated`, `closed`, `reopened`, oppure `any` per tutte e quattro. | +| **Ambito** | vuoto | Quali Riscontri considera questa regola. Vuoto significa ogni Riscontro visibile al proprietario della regola. | + +I Riscontri indicati dall'evento vengono confrontati con l'ambito prima di entrare nel grafo, quindi l'evento decide *quando* e l'ambito decide *quali*. + +### Su pianificazione + +`trigger.schedule` + +Scansiona tutti i Riscontri nell'ambito secondo una pianificazione. La pianificazione viene configurata sulla regola ed è limitata a intervalli di un quarto d'ora. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Ambito** | vuoto | Quali Riscontri considera questa regola. | + +### Esecuzione manuale + +`trigger.manual` + +Scansiona tutti i Riscontri nell'ambito quando si preme **Esegui** sulla regola. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Ambito** | vuoto | Quali Riscontri considera questa regola. | + +## Logica + +### Se / Filtro + +`filter.if` + +Instrada ogni elemento lungo il ramo **true** o **false**, in base a delle condizioni. È l'unico nodo con due output, ed è il modo in cui un grafo si dirama. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Condizioni** | vuoto | Ogni riga è un percorso, un operatore e un valore. Vedere [Condizioni](../building_rules/#conditions). | +| **Corrispondenza** | `all` | Se tutte le condizioni devono essere vere (`all`), oppure solo una di esse (`any`). | + +Un elenco di condizioni vuoto fa passare tutto lungo il ramo true. Entrambi i rami sono opzionali: lasciare il ramo false non collegato scarta semplicemente gli elementi che non hanno soddisfatto la condizione. + +### Limite + +`flow.limit` + +Fa passare i primi N elementi e scarta il resto. Utile come valvola di sicurezza durante il test di una regola, e per limitare quanti ticket o messaggi può produrre una singola esecuzione. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Mantieni i primi** | `100` | Quanti elementi far passare. | + +### Deduplica all'interno dell'esecuzione + +`flow.dedupe_batch` + +Mantiene il primo elemento per ogni chiave e scarta quelli successivi con la stessa chiave. Limitato all'esecuzione corrente, quindi deduplica all'interno di una singola esecuzione e non tra esecuzioni diverse. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Percorso chiave** | `finding.hash_code` | Il percorso dell'elemento il cui valore identifica un duplicato. | + +Un uso comune è `finding.component_name`, per notificare una volta per ogni componente interessato invece che una volta per Riscontro. + +## Riscontri + +Questi nodi modificano i Riscontri. Ogni modifica viene attribuita alla regola, all'esecuzione e al nodo che l'ha effettuata, e compare nella cronologia di provenienza del Riscontro. + +### Imposta gravità + +`finding.set_severity` + +Imposta la gravità e ricalcola di conseguenza la data SLA e la priorità. + +| Impostazione | Opzioni | +|---------|---------| +| **Gravità** | `Critical`, `High`, `Medium`, `Low`, `Info` | + +### Imposta un campo + +`finding.set_field` + +Imposta, aggiunge in coda, oppure antepone il testo a un campo testuale. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Campo** | nessuno | Uno tra `component_name`, `component_version`, `cvssv3`, `cwe`, `description`, `file_path`, `impact`, `mitigation`, `service`, `title`. | +| **Modalità** | `set` | `set`, `append` o `prepend`. Un vettore CVSSv3 può essere solo sostituito. | +| **Valore** | nessuno | Il testo da scrivere. Supporta segnaposto in stile `{{finding.title}}`. | + +### Imposta stato + +`finding.set_status` + +Sposta il Riscontro in uno stato. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Stato** | nessuno | `active`, `inactive`, `verified`, `unverified`, `false_positive`, `mitigated`, `reopen`. | +| **Nota** | vuoto | Una nota facoltativa registrata insieme alla modifica dello stato. | + +### Aggiungi tag + +`finding.add_tags` + +Aggiunge tag al Riscontro. I tag esistenti vengono mantenuti. + +| Impostazione | Note | +|---------|-------| +| **Tag** | Separati da virgola. Supporta segnaposto in stile `{{product.name}}`, per taggare con dati provenienti dal Riscontro. | + +### Aggiungi una nota + +`finding.add_note` + +Aggiunge una nota al Riscontro. + +| Impostazione | Note | +|---------|-------| +| **Nota** | Il testo della nota. Supporta i segnaposto. | + +### Imposta proprietari + +`finding.set_owners` + +Rende un gruppo responsabile del Riscontro. + +| Impostazione | Note | +|---------|-------| +| **Gruppo** | Il gruppo proprietario di questi Riscontri. | + +### Imposta revisori + +`finding.set_reviewers` + +Sottopone il Riscontro alla revisione degli utenti selezionati. + +| Impostazione | Note | +|---------|-------| +| **Revisori** | Uno o più utenti che devono revisionare questi Riscontri. | + +### Accetta rischio + +`finding.risk_accept` + +Applica l'accettazione semplice del rischio al Riscontro, oppure lo aggiunge a un record di accettazione del rischio. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Come** | `simple` | `simple` imposta l'accettazione semplice del rischio sul Riscontro. `acceptance` lo aggiunge a un record di accettazione del rischio. | +| **Accettato** | attivo | Visibile per `simple`. Disattivare per annullare l'accettazione del rischio. | +| **Accettazione del rischio** | nessuno | Visibile per `acceptance`. A quale accettazione del rischio aggiungere questi Riscontri. | + +### Imposta policy di mitigazione + +`finding.set_mitigation_policy` + +Imposta la policy di mitigazione in base alla quale il Riscontro viene risolto. + +| Impostazione | Note | +|---------|-------| +| **Policy di mitigazione** | La policy da applicare. | + +### Cambia priorità + +`finding.set_priority` + +Imposta la priorità, oppure la modifica aritmeticamente. Questo sovrascrive la priorità calcolata. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Operazione** | `set` | `set`, `add`, `subtract`, `multiply`, `divide`. | +| **Valore** | nessuno | La priorità da impostare, oppure la quantità di cui modificarla. | + +### Imposta rischio + +`finding.set_risk` + +Imposta il rischio, sovrascrivendo quello calcolato. + +| Impostazione | Opzioni | +|---------|---------| +| **Rischio** | `Low`, `Medium`, `Needs Action`, `Urgent` | + +## Uscita + +I nodi di uscita sono i nodi che escono da DefectDojo. Ognuno di essi registra una [Consegna](../deliveries/) prima che venga inviato qualsiasi cosa, ed ognuno rispetta la modalità **Simulazione** o **Live** della regola. + +Diversi di essi offrono la stessa opzione **Un messaggio per Riscontro**. Se disattivata, il nodo invia un unico messaggio che descrive l'intero batch, con una ripartizione per gravità e un elenco limitato di Riscontri. Se attivata, invia un messaggio per ogni Riscontro. + +Un nodo che invia un messaggio per ogni Riscontro si ferma per impostazione predefinita dopo 1.000 invii in una singola esecuzione, e registra un salto visibile che indica per quanti Riscontri non ha inviato nulla. Vedere [Configurazione](../configuration/#per-finding-send-ceiling). + +### Quando un canale non è disponibile + +Un nodo di uscita dipende da qualcosa esterno alla regola: un token Slack, un webhook Microsoft Teams, una configurazione JIRA, un connettore con licenza. Quando questo manca o è disattivato, il nodo non può funzionare, e Rules Engine 2.0 lo segnala in tre momenti diversi invece di fallire silenziosamente: + +* **Nella tavolozza**, un nodo non disponibile viene contrassegnato come tale, con il motivo, prima che venga trascinato sul canvas. +* **Al salvataggio**, un grafo che contiene un nodo non disponibile viene rifiutato. È il momento in cui qualcuno è presente per sceglierne uno diverso. +* **In fase di esecuzione**, la consegna viene **saltata** con il motivo allegato, non fallita. Una regola salvata mentre Slack era attivo non dovrebbe iniziare a generare errori il giorno in cui qualcuno disattiva Slack. Il resoconto corretto è una consegna saltata che indica che Slack è disattivato. + +### Crea un problema JIRA + +`ticket.jira` + +Crea o aggiorna il problema JIRA per il Riscontro. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Salta i Riscontri che hanno già un problema** | attivo | Lascia invariati i Riscontri che hanno già un problema JIRA. | +| **Aggiorna un problema esistente** | disattivo | Visibile quando l'opzione precedente è disattivata. Invia i Riscontri che hanno già un problema, in modo da aggiornare JIRA. | + +Il riepilogo, la descrizione e la priorità provengono dalla configurazione JIRA del prodotto, non da questo nodo. Un ticket creato da una regola è quindi identico a uno creato tramite l'invio di tutti i problemi. + +### Crea un ticket downstream + +`ticket.downstream` + +Crea o aggiorna un ticket tramite un [connettore downstream](/connectors/downstream/about/). + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Issue tracker** | `auto` | `auto` utilizza gli issue tracker assegnati all'Engagement o al Prodotto. `mapping` punta a una mappatura specifica. | +| **Mappatura issue tracker** | nessuno | Visibile per `mapping`. A quale mappatura inviare. | +| **Operazione** | `create` | `create` un ticket, oppure `update` quello esistente. Un `update` senza un ticket esistente lo crea. | +| **Salta i Riscontri che hanno già un ticket** | attivo | Lascia invariati i Riscontri che hanno già un ticket nella mappatura di destinazione. | + +La regola sostituisce le impostazioni di invio automatico dell'assegnazione: i filtri per gravità e solo-attivi non vengono applicati una seconda volta qui. Un Riscontro il cui ticket esiste già viene saltato, indipendentemente da come quel ticket sia stato creato. + +### Invia un messaggio Slack + +`notify.slack` + +Pubblica su un canale Slack tramite un connettore di messaggistica. La connessione contiene il token del bot; le impostazioni Slack a livello di istanza in **Impostazioni di sistema** non vengono utilizzate e non fungono da fallback. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Connessione** | nessuno | Un [connettore di messaggistica](/issue_tracking/pro_integration/messaging_connectors/) di questo tipo. Obbligatorio. | +| **Destinazione** | vuoto | Visibile una volta scelta una connessione. I campi dipendono dal vendor della connessione. | +| **Un messaggio per Riscontro** | disattivo | Se disattivata, invia un unico messaggio relativo al batch. | +| **Messaggio** | `{{finding.severity}}: {{finding.title}} ({{product.name}})` | Renderizzato per ogni Riscontro. | +| **Riscontri elencati nel digest** | `10` | Visibile per i messaggi in batch. Quanti Riscontri elenca il messaggio prima di indicare quanti altri ce ne sono. | + +### Invia un messaggio Microsoft Teams + +`notify.msteams` + +Pubblica una scheda tramite un connettore di messaggistica. La connessione contiene l'URL del flusso di lavoro Power Automate; il webhook Teams a livello di istanza in **Impostazioni di sistema** non viene utilizzato e non funge da fallback. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Connessione** | nessuno | Un [connettore di messaggistica](/issue_tracking/pro_integration/messaging_connectors/) di questo tipo. Obbligatorio. | +| **Destinazione** | vuoto | Visibile una volta scelta una connessione. I campi dipendono dal vendor della connessione. | +| **Un messaggio per Riscontro** | disattivo | Se disattivata, invia un'unica scheda relativa al batch. | +| **Messaggio** | `{{finding.severity}}: {{finding.title}} ({{product.name}})` | Renderizzato per ogni Riscontro. | +| **Riscontri elencati nel digest** | `10` | Visibile per i messaggi in batch. | + +### Invia un'email + +`notify.email` + +Invia un'email a un elenco fisso di indirizzi tramite un connettore di messaggistica. I destinatari corrispondono alla destinazione della connessione. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Connessione** | nessuno | Un [connettore di messaggistica](/issue_tracking/pro_integration/messaging_connectors/) di questo tipo. Obbligatorio. | +| **Destinazione** | vuoto | Visibile una volta scelta una connessione. I campi dipendono dal vendor della connessione. | + +| **Oggetto** | `[DefectDojo] {{ctx.count}} finding(s) from rule {{ctx.rule_name}}` | Renderizzato una volta per messaggio. | +| **Corpo** | un corpo HTML contenente `{{ctx.findings_html}}` | HTML. `{{ctx.findings_html}}` visualizza l'elenco dei Riscontri. | +| **Un messaggio per Riscontro** | disattivo | Se disattivata, invia un'unica email relativa al batch. | +| **Riscontri elencati nel corpo** | `25` | Quanti Riscontri elenca `{{ctx.findings_html}}` prima di indicare quanti altri ce ne sono. | + +### Chiama un webhook + +`notify.webhook` + +Invia una richiesta POST JSON a un endpoint webhook. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Endpoint webhook** | nessuno | Un [webhook di notifica](/automation/api/notification_webhooks/) configurato. La sua intestazione personalizzata viene inviata con la richiesta. | +| **URL** | vuoto | Visibile quando non è selezionato alcun endpoint. Dove inviare la richiesta POST. | +| | | È obbligatorio uno dei due precedenti. | +| **Segreto di firma** | vuoto | Firma il corpo come `X-DefectDojo-Signature: sha256=HMAC`. | +| **Un messaggio per Riscontro** | disattivo | Se disattivata, pubblica l'intero batch in un'unica richiesta. | + +Due cose da sapere. Un segreto di firma digitato qui viene memorizzato con la regola, quindi per qualsiasi dato sensibile è preferibile utilizzare un endpoint configurato con la propria intestazione. Inoltre, un webhook chiamato da una regola non modifica mai lo stato di salute di quell'endpoint, quindi una regola non può disabilitare i webhook di notifica fallendo. + +Gli URL in testo libero vengono convalidati al salvataggio. Vedere [Configurazione](../configuration/#outbound-destination-validation) per sapere cosa viene rifiutato e come consentire indirizzi privati. + +### Genera un avviso in-app + +`notify.alert` + +Crea un avviso in-app relativo al batch. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Titolo** | `Rules Engine 2.0: {{ctx.rule_name}}` | Renderizzato una volta per l'intero batch. | +| **Descrizione** | `{{ctx.count}} finding(s) matched the rule {{ctx.rule_name}}.` | Renderizzato una volta per l'intero batch. | +| **Destinatari** | vuoto | Nomi utente separati da virgola. Se vuoto, avvisa gli amministratori. | + +I destinatari mantengono comunque il controllo su questo tramite la propria impostazione di notifica **Corrispondenza Rules Engine**, quindi un avviso non può aggirare le preferenze di notifica di un utente. + +### Genera un report + +`report.generate` + +Genera un report da un modello, limitato ai Riscontri che hanno raggiunto questo nodo, e può annunciare il link di download. + +| Impostazione | Predefinito | Note | +|---------|---------|-------| +| **Modello di report** | nessuno | Da quale modello generare. Obbligatorio. | +| **Formato** | `pdf` | `pdf` o `html`. | +| **Riscontri inclusi** | `batch_findings` | `batch_findings` limita il report ai Riscontri che hanno raggiunto questo nodo. `template_default` consente al modello di usare i propri filtri. | +| **Annuncia tramite** | nessuno | Un [connettore di messaggistica](/issue_tracking/pro_integration/messaging_connectors/) su cui pubblicare il link di download una volta generato il report. Lasciare vuoto per non annunciare. | +| **Annuncia a** | vuoto | Visibile una volta scelta una connessione. Dove invia quella connessione: un ID canale Slack, indirizzi email, e così via. | +| **Annuncio** | `Report ready: {{ctx.report_url}}` | Visibile quando si annuncia. `{{ctx.report_url}}` è il link di download. | + +`batch_findings` è ciò che una regola può fare e un report pianificato no: creare un report esattamente sui Riscontri appena corrisposti. + +L'annuncio viene registrato come una consegna a sé stante, separata dalla generazione del report, in modo da poter vedere il report riuscire e l'annuncio fallire in modo indipendente. diff --git a/docs/content/automation/rules_engine_2/node_reference.pt-br.md b/docs/content/automation/rules_engine_2/node_reference.pt-br.md new file mode 100644 index 0000000000..071178df60 --- /dev/null +++ b/docs/content/automation/rules_engine_2/node_reference.pt-br.md @@ -0,0 +1,347 @@ +--- +title: Referência de Nós +description: Todos os nós com que o Rules Engine 2.0 vem, e o que cada um faz +weight: 3 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/node_reference/ +--- + +Nota: o Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +O Rules Engine 2.0 vem com 25 nós em quatro categorias. Esta página documenta todos eles. + +Salvo indicação contrária, um nó recebe uma entrada, produz uma saída chamada `out`, e repassa a essa saída cada item que recebeu. Isso importa quando você encadeia nós: um nó de Achados altera o Achado e então repassa o item adiante, de modo que vários deles em sequência são todos aplicados. + +## Gatilhos + +Todo grafo tem exatamente um gatilho, e apenas um gatilho pode iniciar uma execução. Os três produzem itens de Achado, e os três recebem um **Scope** que restringe quais Achados eles produzem. Veja [Construindo Regras](../building_rules/) para saber como o escopo funciona. + +### Em Evento de Achado + +`trigger.finding` + +É executado quando Achados são criados, atualizados, fechados ou reabertos. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Event** | `created` | Qual mudança do Achado ativa esta regra: `created`, `updated`, `closed`, `reopened`, ou `any` para as quatro. | +| **Scope** | vazio | Quais Achados esta regra considera. Vazio significa todo Achado que o proprietário da regra pode ver. | + +Os Achados indicados pelo evento são comparados ao escopo antes de entrarem no grafo, de modo que o evento decide *quando* e o escopo decide *quais*. + +### Em uma Programação + +`trigger.schedule` + +Varre todos os Achados no escopo em uma programação. A programação é configurada na regra e é limitada a marcas de quinze em quinze minutos. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Scope** | vazio | Quais Achados esta regra considera. | + +### Execução Manual + +`trigger.manual` + +Varre todos os Achados no escopo quando você clica em **Run** na regra. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Scope** | vazio | Quais Achados esta regra considera. | + +## Lógica + +### Se / Filtro + +`filter.if` + +Direciona cada item para o ramo **true** ou **false**, de acordo com condições. Este é o único nó com duas saídas, e é assim que um grafo se ramifica. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Conditions** | vazio | Cada linha é um caminho, um operador e um valor. Veja [Condições](../building_rules/#conditions). | +| **Match** | `all` | Se toda condição precisa ser verdadeira (`all`), ou apenas uma delas (`any`). | + +Uma lista de condições vazia passa tudo para o ramo true. Os dois ramos são opcionais: deixar o ramo false sem conexão simplesmente descarta os itens que falharam. + +### Limite + +`flow.limit` + +Passa os primeiros N itens e descarta o restante. Útil como válvula de segurança enquanto você está testando uma regra, e para limitar quantos tickets ou mensagens uma única execução pode produzir. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Keep First** | `100` | Quantos itens repassar. | + +### Deduplicar Dentro da Execução + +`flow.dedupe_batch` + +Mantém o primeiro item por chave e descarta os posteriores que carregam a mesma chave. Restrito à execução, então ele deduplica dentro de uma única execução, e não entre execuções. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Key Path** | `finding.hash_code` | O caminho do item cujo valor identifica uma duplicata. | + +Um uso comum é `finding.component_name`, para notificar uma vez por componente afetado em vez de uma vez por Achado. + +## Achados + +Esses nós alteram Achados. Toda alteração é atribuída de volta à regra, à execução e ao nó que a fez, e aparece na linha do tempo de proveniência do Achado. + +### Definir Severidade + +`finding.set_severity` + +Define a severidade, e recalcula a data de SLA e a prioridade com base nela. + +| Setting | Options | +|---------|---------| +| **Severity** | `Critical`, `High`, `Medium`, `Low`, `Info` | + +### Definir um Campo + +`finding.set_field` + +Define, anexa ao final de, ou insere no início de um campo de texto. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Field** | nenhum | Um de `component_name`, `component_version`, `cvssv3`, `cwe`, `description`, `file_path`, `impact`, `mitigation`, `service`, `title`. | +| **Mode** | `set` | `set`, `append` ou `prepend`. Um vetor CVSSv3 só pode ser substituído. | +| **Value** | nenhum | O texto a escrever. Suporta placeholders no estilo `{{finding.title}}`. | + +### Definir Status + +`finding.set_status` + +Move o Achado para um status. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Status** | nenhum | `active`, `inactive`, `verified`, `unverified`, `false_positive`, `mitigated`, `reopen`. | +| **Note** | vazio | Uma nota opcional registrada junto com a mudança de status. | + +### Adicionar Tags + +`finding.add_tags` + +Adiciona tags ao Achado. As tags existentes são mantidas. + +| Setting | Notes | +|---------|-------| +| **Tags** | Separadas por vírgula. Suporta placeholders no estilo `{{product.name}}`, para que você possa marcar com dados do Achado. | + +### Adicionar uma Nota + +`finding.add_note` + +Adiciona uma nota ao Achado. + +| Setting | Notes | +|---------|-------| +| **Note** | O texto da nota. Suporta placeholders. | + +### Definir Responsáveis + +`finding.set_owners` + +Torna um grupo responsável pelo Achado. + +| Setting | Notes | +|---------|-------| +| **Group** | O grupo dono desses Achados. | + +### Definir Revisores + +`finding.set_reviewers` + +Coloca o Achado em revisão pelos usuários selecionados. + +| Setting | Notes | +|---------|-------| +| **Reviewers** | Um ou mais usuários que devem revisar esses Achados. | + +### Aceitar Risco + +`finding.risk_accept` + +Aceita simplesmente o risco do Achado, ou o adiciona a um registro de aceitação de risco. + +| Setting | Default | Notes | +|---------|---------|-------| +| **How** | `simple` | `simple` define aceitação de risco simples no Achado. `acceptance` o adiciona a um registro de aceitação de risco. | +| **Accepted** | ativado | Exibido para `simple`. Desative para desfazer a aceitação do risco. | +| **Risk Acceptance** | nenhum | Exibido para `acceptance`. A qual aceitação de risco adicionar esses Achados. | + +### Definir Política de Mitigação + +`finding.set_mitigation_policy` + +Define a política de mitigação sob a qual o Achado é corrigido. + +| Setting | Notes | +|---------|-------| +| **Mitigation Policy** | A política a aplicar. | + +### Alterar Prioridade + +`finding.set_priority` + +Define a prioridade, ou a ajusta aritmeticamente. Isso substitui a prioridade calculada. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Operation** | `set` | `set`, `add`, `subtract`, `multiply`, `divide`. | +| **Value** | nenhum | A prioridade a definir, ou a quantidade a ajustar. | + +### Definir Risco + +`finding.set_risk` + +Define o risco, substituindo o calculado. + +| Setting | Options | +|---------|---------| +| **Risk** | `Low`, `Medium`, `Needs Action`, `Urgent` | + +## Saída + +Nós de saída são os nós que saem do DefectDojo. Cada um deles registra uma [Entrega](../deliveries/) antes de qualquer coisa ser enviada, e cada um deles respeita o modo **Simulate** ou **Live** da regra. + +Vários deles oferecem a mesma opção **One Message per Finding**. Desativada, o nó envia uma mensagem descrevendo o lote inteiro, com uma divisão por severidade e uma lista limitada de Achados. Ativada, ele envia uma mensagem por Achado. + +Um nó que envia uma mensagem por Achado para por padrão após 1.000 envios em uma única execução, e registra uma entrada ignorada visível dizendo sobre quantos Achados ele não enviou. Veja [Configuração](../configuration/#per-finding-send-ceiling). + +### Quando um canal está indisponível + +Um nó de saída depende de algo externo à regra: um token do Slack, um webhook do Microsoft Teams, uma configuração do JIRA, um conector licenciado. Quando isso está ausente ou desligado, o nó não consegue funcionar, e o Rules Engine 2.0 avisa disso em três momentos diferentes, em vez de falhar silenciosamente: + +* **Na paleta**, um nó indisponível é marcado como tal, com o motivo, antes de você arrastá-lo para a tela. +* **Ao salvar**, um grafo contendo um nó indisponível é recusado. Esse é o momento em que alguém está presente para escolher outro. +* **Em tempo de execução**, a entrega é **ignorada** com o motivo anexado, não falha. Uma regra salva enquanto o Slack estava ativo não deveria começar a apresentar erros no dia em que alguém desativa o Slack. O registro honesto é uma entrega ignorada dizendo que o Slack está desligado. + +### Criar uma Issue do JIRA + +`ticket.jira` + +Cria ou atualiza a issue do JIRA do Achado. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Skip Findings That Already Have an Issue** | ativado | Deixa intactos os Achados que já têm uma issue do JIRA. | +| **Update an Existing Issue** | desativado | Exibido quando a opção acima está desativada. Envia os Achados que já têm uma issue, para que o JIRA seja atualizado. | + +O resumo, a descrição e a prioridade vêm da configuração do JIRA do produto, não deste nó. Um ticket criado por uma regra é, portanto, idêntico a um criado por push all issues. + +### Criar um Ticket Downstream + +`ticket.downstream` + +Cria ou atualiza um ticket através de um [Downstream Connector](/connectors/downstream/about/). + +| Setting | Default | Notes | +|---------|---------|-------| +| **Issue Trackers** | `auto` | `auto` usa os rastreadores de issues atribuídos ao engajamento ou ao produto. `mapping` direciona para um mapeamento específico. | +| **Issue Tracker Mapping** | nenhum | Exibido para `mapping`. Para qual mapeamento enviar. | +| **Operation** | `create` | `create` um ticket, ou `update` o que já existe. Uma atualização sem ticket existente o cria. | +| **Skip Findings That Already Have a Ticket** | ativado | Deixa intactos os Achados que já têm um ticket no mapeamento de destino. | + +A regra substitui as configurações automáticas de push da atribuição: os filtros de severidade e apenas-ativos não são aplicados uma segunda vez aqui. Um Achado cujo ticket já existe é ignorado, não importa como aquele ticket tenha sido criado. + +### Enviar uma Mensagem no Slack + +`notify.slack` + +Publica em um canal do Slack através de um Conector de Mensagens. A conexão carrega o token do bot; as configurações do Slack de toda a instância em **System Settings** não são usadas e não servem como alternativa. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Connection** | nenhuma | Um [Messaging Connector](/issue_tracking/pro_integration/messaging_connectors/) desse tipo. Obrigatório. | +| **Destination** | vazio | Exibido assim que uma conexão é escolhida. Os campos dependem do fornecedor da conexão. | +| **One Message per Finding** | desativado | Desativado envia uma mensagem sobre o lote. | +| **Message** | `{{finding.severity}}: {{finding.title}} ({{product.name}})` | Renderizado por Achado. | +| **Findings Listed in the Digest** | `10` | Exibido para mensagens em lote. Quantos Achados a mensagem lista antes de dizer quantos mais existiam. | + +### Enviar uma Mensagem no Microsoft Teams + +`notify.msteams` + +Publica um cartão através de um Conector de Mensagens. A conexão carrega a URL do fluxo de trabalho do Power Automate; o webhook do Teams de toda a instância em **System Settings** não é usado e não serve como alternativa. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Connection** | nenhuma | Um [Messaging Connector](/issue_tracking/pro_integration/messaging_connectors/) desse tipo. Obrigatório. | +| **Destination** | vazio | Exibido assim que uma conexão é escolhida. Os campos dependem do fornecedor da conexão. | +| **One Message per Finding** | desativado | Desativado envia um cartão sobre o lote. | +| **Message** | `{{finding.severity}}: {{finding.title}} ({{product.name}})` | Renderizado por Achado. | +| **Findings Listed in the Digest** | `10` | Exibido para mensagens em lote. | + +### Enviar um E-mail + +`notify.email` + +Envia e-mail para uma lista fixa de endereços através de um Conector de Mensagens. Os destinatários são o destino da conexão. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Connection** | nenhuma | Um [Messaging Connector](/issue_tracking/pro_integration/messaging_connectors/) desse tipo. Obrigatório. | +| **Destination** | vazio | Exibido assim que uma conexão é escolhida. Os campos dependem do fornecedor da conexão. | + +| **Subject** | `[DefectDojo] {{ctx.count}} finding(s) from rule {{ctx.rule_name}}` | Renderizado uma vez por mensagem. | +| **Body** | um corpo HTML contendo `{{ctx.findings_html}}` | HTML. `{{ctx.findings_html}}` renderiza a lista de Achados. | +| **One Message per Finding** | desativado | Desativado envia um e-mail sobre o lote. | +| **Findings Listed in the Body** | `25` | Quantos Achados `{{ctx.findings_html}}` lista antes de dizer quantos mais existiam. | + +### Chamar um Webhook + +`notify.webhook` + +Envia um POST com JSON para um endpoint de webhook. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Webhook Endpoint** | nenhum | Um [notification webhook](/automation/api/notification_webhooks/) configurado. Seu cabeçalho personalizado é enviado com a requisição. | +| **URL** | vazio | Exibido quando nenhum endpoint é selecionado. Para onde fazer o POST. | +| | | Um dos dois acima é obrigatório. | +| **Signing Secret** | vazio | Assina o corpo como `X-DefectDojo-Signature: sha256=HMAC`. | +| **One Message per Finding** | desativado | Desativado publica o lote inteiro em uma única requisição. | + +Duas coisas a saber. Um signing secret digitado aqui é armazenado junto com a regra, então, para qualquer coisa sensível, prefira um endpoint configurado e seu próprio cabeçalho. E um webhook chamado por uma regra nunca altera o status de saúde daquele endpoint, então uma regra não pode desativar seus webhooks de notificação ao falhar. + +URLs em texto livre são validadas quando você salva. Veja [Configuration](../configuration/#outbound-destination-validation) para saber o que é rejeitado e como permitir endereços privados. + +### Emitir um Alerta no Aplicativo + +`notify.alert` + +Cria um alerta no aplicativo sobre o lote. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Title** | `Rules Engine 2.0: {{ctx.rule_name}}` | Renderizado uma vez para o lote inteiro. | +| **Description** | `{{ctx.count}} finding(s) matched the rule {{ctx.rule_name}}.` | Renderizado uma vez para o lote inteiro. | +| **Recipients** | vazio | Nomes de usuário, separados por vírgula. Vazio alerta os administradores. | + +Os destinatários ainda controlam isso por meio de sua própria configuração de notificação **Rules Engine Match**, de modo que um alerta não pode contornar as preferências de notificação de um usuário. + +### Gerar um Relatório + +`report.generate` + +Gera um relatório a partir de um modelo, restrito aos Achados que chegaram a este nó, e pode anunciar o link de download. + +| Setting | Default | Notes | +|---------|---------|-------| +| **Report Template** | nenhum | A partir de qual modelo gerar. Obrigatório. | +| **Format** | `pdf` | `pdf` ou `html`. | +| **Findings Included** | `batch_findings` | `batch_findings` limita o relatório aos Achados que chegaram a este nó. `template_default` permite que o modelo use seus próprios filtros. | +| **Announce Over** | nenhum | Um [Messaging Connector](/issue_tracking/pro_integration/messaging_connectors/) pelo qual publicar o link de download assim que o relatório for gerado. Deixe vazio para não anunciar. | +| **Announce To** | vazio | Exibido assim que uma conexão é escolhida. Para onde essa conexão envia: um ID de canal do Slack, endereços de e-mail, e assim por diante. | +| **Announcement** | `Report ready: {{ctx.report_url}}` | Exibido ao anunciar. `{{ctx.report_url}}` é o link de download. | + +`batch_findings` é o que uma regra consegue fazer e um relatório agendado não: reportar exatamente os Achados que acabaram de corresponder. + +O anúncio é registrado como sua própria entrega, separada da geração do relatório, de modo que você pode ver o relatório ter sucesso e o anúncio falhar de forma independente. diff --git a/docs/content/automation/rules_engine_2/node_reference.zh-hans.md b/docs/content/automation/rules_engine_2/node_reference.zh-hans.md new file mode 100644 index 0000000000..2abdf5b985 --- /dev/null +++ b/docs/content/automation/rules_engine_2/node_reference.zh-hans.md @@ -0,0 +1,347 @@ +--- +title: 节点参考 +description: Rules Engine 2.0 内置的每一个节点及其作用 +weight: 3 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/node_reference/ +--- + +注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。 + +Rules Engine 2.0 内置了分为四大类的 25 个节点。本页对它们逐一进行说明。 + +除非另有说明，每个节点都接受一个输入，产生一个名为 `out` 的输出，并将其收到的每一项都传递给该输出。这一点在你串联多个节点时很重要：一个发现项节点会先修改该发现项，然后再将其向后传递，因此依次排列的多个此类节点都会依次生效。 + +## 触发器 + +每张图中都有且仅有一个触发器，也只有触发器才能启动一次运行。三种触发器都会产生发现项，并且都带有一个**范围**设置，用来限定它们产生哪些发现项。范围的具体工作方式参见[构建规则](../building_rules/)。 + +### 发现项事件 + +`trigger.finding` + +当发现项被创建、更新、关闭或重新打开时运行。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **事件** | `created` | 触发该规则的发现项变化类型：`created`、`updated`、`closed`、`reopened`，或用 `any` 表示以上四种全部。 | +| **范围** | 空 | 该规则所考虑的发现项范围。留空表示规则所有者可见的所有发现项。 | + +事件所指定的发现项，在进入图之前会先与范围进行匹配，因此事件决定*何时*触发，范围决定触发*哪些*对象。 + +### 按计划 + +`trigger.schedule` + +按照计划扫描范围内的所有发现项。该计划在规则上配置，且只能设置为整刻钟（每 15 分钟）的时间点。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **范围** | 空 | 该规则所考虑的发现项范围。 | + +### 手动运行 + +`trigger.manual` + +当你在规则上点击**运行**时，扫描范围内的所有发现项。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **范围** | 空 | 该规则所考虑的发现项范围。 | + +## 逻辑 + +### 条件判断 / 过滤 + +`filter.if` + +根据条件，将每一项路由到**真**或**假**分支。这是唯一一个拥有两个输出的节点，也是图实现分支的方式。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **条件** | 空 | 每一行由一个路径、一个运算符和一个值组成。参见[条件](../building_rules/#conditions)。 | +| **匹配** | `all` | 是要求所有条件都成立（`all`），还是只需其中一个成立（`any`）。 | + +空的条件列表会让所有项都进入真分支。两个分支都是可选的：如果不连接假分支，未通过条件的项就会被直接丢弃。 + +### 限制数量 + +`flow.limit` + +只放行前 N 项，其余全部丢弃。在测试规则时可以用作安全阀，也可以用来限制单次运行最多产生多少个工单或消息。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **保留前几项** | `100` | 要放行的项目数量。 | + +### 在单次运行内去重 + +`flow.dedupe_batch` + +对于同一个键，只保留第一项，之后携带相同键的项一律丢弃。该去重范围限定在单次运行内，因此只在一次执行内部去重，不会跨多次执行去重。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **键路径** | `finding.hash_code` | 用于判定重复项的字段路径。 | + +一个常见用法是使用 `finding.component_name`，从而按受影响的组件而不是按发现项逐一通知。 + +## 发现项 + +这些节点会修改发现项。每一次修改都会被追溯到进行该修改的规则、运行和节点，并显示在该发现项的溯源时间线上。 + +### 设置严重程度 + +`finding.set_severity` + +设置严重程度，并据此重新计算 SLA 日期和优先级。 + +| 设置 | 选项 | +|-----|-----| +| **严重程度** | `Critical`、`High`、`Medium`、`Low`、`Info` | + +### 设置字段 + +`finding.set_field` + +设置某个文本字段，或在其后追加内容、在其前插入内容。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **字段** | 无 | 可选值为 `component_name`、`component_version`、`cvssv3`、`cwe`、`description`、`file_path`、`impact`、`mitigation`、`service`、`title` 之一。 | +| **模式** | `set` | `set`、`append` 或 `prepend`。CVSSv3 向量只能被替换。 | +| **值** | 无 | 要写入的文本内容。支持 `{{finding.title}}` 这类占位符。 | + +### 设置状态 + +`finding.set_status` + +将发现项变更为指定状态。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **状态** | 无 | `active`、`inactive`、`verified`、`unverified`、`false_positive`、`mitigated`、`reopen`。 | +| **备注** | 空 | 随状态变更一并记录的可选备注。 | + +### 添加标签 + +`finding.add_tags` + +为发现项添加标签，已有标签保持不变。 + +| 设置 | 说明 | +|-----|-----| +| **标签** | 用逗号分隔。支持 `{{product.name}}` 这类占位符，因此你可以用发现项中的数据来打标签。 | + +### 添加备注 + +`finding.add_note` + +为发现项添加一条备注。 + +| 设置 | 说明 | +|-----|-----| +| **备注** | 备注内容。支持占位符。 | + +### 设置负责人 + +`finding.set_owners` + +指定一个组对该发现项负责。 + +| 设置 | 说明 | +|-----|-----| +| **组** | 负责这些发现项的组。 | + +### 设置审核人 + +`finding.set_reviewers` + +将该发现项交由所选用户进行审核。 + +| 设置 | 说明 | +|-----|-----| +| **审核人** | 应当审核这些发现项的一位或多位用户。 | + +### 接受风险 + +`finding.risk_accept` + +对该发现项进行简单风险接受，或将其加入某条风险接受记录。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **方式** | `simple` | `simple` 会对该发现项设置简单风险接受；`acceptance` 会将其加入某条风险接受记录。 | +| **已接受** | 开启 | 在选择 `simple` 时显示。关闭表示取消风险接受。 | +| **风险接受** | 无 | 在选择 `acceptance` 时显示。指定要将这些发现项加入哪条风险接受记录。 | + +### 设置缓解策略 + +`finding.set_mitigation_policy` + +设置该发现项所依据的整改缓解策略。 + +| 设置 | 说明 | +|-----|-----| +| **缓解策略** | 要应用的策略。 | + +### 更改优先级 + +`finding.set_priority` + +设置优先级，或对其进行算术调整。此操作会覆盖系统计算出的优先级。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **操作** | `set` | `set`、`add`、`subtract`、`multiply`、`divide`。 | +| **值** | 无 | 要设置的优先级，或要调整的数值。 | + +### 设置风险 + +`finding.set_risk` + +设置风险等级，覆盖系统计算出的结果。 + +| 设置 | 选项 | +|-----|-----| +| **风险** | `Low`、`Medium`、`Needs Action`、`Urgent` | + +## 出站节点 + +出站节点是指会离开 DefectDojo 向外发送内容的节点。在发送任何内容之前，每一个出站节点都会先记录一条[投递记录](../deliveries/)，并且都会遵循该规则所处的**模拟**或**正式**模式。 + +其中有几个节点都提供相同的**按发现项逐条发送**选项。关闭时，节点会发送一条描述整批内容的消息，其中包含严重程度细分和一份数量有上限的发现项列表；开启时，则会按发现项逐条发送消息。 + +按发现项逐条发送消息的节点，默认在单次运行中发送满 1,000 条后就会停止，并记录一条可见的跳过说明，注明还有多少发现项未被发送。参见[配置](../configuration/#per-finding-send-ceiling)。 + +### 当渠道不可用时 + +出站节点依赖于规则之外的某些资源：Slack 令牌、Microsoft Teams webhook、JIRA 配置、已获得许可的连接器等。当这些资源缺失或被关闭时，该节点就无法工作，而 Rules Engine 2.0 会在三个不同的时刻明确告知这一点，而不是悄无声息地失败： + +* **在节点面板中**，不可用的节点在你将其拖到画布上之前，就已经被标注为不可用并说明原因。 +* **在保存时**，包含不可用节点的图会被拒绝保存。这正是有人在场、可以另选一个节点的时刻。 +* **在运行时**，该次投递会被标记为**跳过**并附带原因，而不是标记为失败。在 Slack 开启时保存的规则，不应该在有人关闭 Slack 的那天开始报错。诚实的记录方式，就是一条说明“Slack 已关闭”的跳过记录。 + +### 创建 JIRA 问题 + +`ticket.jira` + +为该发现项创建或更新 JIRA 问题。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **跳过已存在问题的发现项** | 开启 | 对已经存在 JIRA 问题的发现项不做处理。 | +| **更新已存在的问题** | 关闭 | 在上面的跳过选项关闭时显示。会推送已存在问题的发现项，从而更新 JIRA 中的内容。 | + +摘要、描述和优先级均来自该产品的 JIRA 配置，而非来自此节点。因此，规则所创建的工单，与通过“推送所有问题”创建的工单完全相同。 + +### 创建下游工单 + +`ticket.downstream` + +通过[下游连接器](/connectors/downstream/about/)创建或更新工单。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **问题跟踪系统** | `auto` | `auto` 使用分配给该测试活动或产品的问题跟踪系统；`mapping` 则指定某一个具体的映射。 | +| **问题跟踪系统映射** | 无 | 在选择 `mapping` 时显示。指定要推送到哪一个映射。 | +| **操作** | `create` | `create` 表示创建工单，`update` 表示更新已存在的工单。如果执行更新时并不存在对应工单，则会创建一个。 | +| **跳过已有工单的发现项** | 开启 | 对目标映射中已经存在工单的发现项不做处理。 | + +该规则会取代分配设置中的自动推送配置：严重程度和“仅活动”过滤条件不会在此处被再次应用。无论某个发现项的工单最初是如何创建的，只要工单已存在，就会被跳过。 + +### 发送 Slack 消息 + +`notify.slack` + +通过消息连接器发布到 Slack 频道。机器人令牌保存在该连接中；**系统设置**下的实例级 Slack 设置不会被使用，也不会作为后备方案。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **连接** | 无 | 该类型的[消息连接器](/issue_tracking/pro_integration/messaging_connectors/)。必填。 | +| **目的地** | 空 | 在选定连接后显示。具体字段取决于该连接所使用的供应商。 | +| **按发现项逐条发送** | 关闭 | 关闭时，会针对整批内容发送一条消息。 | +| **消息内容** | `{{finding.severity}}: {{finding.title}} ({{product.name}})` | 按发现项逐条渲染。 | +| **摘要中列出的发现项数量** | `10` | 用于批量消息。指消息中列出多少条发现项后，再说明还有多少条未列出。 | + +### 发送 Microsoft Teams 消息 + +`notify.msteams` + +通过消息连接器发布一张卡片。Power Automate 工作流的 URL 保存在该连接中；**系统设置**下的实例级 Teams webhook 不会被使用，也不会作为后备方案。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **连接** | 无 | 该类型的[消息连接器](/issue_tracking/pro_integration/messaging_connectors/)。必填。 | +| **目的地** | 空 | 在选定连接后显示。具体字段取决于该连接所使用的供应商。 | +| **按发现项逐条发送** | 关闭 | 关闭时，会针对整批内容发送一张卡片。 | +| **消息内容** | `{{finding.severity}}: {{finding.title}} ({{product.name}})` | 按发现项逐条渲染。 | +| **摘要中列出的发现项数量** | `10` | 用于批量消息。 | + +### 发送电子邮件 + +`notify.email` + +通过消息连接器向一组固定的地址发送电子邮件。收件人即该连接的目的地。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **连接** | 无 | 该类型的[消息连接器](/issue_tracking/pro_integration/messaging_connectors/)。必填。 | +| **目的地** | 空 | 在选定连接后显示。具体字段取决于该连接所使用的供应商。 | + +| **主题** | `[DefectDojo] {{ctx.count}} finding(s) from rule {{ctx.rule_name}}` | 每条消息渲染一次。 | +| **正文** | 包含 `{{ctx.findings_html}}` 的 HTML 正文 | HTML。`{{ctx.findings_html}}` 用于渲染发现项列表。 | +| **按发现项逐条发送** | 关闭 | 关闭时，会针对整批内容发送一封电子邮件。 | +| **正文中列出的发现项数量** | `25` | `{{ctx.findings_html}}` 会列出多少条发现项后，再说明还有多少条未列出。 | + +### 调用 Webhook + +`notify.webhook` + +向某个 webhook 端点 POST JSON 数据。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **Webhook 端点** | 无 | 一个已配置的[通知 webhook](/automation/api/notification_webhooks/)。其自定义请求头会随请求一并发送。 | +| **URL** | 空 | 在未选择端点时显示。指定要 POST 到的地址。 | +| | | 以上两者必须填写其中一个。 | +| **签名密钥** | 空 | 以 `X-DefectDojo-Signature: sha256=HMAC` 的形式对请求体进行签名。 | +| **按发现项逐条发送** | 关闭 | 关闭时，会将整批内容放在一个请求中发送。 | + +有两点需要注意。在此处填写的签名密钥会与规则一起存储，因此对于任何敏感信息，最好使用已配置的端点及其自带的请求头。此外，规则调用 webhook 从不会改变该端点自身的健康状态，因此规则本身的失败不会导致你的通知 webhook 被禁用。 + +手动填写的 URL 会在保存时进行校验。哪些地址会被拒绝、以及如何允许私有地址，参见[配置](../configuration/#outbound-destination-validation)。 + +### 触发应用内提醒 + +`notify.alert` + +针对整批内容创建一条应用内提醒。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **标题** | `Rules Engine 2.0: {{ctx.rule_name}}` | 针对整批内容渲染一次。 | +| **描述** | `{{ctx.count}} finding(s) matched the rule {{ctx.rule_name}}.` | 针对整批内容渲染一次。 | +| **接收人** | 空 | 用户名，用逗号分隔。留空则提醒管理员。 | + +接收人仍然可以通过自己的**Rules Engine Match** 通知设置来控制这一行为，因此提醒无法绕过用户自己的通知偏好设置。 + +### 生成报告 + +`report.generate` + +根据模板生成一份报告，范围限定为到达此节点的发现项，并可以通知发送该报告的下载链接。 + +| 设置 | 默认值 | 说明 | +|-----|-----|-----| +| **报告模板** | 无 | 用于生成报告的模板。必填。 | +| **格式** | `pdf` | `pdf` 或 `html`。 | +| **包含的发现项** | `batch_findings` | `batch_findings` 会将报告限定为到达此节点的发现项；`template_default` 则让模板使用自己的过滤条件。 | +| **通知渠道** | 无 | 报告生成后，用于发布下载链接的[消息连接器](/issue_tracking/pro_integration/messaging_connectors/)。留空则不发送通知。 | +| **通知目标** | 空 | 在选定连接后显示。指该连接的发送位置：Slack 频道 ID、电子邮件地址等等。 | +| **通知内容** | `Report ready: {{ctx.report_url}}` | 在发送通知时显示。`{{ctx.report_url}}` 即下载链接。 | + +`batch_findings` 正是规则能做到、而定时报告做不到的事情：精确针对刚刚匹配到的那些发现项生成报告。 + +该通知会作为一条独立的投递记录单独记录，与报告的生成过程分开，因此你可以分别查看报告生成成功、而通知发送失败这样的情况。 diff --git a/docs/content/automation/rules_engine_2/runs.it.md b/docs/content/automation/rules_engine_2/runs.it.md new file mode 100644 index 0000000000..94b5051c20 --- /dev/null +++ b/docs/content/automation/rules_engine_2/runs.it.md @@ -0,0 +1,133 @@ +--- +title: Esecuzioni +description: Come viene eseguita una regola, cosa registra un'esecuzione e come viene + limitata la propagazione a cascata +weight: 4 +audience: pro +aliases: +- /it/automation/rules_engine_v2/runs/ +--- + +Nota: Rules Engine 2.0 è una funzionalità disponibile solo in DefectDojo Pro. + +Un **run** è una singola esecuzione di una regola. Ogni run viene registrato, sia che abbia avuto esito positivo sia che sia fallito, e ogni nodo al suo interno lascia una traccia. **Rules Engine 2.0 > Runs** li elenca. + +## Cosa registra un run + +| Campo | Significato | +|-------|---------| +| **Rule** | La regola che è stata eseguita. | +| **Trigger** | L'evento che lo ha avviato, ad esempio `finding.created`, `schedule` o `manual`. | +| **Triggered by** | La persona che lo ha avviato, quando una persona lo ha fatto: chi ha premuto Run, oppure chi ha salvato il Finding che lo ha attivato. Vuoto per una pianificazione, e per una modifica alla quale nessuno era presente, come un'importazione o una chiamata API senza utente. Questo campo è distinto dal proprietario della regola, che è l'identità con cui il run viene eseguito. | +| **Status** | `Running`, `Success` o `Error`. | +| **Started** e **Finished** | Quando è stato eseguito. Finished è vuoto solo mentre è ancora in esecuzione. | +| **Error** | L'errore che lo ha terminato, in caso di fallimento. | +| **Stats** | Totali per nodo, eventi a cascata e lavoro differito. | +| **Depth** | Quanti passaggi a cascata separano questo run dall'evento che lo ha originato. | +| **Source run** | Il run il cui evento emesso ha attivato questo, nel caso di un run a cascata. | + +### La traccia dei nodi + +All'interno di un run, ogni nodo registra una propria riga: + +| Campo | Significato | +|-------|---------| +| **Order** | La posizione del nodo nell'ordine di esecuzione. | +| **Node** | Il suo id, il suo tipo e la sua etichetta, se ne è stata assegnata una. | +| **Status** | Se il nodo è stato completato o ha generato un errore. | +| **Items in** | Quanti elementi sono entrati. | +| **Items out** | Quanti ne sono usciti, suddivisi per handle di output, in modo che un nodo If / Filter mostri separatamente i conteggi true e false. | +| **Summary** | I contatori riportati dal nodo, ad esempio quanti Finding ha modificato. | +| **Error** | L'errore generato, in caso di fallimento. | + +La traccia è ciò che si consulta quando una regola non ha fatto ciò che ci si aspettava. Un nodo If / Filter che riporta 400 elementi in ingresso e 0 sul ramo true indica che le condizioni sono sbagliate, senza dover indovinare. + +## Modello di esecuzione + +I nodi vengono eseguiti in ordine topologico: un nodo viene eseguito solo dopo che tutto ciò che lo alimenta è stato eseguito. Un nodo con più archi in ingresso riceve tutti i relativi output concatenati. Un nodo privo di input viene comunque eseguito, con un elenco di input vuoto. + +### Un run fallito non cambia nulla + +Un run è atomico. Se un nodo genera un errore, ogni modifica ai Finding effettuata dal run viene annullata (rollback). + +La traccia non viene annullata insieme al resto. Le righe dei nodi e lo stato `Error` vengono scritti in seguito, quindi un run fallito indica esattamente quale nodo si è rotto senza lasciare modifiche parzialmente applicate. Questa è la garanzia più importante da tenere presente leggendo la pagina Runs: un run in errore è un run che non ha fatto nulla. + +L'egress segue la stessa regola. Le consegne (deliveries) vengono registrate all'interno della transazione del run e vengono inviate solo dopo il commit, quindi un run che viene annullato non invia nulla. + +### Un solo run per regola alla volta + +Una regola può avere un solo run in corso. Un secondo trigger per la stessa regola mentre è ancora in esecuzione non entra in competizione con essa: attende e riprova. + +Regole diverse vengono eseguite in modo completamente concorrente, quindi una regola lenta non blocca mai le altre. + +Se un run viene in qualche modo abbandonato, ad esempio perché il worker che lo eseguiva è stato terminato, il suo lock viene rilasciato dopo una finestra di stallo (30 minuti per impostazione predefinita), in modo che la regola non resti bloccata per sempre. Un run che si avvicina a questa soglia si interrompe da solo per primo, annullandosi in modo pulito, così un run semplicemente lento non può mai finire per essere eseguito insieme alla propria sostituzione. + +## Cascata + +Una regola che modifica un Finding produce esattamente il tipo di evento su cui un'altra regola può attivarsi. Rules Engine 2.0 lo consente, quindi catene del tipo `A -> B -> C` funzionano, e le limita in due modi indipendenti: + +* **Profondità.** Un evento può percorrere al massimo **3** passaggi a cascata dalla modifica che lo ha originato. +* **Appartenenza alla catena.** Ogni evento porta con sé l'elenco delle regole già attraversate nella sua catena, e una regola non viene mai eseguita due volte nella stessa catena. Quindi una regola non può riattivare se stessa, e due regole non possono rimbalzare tra loro. + +I campi **Depth** e **Source run** di un run permettono di risalire una catena fino alla modifica che l'ha avviata. **Triggered by** viene trasmesso lungo tutta la catena, quindi una cascata avviata da una persona resta attribuibile a quella persona a ogni passaggio. + +Le modifiche effettuate *da* una regola in esecuzione vengono attribuite alla cascata di quella regola, invece di apparire come nuova attività dell'utente, così una regola che delega lavoro internamente non gonfia la catena. + +## Scala e limiti + +**Un run non ha un limite massimo.** Una regola elabora tutto ciò che corrisponde al suo ambito, per quanto grande sia. Una regola che si fermasse silenziosamente ai primi N Finding sarebbe una regola di cui non ci si potrebbe fidare. + +Un run viene invece elaborato in **blocchi (chunk)**, 1.000 Finding alla volta per impostazione predefinita. Solo il blocco corrente viene mantenuto in memoria, quindi una scansione su un ambito molto ampio è limitata in memoria, non in copertura. L'unica eccezione è **Preview**, che applica un limite e lo segnala nella propria traccia quando tronca i risultati. + +Altri due numeri determinano come viene suddiviso il lavoro: + +* **Finding per evento**, 500 per impostazione predefinita. Una modifica in blocco viene suddivisa su più eventi, ciascuno dei quali diventa un proprio run. L'effetto pratico per un'importazione di grandi dimensioni è un numero gestibile di run, invece di un run per ogni Finding. +* **Limite di invio per Finding**, 1.000 per impostazione predefinita. Un nodo di egress impostato per inviare un messaggio per ogni Finding si ferma a questo numero all'interno di un singolo run e registra uno skip visibile che indica per quanti Finding non ha inviato nulla. Questo limita le righe di consegna e le attività in coda, che un run suddiviso in blocchi non limita più da solo. + +Tutti e tre sono impostazioni di deployment, documentate in [Configuration](../configuration/). + +### Quanto può durare un run + +Un run registra un **heartbeat** dopo ogni blocco. Il rilevamento dello stallo legge questo heartbeat anziché l'orario di avvio, quindi una scansione lunga che sta ancora facendo progressi non viene mai scambiata per un worker bloccato. + +Si applicano due finestre temporali, entrambe configurabili: + +* Un run che rimane 30 minuti senza heartbeat viene considerato abbandonato, segnato come errore, e il suo lock viene rilasciato. +* Un run viene terminato forzatamente dopo sei ore, come protezione contro un run che non finirebbe mai. + +## Conservazione + +I run vengono conservati per **180 giorni** per impostazione predefinita, insieme alle relative righe per nodo e alla provenienza dei Finding. Le consegne (deliveries) vengono conservate per 180 giorni separatamente. + +Il prodotto lo comunica esplicitamente, invece di lasciarlo implicito: il dettaglio di un run mostra la finestra di conservazione e la data in cui quel run verrà eliminato. Un run che detiene ancora consegne viene mantenuto finché queste non vengono rimosse. + +Entrambe le finestre sono configurabili, ed è possibile impostarne una qualsiasi per conservare i record a tempo indeterminato. Vedere [Configuration](../configuration/#retention). + +## Eseguire una regola manualmente + +Una regola il cui trigger è **Manual Run** viene eseguita con l'azione **Run** nell'elenco delle regole. Le regole con altri trigger vengono eseguite quando il rispettivo trigger scatta. + +**Preview**, nell'editor, è l'altro modo per eseguire un grafo. Esegue il motore reale e poi annulla tutto, non registra alcun run, e forza l'egress a simulare. Usa preview mentre costruisci, e i run per vedere cosa è realmente successo. + +## Provenienza su un Finding + +I run rispondono alla domanda "cosa ha fatto questa regola?". La provenienza risponde alla domanda opposta: "perché questo Finding è cambiato?". + +Ogni modifica effettuata da una regola viene registrata a fronte del Finding con la regola, il run e il nodo responsabili, e appare come una timeline sul Finding stesso. Le azioni registrate sono: + +| Azione | Significato | +|--------|---------| +| `created`, `updated`, `closed`, `reopened` | Il ciclo di vita del Finding è cambiato. | +| `duplicate`, `status_change` | I suoi flag di duplicato o di stato sono cambiati. | +| `notified` | È stata inviata una notifica a riguardo. | +| `delivered` | Una consegna in uscita lo ha riguardato. | + +Le modifiche ai campi registrano cosa è cambiato, incluso il valore precedente e successivo di ogni campo. I valori molto lunghi vengono troncati nel record, in modo che la timeline resti una registrazione della modifica e non una seconda copia del Finding. + +Anche le notifiche e le consegne vengono registrate qui. È una scelta deliberata: una regola che ha inviato un messaggio ma non ha modificato alcun campo altrimenti non lascerebbe alcuna traccia sul Finding. + +La provenienza sopravvive alla regola. Eliminare una regola o un run mantiene le voci della timeline e si limita a scollegarle, così la cronologia non scompare quando qualcuno fa pulizia. + +## Eliminare regole con cronologia + +Una regola che ha prodotto delle consegne non può essere eliminata lasciandole orfane. Elimina prima le consegne, oppure mantieni la regola e disattivala. Questo è intenzionale: le consegne conservano il record di ciò che è stato effettivamente inviato ai sistemi esterni, e un'eliminazione a cascata trascinerebbe con sé gli invii in corso. diff --git a/docs/content/automation/rules_engine_2/runs.pt-br.md b/docs/content/automation/rules_engine_2/runs.pt-br.md new file mode 100644 index 0000000000..7c7bc4e5c7 --- /dev/null +++ b/docs/content/automation/rules_engine_2/runs.pt-br.md @@ -0,0 +1,133 @@ +--- +title: Execuções +description: Como uma regra é executada, o que uma execução registra e como o encadeamento + é limitado +weight: 4 +audience: pro +aliases: +- /pt-br/automation/rules_engine_v2/runs/ +--- + +Observação: o Rules Engine 2.0 é um recurso exclusivo do DefectDojo Pro. + +Um **run** (execução) é a execução de uma regra. Toda execução é registrada, tenha sido bem-sucedida ou não, e cada nó dentro dela deixa um rastro. **Rules Engine 2.0 > Runs** lista essas execuções. + +## O que uma execução registra + +| Campo | Significado | +|-------|---------| +| **Rule** | A regra que foi executada. | +| **Trigger** | O evento que iniciou a execução, por exemplo `finding.created`, `schedule` ou `manual`. | +| **Triggered by** | A pessoa que a disparou, quando uma pessoa esteve envolvida: quem clicou em Run, ou quem salvou o Finding que a disparou. Fica vazio para um agendamento, e para uma alteração em que ninguém esteve presente, como uma importação ou uma chamada de API sem usuário. Isso é diferente do proprietário da regra, que é quem a execução realmente executa **como**. | +| **Status** | `Running`, `Success` ou `Error`. | +| **Started** e **Finished** | Quando foi executada. Finished fica vazio apenas enquanto ela ainda está em execução. | +| **Error** | O erro que a encerrou, caso tenha falhado. | +| **Stats** | Totais por nó, eventos em cascata e trabalho adiado. | +| **Depth** | Quantos saltos de cascata esta execução está distante do evento que a originou. | +| **Source run** | A execução cujo evento emitido disparou esta, no caso de uma execução em cascata. | + +### O rastro dos nós + +Dentro de uma execução, cada nó registra sua própria linha: + +| Campo | Significado | +|-------|---------| +| **Order** | Onde o nó se posicionou na ordem de execução. | +| **Node** | Seu id, seu tipo e seu rótulo, se você tiver definido um. | +| **Status** | Se o nó foi concluído ou gerou um erro. | +| **Items in** | Quantos itens entraram. | +| **Items out** | Quantos saíram, detalhados por handle de saída, de modo que um nó If / Filter mostra suas contagens de verdadeiro e falso separadamente. | +| **Summary** | Quaisquer contadores que o nó tenha reportado, por exemplo quantos Findings ele alterou. | +| **Error** | O erro gerado, caso tenha falhado. | + +O rastro é o que você lê quando uma regra não fez o que você esperava. Um nó If / Filter reportando 400 itens de entrada e 0 no ramo verdadeiro informa que as condições estão erradas, sem que você precise adivinhar. + +## Modelo de execução + +Os nós são executados em ordem topológica: um nó é executado assim que tudo que o alimenta já foi executado. Um nó com várias arestas de entrada recebe todas as saídas delas concatenadas. Um nó sem nada o alimentando ainda é executado, com uma lista de entrada vazia. + +### Uma execução com falha não altera nada + +Uma execução é atômica. Se qualquer nó gerar um erro, toda alteração de Finding feita pela execução é revertida. + +O rastro não é revertido junto. As linhas dos nós e o status `Error` são gravados depois, de modo que uma execução com falha mostra exatamente qual nó quebrou, sem deixar nenhuma edição parcialmente aplicada para trás. Esta é a garantia mais importante a se ter em mente ao ler a página Runs: uma execução com erro é uma execução que não fez nada. + +A saída (egress) segue a mesma regra. As entregas são registradas dentro da transação da execução e só são despachadas depois que ela é confirmada (commit), de modo que uma execução revertida não envia nada. + +### Uma execução por regra por vez + +Uma regra só pode ter uma execução em andamento. Um segundo disparo para a mesma regra enquanto ela ainda está em execução não entra em disputa com ela. Ele aguarda e tenta novamente. + +Regras diferentes são executadas totalmente em paralelo, de modo que uma regra lenta nunca atrasa suas irmãs. + +Se uma execução for de alguma forma abandonada, por exemplo porque o worker que a executava foi encerrado, seu lock é liberado após uma janela de inatividade (30 minutos por padrão), de modo que a regra não fique travada para sempre. Uma execução próxima dessa janela se interrompe primeiro, revertendo tudo de forma limpa, de modo que uma execução apenas lenta nunca acaba sendo executada junto com sua própria substituta. + +## Encadeamento (cascata) + +Uma regra que altera um Finding produz exatamente o tipo de evento que outra regra pode usar como gatilho. O Rules Engine 2.0 permite isso, de modo que cadeias `A -> B -> C` funcionam, e as limita de duas formas independentes: + +* **Depth (profundidade).** Um evento pode percorrer no máximo **3** saltos de cascata a partir da alteração que o originou. +* **Pertencimento à cadeia.** Todo evento carrega a lista de regras já percorridas em sua cadeia, e uma regra nunca é executada duas vezes na mesma cadeia. Assim, uma regra não pode disparar a si mesma novamente, e duas regras não podem ficar em ping-pong. + +Os campos **Depth** e **Source run** de uma execução permitem rastrear uma cadeia até a alteração que a iniciou. **Triggered by** é propagado por toda a cadeia, de modo que uma cascata disparada por uma pessoa permanece atribuída a ela em cada salto. + +Alterações feitas *por* uma regra em execução são atribuídas à própria cascata dessa regra, em vez de parecerem nova atividade do usuário, de modo que uma regra que delega trabalho internamente não infla a cadeia. + +## Escala e limites + +**Uma execução não tem limite superior de itens.** Uma regra processa tudo o que seu escopo corresponde, por maior que seja. Uma regra que parasse silenciosamente nos primeiros N Findings seria uma regra na qual você não poderia confiar. + +Em vez disso, uma execução é processada em **blocos (chunks)**, 1.000 Findings por vez por padrão. Apenas o bloco fica em memória, de modo que uma varredura sobre um escopo muito grande é limitada em memória, não em cobertura. A única exceção é o **Preview**, que tem um limite, e informa isso em seu rastro quando trunca. + +Outros dois números moldam como o trabalho é dividido: + +* **Findings per event**, 500 por padrão. Uma alteração em massa é dividida em vários eventos, cada um se tornando sua própria execução. O efeito prático para uma importação grande é um número administrável de execuções, em vez de uma execução por Finding. +* **Per-Finding send ceiling**, 1.000 por padrão. Um nó de saída configurado para enviar uma mensagem por Finding para de enviar ao atingir esse número em uma única execução, e registra uma omissão visível informando sobre quantos não enviou. Isso limita as linhas de entrega e as tarefas enfileiradas, algo que uma execução em blocos não limita mais por si só. + +Todos os três são configurações de implantação, documentadas em [Configuração](../configuration/). + +### Quanto tempo uma execução pode levar + +Uma execução registra um **heartbeat (pulsação)** após cada bloco. A detecção de travamento lê essa pulsação em vez do horário de início, de modo que uma varredura longa que ainda está progredindo nunca é confundida com um worker travado. + +Duas janelas se aplicam, ambas configuráveis: + +* Uma execução que fica 30 minutos sem pulsação é tratada como abandonada, marcada como erro, e seu lock é liberado. +* Uma execução é encerrada à força após seis horas, como proteção contra uma execução que nunca terminaria. + +## Retenção + +As execuções são mantidas por **180 dias** por padrão, junto com suas linhas por nó e sua proveniência de Finding. As entregas são mantidas por 180 dias separadamente. + +O produto informa isso em vez de deixar implícito: o detalhe de uma execução mostra a janela de retenção e a data em que aquela execução será excluída. Uma execução que ainda contém entregas é mantida até que essas sejam removidas. + +Ambas as janelas são configuráveis, e qualquer uma delas pode ser definida para manter os registros indefinidamente. Veja [Configuração](../configuration/#retention). + +## Executando uma regra manualmente + +Uma regra cujo gatilho é **Manual Run** é executada com a ação **Run** na lista de regras. Regras com outros gatilhos são executadas quando seu gatilho dispara. + +**Preview**, no editor, é a outra forma de executar um grafo. Ele executa o mecanismo real e depois reverte tudo, não registra nenhuma execução, e força a saída (egress) a simular. Use o preview enquanto constrói, e as execuções para ver o que realmente aconteceu. + +## Proveniência em um Achado + +As execuções respondem "o que esta regra fez?". A proveniência responde à pergunta oposta: "por que este Finding mudou?". + +Toda alteração feita por uma regra é registrada no Finding junto com a regra, a execução e o nó responsáveis, e aparece como uma linha do tempo no próprio Finding. As ações registradas são: + +| Ação | Significado | +|--------|---------| +| `created`, `updated`, `closed`, `reopened` | O ciclo de vida do Finding mudou. | +| `duplicate`, `status_change` | Seus sinalizadores de duplicidade ou status mudaram. | +| `notified` | Uma notificação foi enviada sobre ele. | +| `delivered` | Uma entrega de saída o cobriu. | + +Edições de campo registram o que mudou, incluindo o valor anterior e o valor posterior de cada campo. Valores muito longos são truncados no registro, de modo que a linha do tempo permanece um registro da alteração, e não uma segunda cópia do Finding. + +Notificações e entregas também são registradas aqui. Isso é proposital: uma regra que enviou uma mensagem, mas não alterou nenhum campo, de outra forma não deixaria nenhum rastro no Finding. + +A proveniência sobrevive à regra. Excluir uma regra ou uma execução mantém as entradas da linha do tempo e simplesmente as desvincula, de modo que o histórico não desaparece quando alguém faz uma limpeza. + +## Excluindo regras com histórico + +Uma regra que produziu entregas não pode ser excluída enquanto elas existirem. Exclua as entregas primeiro, ou mantenha a regra e a desative. Isso é intencional: as entregas guardam o registro do que foi realmente enviado para sistemas externos, e uma exclusão em cascata levaria consigo envios em andamento. diff --git a/docs/content/automation/rules_engine_2/runs.zh-hans.md b/docs/content/automation/rules_engine_2/runs.zh-hans.md new file mode 100644 index 0000000000..fda48ee0f4 --- /dev/null +++ b/docs/content/automation/rules_engine_2/runs.zh-hans.md @@ -0,0 +1,132 @@ +--- +title: 运行 +description: 规则如何执行、一次运行会记录哪些内容，以及级联如何被限制 +weight: 4 +audience: pro +aliases: +- /zh-hans/automation/rules_engine_v2/runs/ +--- + +注意：规则引擎 2.0 是 DefectDojo Pro 专属功能。 + +**运行**是一条规则的一次执行。无论成功还是失败，每次运行都会被记录，其中的每个节点也都会留下痕迹。**规则引擎 2.0 > 运行**页面会列出这些记录。 + +## 一次运行会记录哪些内容 + +| Field | Meaning | +|-------|---------| +| **规则** | 执行该操作的规则。 | +| **触发方式** | 触发此次运行的事件，例如 `finding.created`、`schedule` 或 `manual`。 | +| **触发人** | 在有人手动触发时，指按下"运行"的人，或保存了引发此次运行的发现项的人。对于按计划触发，以及诸如导入或没有用户的 API 调用等无人在场的变更，此字段为空。这与规则的所有者不同，所有者指的是此次运行**以谁的身份**执行。 | +| **状态** | `Running`、`Success` 或 `Error`。 | +| **开始时间**与**结束时间** | 运行发生的时间。只有在仍在运行时，结束时间才为空。 | +| **错误** | 若运行失败，导致其结束的错误。 | +| **统计信息** | 按节点统计的总数、级联事件以及延迟处理的工作。 | +| **深度** | 此次运行距离触发它的原始事件经过了多少次级联跳转。 | +| **源运行** | 对于级联触发的运行，指其所发出的事件触发了此次运行的那次运行。 | + +### 节点执行记录 + +在一次运行中，每个节点都会记录自己的一行数据： + +| Field | Meaning | +|-------|---------| +| **顺序** | 该节点在执行顺序中所处的位置。 | +| **节点** | 节点的 ID、类型，以及（如果设置了）标签。 | +| **状态** | 节点是执行完成还是抛出了错误。 | +| **输入项数** | 进入该节点的项目数量。 | +| **输出项数** | 离开该节点的项目数量，按输出端口分别统计，因此 If / Filter 节点会分别显示其 true 分支和 false 分支的数量。 | +| **摘要** | 该节点报告的各类计数，例如它更改了多少个发现项。 | +| **错误** | 若节点执行失败，其抛出的错误。 | + +当一条规则的执行结果不符合预期时，这份执行记录就是你需要查看的内容。如果一个 If / Filter 节点显示输入了 400 个项目，但 true 分支的输出为 0，那么无需猜测你就能知道条件设置有误。 + +## 执行模型 + +节点按拓扑顺序执行：只有当所有输入该节点的上游都执行完毕后，该节点才会执行。一个有多条输入边的节点会接收到所有上游输出拼接后的结果。没有任何上游输入的节点仍会执行，只是输入列表为空。 + +### 失败的运行不会造成任何更改 + +一次运行是原子性的。只要有任何节点抛出错误，此次运行对发现项所做的全部更改都会被回滚。 + +但执行记录不会随之回滚。节点记录行和 `Error` 状态是在此之后写入的，因此一次失败的运行能够准确告诉你是哪个节点出了问题，同时不会留下任何只完成一半的更改。这是查看"运行"页面时需要牢记的最重要的一条保证：出错的运行等同于什么都没做的运行。 + +出站操作也遵循相同的规则。投递记录会在此次运行的事务内被写入，并且只有在事务提交后才会真正发送，因此被回滚的运行不会发出任何内容。 + +### 同一时间每条规则只能有一次运行 + +一条规则同一时间只能有一次运行在进行中。如果同一条规则在仍在运行时被再次触发，第二次触发不会与其产生竞争，而是会等待并重试。 + +不同的规则会完全并发地运行，因此一条运行缓慢的规则永远不会拖慢其他规则。 + +如果一次运行由于某种原因被遗弃——例如执行它的工作进程被终止——它的锁会在一个停滞时间窗口（默认 30 分钟）之后被释放，从而避免该规则被永久卡住。一次运行在接近该时间窗口时会先自行停止并干净地回退，因此一次只是运行缓慢的运行绝不会与它自己的替代运行同时执行。 + +## 级联 + +一条更改了发现项的规则，恰好会产生另一条规则可以据以触发的事件。规则引擎 2.0 允许这种情况发生，因此 `A -> B -> C` 这样的链条是可行的，同时它通过两种独立的方式对此加以限制： + +* **深度。** 一个事件从引发它的变更开始，最多可以经过 **3** 次级联跳转。 +* **链成员关系。** 每个事件都携带其链条中已经经过的规则列表，同一条规则在同一条链中永远不会运行两次。因此，一条规则不能重新触发自身，两条规则之间也不会相互反复触发。 + +一次运行的**深度**和**源运行**字段可以帮助你沿着链条追溯到最初引发它的变更。**触发人**会沿着整条链条一直传递下去，因此由某人引发的一次级联，在每一跳都仍然可以归因到此人。 + +由正在运行的规则所做出*的*更改，会被归因到该规则自身的级联，而不会看起来像是全新的用户操作，因此一条在内部委派工作的规则不会使链条被人为拉长。 + +## 规模与限制 + +**一次运行没有数量上限。** 无论规则的作用范围匹配到多少内容，规则都会全部处理。一条在处理到第 N 个发现项时就悄悄停止的规则，是不值得信任的规则。 + +相反，一次运行会以**分块**的方式处理，默认每次处理 1,000 个发现项。内存中只保留当前这一块的数据，因此对一个非常大的范围进行扫描时，受限的是内存占用，而不是覆盖范围。唯一的例外是**预览**，它确实设有上限，并且在被截断时会在执行记录中说明这一点。 + +还有另外两个数值决定了工作是如何被划分的： + +* **每个事件的发现项数量**，默认值为 500。一次批量更改会被拆分到多个事件中，每个事件各自成为一次独立的运行。对于一次大规模导入而言，实际效果是产生数量可控的若干次运行，而不是每个发现项一次运行。 +* **每个发现项的发送上限**，默认值为 1,000。若某个出站节点被设置为每个发现项发送一条消息，那么在单次运行中达到此上限后就会停止，并记录一条可见的跳过说明，注明有多少发现项未被发送。这一限制约束了投递记录和排队任务的数量，而分块处理本身已不再对这些内容加以约束。 + +以上三项都是部署级设置，记录在[配置](../configuration/)中。 + +### 一次运行可以持续多长时间 + +一次运行在处理完每一块之后都会记录一次**心跳**。停滞检测读取的是这个心跳，而不是开始时间，因此一次仍在取得进展的长时间扫描，永远不会被误判为工作进程已崩溃。 + +有两个时间窗口适用，二者均可配置： + +* 一次运行如果 30 分钟内没有心跳，就会被视为已遗弃、标记为错误，并释放其锁。 +* 一次运行在六小时后会被直接终止，以防止出现永远无法结束的运行。 + +## 保留期限 + +默认情况下，运行记录会连同其各节点的记录行以及发现项溯源信息一起保留 **180 天**。投递记录则单独保留 180 天。 + +产品会明确告知这一点，而不是让它隐而不显：一次运行的详情页会显示保留期限，以及该运行将被删除的日期。仍然持有投递记录的运行，会一直保留到这些投递记录被清理为止。 + +这两个期限都可以配置，并且都可以设置为无限期保留记录。参见[配置](../configuration/#retention)。 + +## 手动运行规则 + +触发方式为**手动运行**的规则，可以通过规则列表中的**运行**操作来执行。其他触发方式的规则，会在其触发条件满足时自动运行。 + +编辑器中的**预览**是执行图的另一种方式。它会运行真实的引擎，然后回滚所有更改，不记录任何运行，并强制所有出站操作以模拟方式执行。在构建规则时使用预览，而要查看实际发生了什么，则查看运行记录。 + +## 发现项上的溯源信息 + +运行记录回答的是"这条规则做了什么？"，而溯源信息回答的是相反的问题："这个发现项为什么会发生变化？" + +规则所做的每一次更改，都会连同负责的规则、运行及节点一起被记录到对应的发现项上，并以时间线的形式呈现在该发现项本身上。所记录的操作类型有： + +| Action | Meaning | +|--------|---------| +| `created`、`updated`、`closed`、`reopened` | 发现项的生命周期状态发生了变化。 | +| `duplicate`、`status_change` | 其重复标记或状态标记发生了变化。 | +| `notified` | 已就此发出通知。 | +| `delivered` | 一次出站投递已覆盖此项。 | + +字段编辑会记录发生了什么变化，包括每个字段变更前后的值。过长的值会在记录中被截断，这样时间线始终是变更的记录，而不会变成发现项的第二份副本。 + +通知和投递也会记录在这里。这是刻意为之：否则，一条只发送了消息却没有更改任何字段的规则，将不会在发现项上留下任何痕迹。 + +溯源信息不依赖于规则而存在。删除一条规则或一次运行时，时间线条目会被保留，只是解除与其的关联，因此当有人进行清理时，历史记录不会消失。 + +## 删除带有历史记录的规则 + +一条已经产生过投递记录的规则，不能在其投递记录仍然存在的情况下被删除。请先删除这些投递记录，或者保留该规则并将其禁用。这是有意为之：投递记录保存着实际发送到外部系统的内容，而级联删除会连同正在进行中的发送一起被删除。 diff --git a/docs/content/connectors/_index.it.md b/docs/content/connectors/_index.it.md new file mode 100644 index 0000000000..5fbd36dcc7 --- /dev/null +++ b/docs/content/connectors/_index.it.md @@ -0,0 +1,17 @@ +--- +title: Connettori +description: Collegare DefectDojo ai propri scanner e sistemi di issue tracking +summary: '' +date: 2026-07-14 00:00:00+00:00 +lastmod: 2026-07-14 00:00:00+00:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +audience: pro +exclude_search: true +--- diff --git a/docs/content/connectors/_index.pt-br.md b/docs/content/connectors/_index.pt-br.md new file mode 100644 index 0000000000..0926f17324 --- /dev/null +++ b/docs/content/connectors/_index.pt-br.md @@ -0,0 +1,17 @@ +--- +title: Conectores +description: Conecte o DefectDojo aos seus scanners e rastreadores de issues +summary: '' +date: 2026-07-14 00:00:00+00:00 +lastmod: 2026-07-14 00:00:00+00:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +audience: pro +exclude_search: true +--- diff --git a/docs/content/connectors/_index.zh-hans.md b/docs/content/connectors/_index.zh-hans.md new file mode 100644 index 0000000000..45c8e463cf --- /dev/null +++ b/docs/content/connectors/_index.zh-hans.md @@ -0,0 +1,17 @@ +--- +title: 连接器 +description: 将 DefectDojo 与您的扫描工具和问题跟踪系统连接起来 +summary: '' +date: 2026-07-14 00:00:00+00:00 +lastmod: 2026-07-14 00:00:00+00:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +audience: pro +exclude_search: true +--- diff --git a/docs/content/connectors/about.it.md b/docs/content/connectors/about.it.md new file mode 100644 index 0000000000..fd06e696a7 --- /dev/null +++ b/docs/content/connectors/about.it.md @@ -0,0 +1,66 @@ +--- +title: Informazioni sui Connectors +description: Il punto di riferimento unificato per gli Upstream Connectors e i Downstream + Connectors nell'interfaccia Pro +summary: '' +date: 2026-07-14 00:00:00+00:00 +lastmod: 2026-07-14 00:00:00+00:00 +draft: false +weight: 1 +chapter: true +sidebar: + collapsed: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +pro-feature: true +--- + +Nota: i Connector sono una funzionalità esclusiva di DefectDojo Pro. + +**Connectors** è l'unico punto di riferimento nell'interfaccia di DefectDojo Pro per ogni strumento con cui DefectDojo comunica, in entrambe le direzioni. Unisce due funzionalità che in precedenza erano configurate in punti separati: + +* **Upstream Connectors** (in precedenza **API Connectors**) importano riscontri e inventario degli asset *in ingresso* dai tuoi scanner e strumenti di sicurezza. +* **Downstream Connectors** (in precedenza **Integrations**) inviano riscontri *in uscita* verso i tuoi sistemi di issue tracking e ticketing. + +Se pensi a DefectDojo come all'hub dei tuoi dati di sicurezza, gli Upstream Connectors sono il modo in cui i dati arrivano, mentre i Downstream Connectors sono il modo in cui il lavoro di remediation viene inviato all'esterno. + +## Dove trovare i Connectors + +Nella barra laterale dell'interfaccia Pro, apri il gruppo **Connectors** sotto l'intestazione **Import**: + +* **Connectors > Upstream Connectors** — sostituisce la vecchia voce **API Connectors** (in precedenza sotto Import). +* **Connectors > Downstream Connectors** — sostituisce la vecchia voce **Integrations** (in precedenza sotto Settings). Questa direzione è attualmente in **Beta**. + +I vecchi segnalibri e i deep link continuano a funzionare: gli URL legacy di **API Connectors** e **Integrations** reindirizzano automaticamente alle nuove pagine **Upstream Connectors** e **Downstream Connectors**. + +## Chi può vedere cosa + +* **Upstream Connectors** è visibile agli utenti con un ruolo globale (Global Role) di Reader o superiore. +* **Downstream Connectors** è visibile solo ai superuser ed è attualmente in **Beta** per le istanze DefectDojo Pro ospitate su Cloud. + +Il gruppo **Connectors** appare nella barra laterale se almeno una delle due pagine è visibile per te. + +## Le pagine Connectors + +Entrambe le direzioni condividono lo stesso layout rinnovato: + +* Ogni strumento viene mostrato come un **riquadro** a larghezza piena — logo a sinistra, nome dello strumento e una breve descrizione al centro, e un pulsante di azione a destra. +* Ogni sezione dispone di una **casella di ricerca** che filtra i riquadri in base al nome dello strumento man mano che digiti. + +Nella pagina **Upstream Connectors**: + +* **Configured Connectors** elenca i connector già configurati. Ogni riquadro mostra un riepilogo dello stato operativo (stato di salute, ultima operazione e conteggio totale / dei record mappati) e un menu **Manage Configuration** con le azioni **Manage Records & Operations**, **Edit Configuration** e **Delete Configuration**. +* **Available Connectors** elenca gli strumenti supportati non ancora configurati, ciascuno con un pulsante **Add Configuration**. +* Un filtro nell'intestazione della pagina restringe entrambe le sezioni per tipo di connector: **All**, **Asset** (oppure **Product**, a seconda del vocabolario della tua istanza) per i connector che importano l'inventario degli asset, e **Finding** per i connector che importano dati di vulnerabilità. + +Nella pagina **Downstream Connectors**: + +* **Available Integrations** elenca ogni sistema di issue tracking supportato. I riquadri delle integrazioni che hai configurato mostrano un conteggio delle Integration Instances esistenti. + +## Prossimi passi + +* Leggi [Informazioni sugli Upstream Connectors](/connectors/upstream/about/) e [aggiungi il tuo primo Upstream Connector](/connectors/upstream/add_edit/) per iniziare a importare automaticamente i riscontri. +* Leggi la [guida ai Downstream Connectors](/connectors/downstream/about/) per inviare i riscontri ai tuoi sistemi di issue tracking. diff --git a/docs/content/connectors/about.pt-br.md b/docs/content/connectors/about.pt-br.md new file mode 100644 index 0000000000..280d895495 --- /dev/null +++ b/docs/content/connectors/about.pt-br.md @@ -0,0 +1,66 @@ +--- +title: Sobre os Conectores +description: O local unificado para Conectores Upstream e Downstream na interface + do Pro +summary: '' +date: 2026-07-14 00:00:00+00:00 +lastmod: 2026-07-14 00:00:00+00:00 +draft: false +weight: 1 +chapter: true +sidebar: + collapsed: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +pro-feature: true +--- + +Observação: Conectores são um recurso exclusivo do DefectDojo Pro. + +**Conectores** é o local único na interface do DefectDojo Pro para todas as ferramentas com as quais o DefectDojo se comunica, em ambas as direções. Ele reúne dois recursos que antes eram configurados em locais separados: + +* **Conectores Upstream** (antigos **Conectores de API**) trazem achados e inventário de ativos *para dentro*, a partir dos seus scanners e ferramentas de segurança. +* **Conectores Downstream** (antigas **Integrações**) enviam achados *para fora*, para os seus sistemas de rastreamento de problemas e emissão de tickets. + +Se você pensar no DefectDojo como o hub dos seus dados de segurança, os Conectores Upstream são a forma como os dados chegam, e os Conectores Downstream são a forma como o trabalho de remediação sai. + +## Onde encontrar os Conectores + +Na barra lateral da interface do Pro, abra o grupo **Connectors** no cabeçalho **Import**: + +* **Connectors > Upstream Connectors** — substitui a antiga entrada **API Connectors** (anteriormente em Import). +* **Connectors > Downstream Connectors** — substitui a antiga entrada **Integrations** (anteriormente em Settings). Esta direção está atualmente em **Beta**. + +Os favoritos e links diretos antigos continuam funcionando: as URLs legadas de **API Connectors** e **Integrations** redirecionam automaticamente para as novas páginas **Upstream Connectors** e **Downstream Connectors**. + +## Quem pode ver o quê + +* **Upstream Connectors** fica visível para usuários com Função Global de Reader ou superior. +* **Downstream Connectors** fica visível apenas para superusuários, e atualmente está em **Beta** para instâncias do DefectDojo Pro hospedadas na Cloud. + +O grupo **Connectors** aparece na barra lateral se pelo menos uma das duas páginas estiver visível para você. + +## As páginas de Connectors + +As duas direções compartilham o mesmo layout renovado: + +* Cada ferramenta é exibida como um **quadro** (tile) em largura total — logotipo à esquerda, o nome da ferramenta e uma breve descrição no centro, e um botão de ação à direita. +* Cada seção tem uma **caixa de busca** que filtra os quadros por nome da ferramenta enquanto você digita. + +Na página **Upstream Connectors**: + +* **Configured Connectors** lista os conectores que você já configurou. Cada quadro mostra um resumo de integridade operacional (status de integridade, última operação e contagens totais/mapeadas de registros) e um menu **Manage Configuration** com as ações **Manage Records & Operations**, **Edit Configuration** e **Delete Configuration**. +* **Available Connectors** lista as ferramentas suportadas que você ainda não configurou, cada uma com um botão **Add Configuration**. +* Um filtro no cabeçalho da página restringe ambas as seções por tipo de conector: **All**, **Asset** (ou **Product**, dependendo do vocabulário da sua instância) para conectores que importam inventário de ativos, e **Finding** para conectores que importam dados de vulnerabilidade. + +Na página **Downstream Connectors**: + +* **Available Integrations** lista todos os sistemas de rastreamento de problemas suportados. Os quadros das integrações já configuradas mostram uma contagem das Integration Instances existentes. + +## Próximos passos + +* Leia [Sobre os Conectores Upstream](/connectors/upstream/about/) e [adicione seu primeiro Conector Upstream](/connectors/upstream/add_edit/) para começar a importar achados automaticamente. +* Leia o [guia de Conectores Downstream](/connectors/downstream/about/) para enviar achados aos seus sistemas de rastreamento de problemas. diff --git a/docs/content/connectors/about.zh-hans.md b/docs/content/connectors/about.zh-hans.md new file mode 100644 index 0000000000..ee1e62c6dc --- /dev/null +++ b/docs/content/connectors/about.zh-hans.md @@ -0,0 +1,65 @@ +--- +title: 关于连接器 +description: Pro UI 中上游连接器和下游连接器的统一入口 +summary: '' +date: 2026-07-14 00:00:00+00:00 +lastmod: 2026-07-14 00:00:00+00:00 +draft: false +weight: 1 +chapter: true +sidebar: + collapsed: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +pro-feature: true +--- + +注意：连接器是 DefectDojo Pro 专属功能。 + +**连接器（Connectors）** 是 DefectDojo Pro UI 中的统一入口，用于管理 DefectDojo 与之通信的所有工具（无论数据流向哪个方向）。它合并了此前在不同位置分别配置的两项功能： + +* **上游连接器（Upstream Connectors）**（原名 **API Connectors**）从您的扫描器和安全工具中拉取发现项和资产清单。 +* **下游连接器（Downstream Connectors）**（原名 **Integrations**）将发现项推送到您的问题跟踪系统和工单系统。 + +如果将 DefectDojo 视为您安全数据的枢纽，那么上游连接器就是数据流入的方式，下游连接器则是修复工作流出的方式。 + +## 在哪里找到连接器 + +在 Pro UI 侧边栏中，展开 **Import（导入）** 分组下的 **Connectors（连接器）** 分组： + +* **Connectors > Upstream Connectors（连接器 > 上游连接器）**——取代了原来的 **API Connectors** 条目（此前位于 Import 下）。 +* **Connectors > Downstream Connectors（连接器 > 下游连接器）**——取代了原来的 **Integrations** 条目（此前位于 Settings 下）。该方向目前处于 **Beta** 阶段。 + +旧的书签和深层链接仍然有效：原有的 **API Connectors** 和 **Integrations** 网址会自动重定向到新的 **Upstream Connectors** 和 **Downstream Connectors** 页面。 + +## 谁可以看到哪些内容 + +* **上游连接器** 对全局角色为 Reader 或更高的用户可见。 +* **下游连接器** 仅超级用户可见，目前针对云托管的 DefectDojo Pro 实例处于 **Beta** 阶段。 + +只要这两个页面中至少有一个对您可见，侧边栏中就会显示 **Connectors（连接器）** 分组。 + +## 连接器页面 + +两个方向共享同一套全新布局： + +* 每个工具都以全宽 **磁贴（tile）** 的形式显示——左侧是徽标，中间是工具名称和简短描述，右侧是操作按钮。 +* 每个部分都有一个 **搜索框**，可在您输入时按工具名称筛选磁贴。 + +在 **Upstream Connectors（上游连接器）** 页面上： + +* **Configured Connectors（已配置的连接器）** 列出您已经设置好的连接器。每个磁贴都会显示运行状况摘要（健康状态、最近一次操作，以及记录总数/已映射数量），并提供一个 **Manage Configuration（管理配置）** 菜单，其中包含 **Manage Records & Operations（管理记录和操作）**、**Edit Configuration（编辑配置）** 和 **Delete Configuration（删除配置）** 操作。 +* **Available Connectors（可用连接器）** 列出您尚未配置的受支持工具，每个工具都带有 **Add Configuration（添加配置）** 按钮。 +* 页面顶部的筛选器可按连接器类型缩小两个部分的范围：**All（全部）**、**Asset（资产，或 Product，具体取决于您实例的术语设置）** 用于导入资产清单的连接器，以及 **Finding（发现项）** 用于导入漏洞数据的连接器。 + +在 **Downstream Connectors（下游连接器）** 页面上： + +* **Available Integrations（可用集成）** 列出所有受支持的问题跟踪系统。已配置集成的磁贴会显示现有 Integration Instances（集成实例）的数量。 + +## 后续步骤 + +* 阅读[关于上游连接器](/connectors/upstream/about/)并[添加您的第一个上游连接器](/connectors/upstream/add_edit/)，开始自动导入发现项。 +* 阅读[下游连接器指南](/connectors/downstream/about/)，将发现项推送到您的问题跟踪系统。 diff --git a/docs/content/connectors/downstream/PRO__jira_guide.it.md b/docs/content/connectors/downstream/PRO__jira_guide.it.md new file mode 100644 index 0000000000..fbdbce5149 --- /dev/null +++ b/docs/content/connectors/downstream/PRO__jira_guide.it.md @@ -0,0 +1,786 @@ +--- +title: Jira (Legacy) +description: Lavorare con l'integrazione Jira +weight: 1 +audience: pro +aliases: +- /it/issue_tracking/jira/pro__jira_guide/ +- /it/en/share_your_findings/jira_guide +--- + +> **Questa pagina documenta l'integrazione Jira legacy.** L'integrazione Jira per prodotto qui descritta è stata sostituita dal **[Connettore downstream Jira](/connectors/downstream/about/)**, disponibile su tutte le istanze di DefectDojo Pro e rappresenta il metodo consigliato per inviare i Riscontri a Jira. Nella barra laterale di Pro, **Connetti > Jira** mostra un badge `LEGACY` proprio per questo motivo — vedere [Badge dei menu](/navigation/pro__menu_badges/). +> +> **Se stai configurando Jira per la prima volta, inizia dal [Connettore downstream](/connectors/downstream/about/) invece che da questa guida.** +> +> **Stai già usando l'integrazione legacy?** DefectDojo Pro include una migrazione integrata che sposta la tua configurazione Jira classica esistente sui Connettori downstream, inclusi i ticket già inviati — vedere [Migrazione al Connettore downstream Jira](#migrating-to-the-jira-downstream-connector) più sotto. +> +> L'integrazione legacy continua a funzionare, e questa guida resta valida per essa. + +L'integrazione Jira di DefectDojo può essere usata per inviare i dati dei Riscontri a uno o più Spazi Jira. Così facendo, puoi integrare DefectDojo nel tuo normale flusso di lavoro di sviluppo. Ecco alcuni esempi di come questo può funzionare: + +* Il team AppSec può inviare selettivamente i Riscontri a uno Spazio Jira usato dagli sviluppatori, in modo che la correzione dei problemi possa essere opportunamente prioritizzata insieme al normale sviluppo. Gli sviluppatori su questa bacheca non hanno bisogno di accedere a DefectDojo - possono tenere tutto il loro lavoro in un unico posto. +* DefectDojo può inviare TUTTI i Riscontri a uno Spazio Jira bidirezionale usato dal team AppSec, il che consente loro di suddividere la convalida dei problemi. Questa bacheca resta sincronizzata con DefectDojo e permette flussi di lavoro di correzione complessi. +* DefectDojo può inviare selettivamente i Riscontri da singoli Prodotti e/o Engagement a Spazi Jira separati, per mantenere ogni cosa nel proprio contesto. + +## Migrazione al Connettore downstream Jira + +DefectDojo Pro può convertire per te una configurazione Jira classica esistente in una configurazione del Connettore downstream, invece di farti ricostruire tutto manualmente. + +**Dove trovarla:** vai su **Connetti \> Downstream** per aprire la pagina **Connettori downstream**, e usa la scheda **Migrazione classica di Jira**. Fai clic su **Migra da Jira classico**, quindi conferma. + +La scheda compare solo se esiste una configurazione Jira classica da migrare, oppure un'esecuzione precedente da segnalare — quindi un'istanza che non ha mai usato Jira classico non la vedrà. Una volta completata la migrazione di tutto, la scheda resta visibile ma il pulsante è disabilitato, perché non c'è più nulla da fare. + +Per eseguire la migrazione sono necessari **permessi globali di livello Maintainer** (nello specifico, il permesso di modificare le integrazioni), e deve essere avviata da una sessione del browser con accesso effettuato — non può essere eseguita con un token API. + +### Cosa succede ai ticket già inviati + +**I tuoi ticket Jira esistenti vengono conservati e ricollegati — non restano orfani, e il connettore non ne apre di duplicati.** Ogni Riscontro che Jira classico aveva già inviato mantiene il proprio ticket, e il connettore prende in carico l'aggiornamento dello stesso ticket. I collegamenti sui Gruppi di riscontri vengono trasferiti allo stesso modo. + +L'unica eccezione sono gli **Epic di Engagement**. Il Connettore downstream non ha alcun concetto di Epic, quindi i ticket Epic vengono segnalati negli avvisi della migrazione e lasciati invariati. + +### Cosa viene migrato + +* La connessione della tua **istanza** Jira — URL e credenziali — diventa un'istanza di integrazione Connettore downstream, mantenendo il proprio nome. +* Le **mappature di gravità** e le **mappature di stato** (le chiavi di transizione di apertura e chiusura) vengono trasferite. +* Ogni configurazione di **Progetto Jira** diventa una mappatura del tracker dei ticket, mantenendo la chiave di progetto e il tipo di ticket, e resta assegnata allo stesso Prodotto o Engagement. +* **Invia tutti i ticket** viene preservato: i progetti che lo avevano abilitato continuano a inviare automaticamente. +* **Campi personalizzati**, **campi di transizione di chiusura/riapertura**, **componente**, **assegnatario predefinito** ed **etichette** vengono convertiti in mappature di campo. Dove usavi *Aggiungi ID vulnerabilità come etichetta Jira*, questo diventa anche una mappatura di etichetta. +* Una directory di **modello di ticket personalizzato** diventa un modello di ticket. I modelli standard non vengono copiati, perché il connettore include già i propri equivalenti. + +### Cosa non viene trasferito + +Questi elementi vengono segnalati come avvisi nell'esecuzione della migrazione — non la bloccano. Cerca l'elenco *"cose che il connettore non può trasferire"* nei risultati. + +* **Sincronizzazione inversa da Jira a DefectDojo.** Questo è il punto importante. Il Connettore downstream non sincronizza le modifiche *in senso inverso* da Jira, quindi le mappature di risoluzione che applicano Rischio accettato o Falso positivo a partire da una risoluzione Jira non vengono migrate. **Se ti affidi alla sincronizzazione inversa, lascia configurata l'istanza Jira classica** — la migrazione non la rimuove. +* **Mappatura Epic di Engagement** — il connettore non ha alcun concetto di Epic. +* **Invia note**, **commenti di notifica SLA** e **commenti di scadenza dell'accettazione del rischio** — il connettore non li pubblica su Jira. +* I campi personalizzati chiamati `summary`, `description`, `project`, `issuetype` o `status` — questi sono riservati dal connettore, e una mappatura di campo che ne usa uno viene ignorata. +* I valori dei campi personalizzati più lunghi di 512 caratteri — vengono ignorati anziché troncati. +* Un Progetto Jira non associato né a un Prodotto né a un Engagement non produce alcuna assegnazione. + +### Cosa succede all'integrazione classica in seguito + +**Niente viene inviato due volte.** Per ogni progetto che migra, la migrazione disattiva il progetto Jira classico corrispondente, quindi da quel momento in poi invia solo il connettore. Non è necessario disabilitare nulla manualmente. + +La tua configurazione classica viene **conservata, non eliminata** — l'istanza, il progetto e i record dei ticket restano tutti presenti, con solo le impostazioni di invio disattivate. Questo è intenzionale: è ciò che rende la modifica reversibile, ed è ciò che mantiene funzionante la sincronizzazione inversa se ne hai bisogno. + +**Per tornare indietro**, riattiva le impostazioni del progetto Jira classico e rimuovi la configurazione del connettore creata dalla migrazione. Non esiste un ripristino con un solo clic. + +**Rieseguirla è sicuro.** La migrazione registra ciò che ha già convertito e lo salta in una seconda esecuzione, quindi nulla viene duplicato. Se un progetto o un'istanza fallisce, il resto viene comunque migrato — un progetto non riuscito viene lasciato in esecuzione sull'integrazione classica invece di essere disattivato, così continua a funzionare mentre indaghi. + +### Durante l'esecuzione + +La migrazione viene eseguita in background e segnala i progressi man mano che procede. Al termine ottieni un riepilogo — quanti connettori, mappature, assegnazioni, modelli e collegamenti ai ticket sono stati creati, quanti progetti classici sono stati disattivati e cosa è stato ignorato — insieme agli avvisi descritti sopra. Viene eseguita una sola migrazione alla volta. + +# Configurazione di Jira + +La configurazione di Jira richiede i seguenti passaggi: +1. Abilita l'integrazione Jira in System Settings. Finché non lo fai, il resto delle impostazioni Jira resta nascosto in tutto DefectDojo. +2. Connetti un'Istanza Jira, con un nome utente/password oppure con un token API. È possibile collegare più istanze. +3. Aggiungi quell'Istanza Jira a uno o più Prodotti o Engagement all'interno di DefectDojo. +4. Se desideri usare la sincronizzazione bidirezionale, crea un Webhook Jira che invierà gli aggiornamenti a DefectDojo. + +## Passaggio 1: abilitare l'integrazione Jira in System Settings + +L'integrazione Jira è disattivata per impostazione predefinita, e finché è disattivata DefectDojo nasconde ogni altro controllo Jira nell'interfaccia. Questa è la prima cosa da configurare: nessuno dei passaggi seguenti è disponibile finché non viene abilitata. + +Finché l'integrazione è disabilitata, non è presente alcuna voce **Jira Instances** nella barra laterale, quindi non c'è modo di aggiungere un'Istanza Jira: + +![immagine](images/jira-menu-hidden-pro.png) + +### Abilitare l'integrazione + +1. Vai su **Settings \> System \> System Settings** dalla barra laterale di DefectDojo. Sulle istanze che usano ancora il layout di menu precedente, questa voce si trova in un gruppo denominato in base al tuo pacchetto di licenza — **Pro Settings** oppure **Enterprise Settings**. Vedere [Il menu delle impostazioni](/navigation/pro__settings_menu/). +​ +2. Nella sezione **Jira Integration Settings**, seleziona **Enable Jira Integration**. +​ +3. Fai clic su **Invia**. **Jira Instances** compare immediatamente nella barra laterale, senza dover ricaricare la pagina: + +![immagine](images/jira-enable-system-settings-pro.png) + +### Cosa controlla questa impostazione + +Abilitare **Enable Jira Integration** è ciò che fa comparire il resto dell'interfaccia Jira. Attivandola ottieni: + +* il menu **Jira Instances**, dove le Istanze Jira vengono aggiunte e modificate +* la pagina **Jira Project Settings** nel menu ⚙️ dell'Asset, e le impostazioni Jira sugli Engagement +* le azioni **Invia a Jira** su Riscontri e Gruppi di riscontri, i campi Jira nei moduli del Riscontro e di modifica collettiva, e le colonne Jira negli elenchi di Asset, Engagement, Riscontro e Gruppo di riscontri (incluse le esportazioni CSV) + +L'impostazione regola l'integrazione anche al di fuori dell'interfaccia: finché è disattivata, DefectDojo non invierà i Riscontri a Jira (incluse le richieste `push_to_jira` inviate tramite l'API), e i webhook Jira in arrivo vengono ignorati. + +I restanti campi Jira in **Jira Integration Settings** (**Add Vulnerability ID as Jira Label**, **Enable Jira Web Hook**, **Disable Jira Web Hook Secret**, **Jira Web Hook Secret**, **Jira Minimum Severity**) restano visibili sia che l'integrazione sia attiva sia che sia disattivata, ma non hanno alcun effetto finché non viene abilitata. + +## Passaggio 2: connettere un'Istanza Jira + +Con l'integrazione abilitata, connettere un'Istanza Jira è il passaggio successivo nella configurazione dell'integrazione Jira di DefectDojo. Nota che Jira Service Management non è attualmente supportato. + +#### Informazioni richieste da Jira + +Atlassian utilizza metodi di autenticazione diversi tra Jira Cloud e Jira Data Center. + +per **Jira Cloud** ti servirà: +* un URL Jira, ad es. https://yourcompany.atlassian.net/ +* un account con i permessi per creare e aggiornare ticket nella tua istanza Jira. Può trattarsi di: + * Una combinazione standard di **nome utente / password** + * Una combinazione di **nome utente / token API** + +per **Jira Data Center (o Server)** ti servirà: +* un URL Jira, ad es. https://jira.yourcompany.com +* un account con i permessi per creare e aggiornare ticket nella tua istanza Jira. Può trattarsi di: + * Una combinazione standard di **nome utente / password** + * Una combinazione di **indirizzo email / Personal Access Token** + +Facoltativamente, puoi mappare: +* Transizioni Jira per attivare la riapertura e la chiusura dei Riscontri +* Risoluzioni Jira che possono applicare gli stati Rischio accettato e Falso positivo ai Riscontri (facoltativo) + +Una singola connessione a un'Istanza Jira può gestire più Spazi Jira, purché l'account / token Jira usato da DefectDojo abbia il permesso di creare ticket nello Spazio Jira associato. + +### Aggiungere un'Istanza Jira + +1. Assicurati che **Enable Jira Integration** sia selezionata in System Settings, come descritto nel [Passaggio 1](#step-1-enable-the-jira-integration-in-system-settings). Il menu **Jira Instances** non compare nella barra laterale finché non lo è. + +2. Vai alla pagina **Enterprise Settings \> Jira Instances \> + New Jira Instance** dalla barra laterale di DefectDojo. + +![immagine](images/jira-instance-beta.png) + +3. Scegli un **Configuration Name** per questa Istanza Jira da usare in DefectDojo. Questo nome è semplicemente un'etichetta per la connessione dell'Istanza in DefectDojo, e non deve necessariamente essere collegato ai dati Jira. + +4. Seleziona l'URL dell'istanza Jira della tua azienda, probabilmente simile a `https://**yourcompany**.atlassian.net` se stai usando un'installazione Jira Cloud. + +5. Inserisci un metodo di autenticazione appropriato nei campi Username / Password per Jira: + * Per l'**autenticazione standard Jira con nome utente / password**, inserisci in questi campi uno Username Jira e la Password corrispondente. + * Per l'autenticazione con il **token API dell'utente (Jira Cloud)**, inserisci lo Username con il corrispondente **token API** nel campo password. + * Per l'autenticazione con un **Personal Access Token Jira (detto anche PAT, usato solo in Jira Data Center e Jira Server)**, inserisci il PAT nel campo password. Lo Username non viene usato per l'autenticazione con un PAT Jira, ma il campo è comunque obbligatorio in questo modulo, quindi puoi usare qui un valore segnaposto per identificare il tuo PAT. + +Nota che l'utente associato a questa connessione deve avere il permesso di creare ticket e accedere ai dati nella tua istanza Jira. + +6. Dovrai fornire i valori per un Epic Name ID, un Re-open Transition ID e un Close Transition ID. Questi valori possono essere modificati in seguito. Mentre sei connesso a Jira, puoi ottenere questi valori dai seguenti URL: +- **Epic Name ID**: visita `https:///rest/api/2/field` e cerca Epic Name. Copia il numero contenuto in `number` e incollalo qui. Se non hai un Epic Name ID associato al tuo Spazio in Jira (ad esempio perché usi uno Spazio a gestione di team), inserisci 0 in questo campo. +- **Re-open Transition ID**: visita `https:///rest/api/latest/issue//transitions?expand-transitions.fields` per trovare l'ID della tua istanza Jira. Incollalo nel campo Reopen Transition ID. +- **Close Transition ID**: visita `https:///rest/api/latest/issue//transitions?expand-transitions.fields` per trovare l'ID della tua istanza Jira. Incollalo nel campo Close Transition ID. + +7. Seleziona il tipo di ticket predefinito con cui creare i ticket in Jira. Le opzioni sono **Bug, Task, Story** ed **Epic** (che sono tipi di ticket Jira standard), oltre a **Spike** e **Security**, che sono tipi di ticket personalizzati. Se vuoi usare un tipo di ticket diverso, contatta [support@defectdojo.com](mailto:support@defectdojo.com) per assistenza. + +8. Seleziona il tuo Modello di ticket, che determinerà la Descrizione del ticket quando i ticket vengono creati in Jira. + +I due tipi sono: +- **Jira\_full**, che include tutte le informazioni del Riscontro nei ticket Jira +- **Jira\_limited**, che include una quantità minore di informazioni e metadati del Riscontro. + +Se lasci questo campo vuoto, verrà usato per impostazione predefinita **Jira\_full.** Se hai bisogno di un tipo diverso di modello, contatta [support@defectdojo.com](mailto:support@defectdojo.com). + +9. Se lo desideri, inserisci il nome di una Risoluzione Jira che cambierà lo stato di un Riscontro in Rischio accettato o in Falso positivo (quando la Risoluzione viene attivata sul ticket). + +Da qui puoi inviare il modulo. Se lo desideri, puoi personalizzare ulteriormente la tua integrazione Jira in Optional Fields. Facendo clic su questo pulsante potrai applicare testo generico ai ticket Jira o modificare le mappature di gravità di Jira. + +## Passaggio 3: connettere un Prodotto o un Engagement a Jira + +Ogni Prodotto o Engagement in DefectDojo ha le proprie impostazioni che regolano il modo in cui i Riscontri vengono convertiti in ticket JIRA. Da qui puoi decidere lo Spazio Jira associato e impostare il comportamento predefinito per la creazione di ticket, Epic, etichette e altri metadati JIRA. + +### Aggiungere Jira a un Prodotto + +Puoi trovare questa pagina facendo clic sul menu a forma di ingranaggio di un Prodotto ⚙️ e aprendo la pagina **Jira Project Settings**. + +![immagine](images/jira-project-settings.png) + +#### Istanza Jira + +Se hai configurato più istanze di Jira, per prodotti o team separati all'interno della tua organizzazione, puoi indicare in quale Spazio Jira vuoi che DefectDojo crei i ticket. Seleziona uno Spazio dal menu a tendina. + +Se questo menu non elenca alcuna istanza Jira, verifica che quegli Spazi siano collegati nella tua Configurazione Jira globale per DefectDojo, su yourcompany.defectdojo.com/jira. + +#### Chiave del progetto + +Questa è la chiave dello Spazio che vuoi usare con DefectDojo. La Space Key di un determinato Spazio si trova nell'URL. (In precedenza era chiamata **Jira Project Key**, ma da settembre 2025 in Jira viene chiamata **Space Key**). + +![immagine](images/Add_a_Connected_Jira_Project_to_a_Product_3.png) + +#### Nome del tipo di ticket Epic + +Il nome del tipo di ticket Epic in Jira. Per impostazione predefinita è "Epic", ma può essere modificato se la tua istanza Jira usa un nome diverso. + +#### Modello di ticket + +Qui puoi determinare quanti metadati di DefectDojo vuoi inviare a Jira. Seleziona una delle due opzioni: + +* **jira\_full**: i ticket terranno traccia di tutti i parametri di DefectDojo, ovvero una Descrizione completa, CVE, Gravità, ecc. Utile se hai bisogno del contesto completo del Riscontro in Jira (ad esempio, se qualcuno che lavora su questo ticket non ha accesso a DefectDojo). + +Ecco un esempio di ticket **jira\_full**: +​ +![immagine](images/Add_a_Connected_Jira_Project_to_a_Product_4.png) + +* **Jira\_limited:** i ticket terranno traccia solo del link a DefectDojo, dei link a Prodotto/Engagement/Test, e dei campi Reporter ed Environment. Tutti gli altri campi vengono tracciati solo in DefectDojo. Utile se non hai bisogno del contesto completo del Riscontro in Jira (ad esempio, se qualcuno che lavora su questo ticket opera principalmente in DefectDojo e non ha bisogno di avere il quadro completo anche in JIRA.) + +​Ecco un esempio di ticket **jira\_limited**: + +![immagine](images/Add_a_Connected_Jira_Project_to_a_Product_5.png) + +#### Componente + +Se gestisci il tuo Spazio Jira usando i Componenti, qui puoi assegnare il Componente appropriato per DefectDojo. Per assegnare più di un Componente, inserisci un elenco separato da virgole (ad esempio, `Security, DevSecOps`); ogni valore viene inviato a Jira come componente separato. + +#### Campi personalizzati + +Se non hai bisogno di usare Campi personalizzati con i ticket di DefectDojo, puoi lasciare questo campo come 'null'. + +Tuttavia, se le impostazioni del tuo Spazio Jira **richiedono** l'uso di Campi personalizzati sui nuovi ticket, dovrai impostare queste mappature come valori fissi. + +Nota che DefectDojo non può inviare come Campi personalizzati alcun metadato specifico del ticket, ma solo un valore predefinito. Questa sezione dovrebbe essere configurata solo se il tuo Spazio Jira **richiede che questi Campi personalizzati esistano** in ogni ticket del tuo Spazio. + +Segui **[questa guida](#custom-fields-in-jira)** per iniziare a lavorare con i Campi personalizzati. + +#### Campi di transizione di chiusura / riapertura + +Alcuni workflow Jira **richiedono** che determinati campi siano impostati come parte di una transizione — ad esempio, un workflow che rifiuta di chiudere un ticket a meno che non vengano forniti un campo Risoluzione e un campo di giustificazione nella schermata di chiusura. L'impostazione Campi personalizzati descritta sopra si applica solo quando un ticket viene *creato*, quindi non può soddisfare questi workflow. + +Senza queste impostazioni, DefectDojo invia le transizioni di chiusura / riapertura senza alcun campo. Un workflow che richiede dei campi rifiuterà quella transizione, e il Riscontro e il ticket Jira si disallineeranno: il Riscontro risulta Mitigato in DefectDojo mentre il ticket resta aperto in Jira. + +Le impostazioni **Campi di transizione di chiusura** e **Campi di transizione di riapertura** accettano un oggetto JSON che viene inviato come payload `fields` della chiamata di transizione di chiusura / riapertura. Ad esempio, per chiudere i ticket con una Risoluzione *Won't Fix* più un valore di giustificazione: + +```json +{ + "resolution": {"name": "Won't Fix"}, + "customfield_10200": "Risk accepted by security team #report-false-positive" +} +``` + +Lascia queste impostazioni come 'null' se il tuo workflow Jira non richiede campi sulle transizioni. + +**Di quali campi hai bisogno?** + +* Chiedi al tuo amministratore Jira quali campi sono presenti nelle **schermate di transizione** di chiusura / riapertura, e quali di essi sono imposti da un validatore. Il JSON configurato deve soddisfare **ogni** campo obbligatorio: se manca dal payload anche un solo campo obbligatorio, Jira rifiuta l'intera transizione e non imposta nulla — fornire solo alcuni dei campi obbligatori non è sufficiente. +* Al contrario, i campi devono essere presenti **nella schermata di transizione** per poter essere inviati: Jira rifiuta le transizioni che tentano di impostare campi non presenti nella schermata di quella transizione. +* Sui workflow creati con l'editor di workflow attuale di Jira Cloud, Jira compila automaticamente la Risoluzione predefinita del sito quando un ticket passa a uno stato della categoria "completato". Quindi, una Risoluzione obbligatoria da sola non bloccherà lì una transizione semplice, e l'uso pratico di `"resolution"` in questo payload è scegliere un valore *significativo* (ad esempio *False Positive*) invece di quello predefinito del sito. I workflow creati con l'editor classico, o con app di validazione del marketplace, possono comunque richiedere obbligatoriamente la Risoluzione. +* Le transizioni di riapertura in genere azzerano la Risoluzione tramite il workflow stesso, quindi **Campi di transizione di riapertura** di solito richiede solo i campi personalizzati richiesti dal tuo workflow. + +**Note:** + +* Lo stesso JSON viene inviato per *ogni* transizione di chiusura (o riapertura) per il Prodotto o l'Engagement — i valori sono statici e non variano per singolo Riscontro. Se hai bisogno di campi diversi in base all'esito (ad esempio, una Risoluzione diversa per i Riscontri Falso positivo rispetto a quelli corretti), usa il DefectDojo Pro Jira Integrator, che supporta mappature di campo per transizione in base allo stato. +* I valori usano lo stesso formato della REST API di Jira: stringhe per i campi di testo, `{"name": ...}` per le risoluzioni, `[{"name": ...}]` per i campi a selezione multipla, e così via. +* Se le transizioni sono state rifiutate mentre queste impostazioni erano mancanti o incomplete, correggere le impostazioni ripara il disallineamento: il successivo invio di stato per il Riscontro ritenta la transizione con i campi configurati. +* Entrambe le impostazioni sono disponibili anche sull'endpoint REST `/api/v2/jira_projects/` (`close_transition_fields` / `reopen_transition_fields`), quindi possono essere gestite tramite l'API. +* Questi campi vengono applicati anche quando DefectDojo chiude un ticket perché il relativo Riscontro è stato **eliminato** — i valori vengono acquisiti nel momento in cui la chiusura viene messa in coda. + +#### Etichette Jira + +Seleziona le etichette pertinenti con cui vuoi che il ticket venga creato in Jira, ad es. **DefectDojo**, **YourProductName..** + +![immagine](images/Add_a_Connected_Jira_Project_to_a_Product_6.png) + +#### Assegnatario predefinito + +Il nome dell'assegnatario predefinito in Jira. Se lasciato vuoto, DefectDojo seguirà il comportamento predefinito del tuo Spazio Jira durante la creazione dei ticket. + +### Jira Project Settings + +#### Abilitato + +Questo interruttore controlla se DefectDojo invia i Riscontri a Jira per questo Prodotto. Disabilitarlo non eliminerà né modificherà i ticket Jira esistenti creati da DefectDojo, ma impedirà ulteriori aggiornamenti o la creazione di nuovi ticket. + +Le integrazioni Jira possono essere rimosse dalla tua istanza solo se non sono stati creati ticket correlati. Se sono stati creati dei ticket, non è possibile rimuovere completamente un'Istanza Jira da DefectDojo. + +#### Aggiungere l'ID vulnerabilità come etichetta Jira + +Questo ti consente di aggiungere automaticamente i dati dell'ID vulnerabilità come Etichetta Jira. Gli ID vulnerabilità vengono aggiunti ai Riscontri dai singoli strumenti di sicurezza, e possono essere ID Common Vulnerabilities and Exposures (CVE) oppure un formato diverso, specifico dello strumento che segnala il Riscontro. + +#### Invia tutti i ticket + +Se selezionata, DefectDojo invierà automaticamente a Jira come ticket tutti i Riscontri con stato Attivo e Verificato. Se lasciata deselezionata, tutti i Riscontri dovranno essere inviati a Jira manualmente (singolarmente o tramite invio collettivo). + +Quando questa impostazione è abilitata, i ticket Jira continueranno a sincronizzarsi con DefectDojo anche se lo stato del Riscontro cambia. + +#### Abilitare la mappatura Epic dell'Engagement + +In DefectDojo, gli Engagement rappresentano un insieme di lavoro. Ogni Engagement contiene uno o più Test, che contengono uno o più Riscontri che devono essere mitigati. Gli Epic in Jira funzionano in modo simile, e questa casella di controllo ti consente di inviare gli Engagement a Jira come Epic. + +* Un Engagement in DefectDojo, nota i tre Riscontri elencati in fondo. +​ +![immagine](images/Add_a_Connected_Jira_Project_to_a_Product_8.png) +* Come lo stesso Engagement diventa un Epic quando viene inviato a JIRA: anche i Riscontri dell'Engagement vengono inviati, e risiedono all'interno dell'Engagement come ticket figli. + +![immagine](images/Add_a_Connected_Jira_Project_to_a_Product_9.png) + +#### Invia note + +Se abilitata, i commenti di Jira compariranno sul Riscontro associato in DefectDojo, sotto Note, e viceversa; le Note sui Riscontri verranno aggiunte al ticket Jira associato come Commenti. + +#### Invia le notifiche SLA come commenti + +Se abilitata, su qualsiasi ticket che viola le regole di Service Level Agreement di DefectDojo verranno aggiunti dei commenti che lo indicano nel ticket Jira. Questi commenti verranno pubblicati quotidianamente finché il ticket non viene risolto. + +I Service Level Agreement possono essere configurati in **Configuration \> SLA Configuration** in DefectDojo e assegnati a ciascun Prodotto. + +#### Invia le notifiche di scadenza dell'accettazione del rischio come commento + +Se abilitata, su qualsiasi ticket la cui Accettazione del rischio di DefectDojo associata scade verrà aggiunto un commento che lo indica nel ticket Jira. Questi commenti verranno pubblicati quotidianamente finché il ticket non viene risolto. + +### Impostazioni Jira a livello di Engagement + +Per impostazione predefinita, gli Engagement **ereditano le impostazioni Jira dal proprio Prodotto**. Tuttavia, puoi sovrascrivere le impostazioni Jira per i singoli Engagement. + +Per accedere alle impostazioni Jira a livello di Engagement, fai clic sul menu a forma di ingranaggio ⚙️ su un Engagement e apri la pagina **Jira Project Settings**. + +Da qui puoi deselezionare **Eredita dal Prodotto** e fornire valori specifici per l'Engagement per: **Chiave del progetto**, **Modello di ticket, Campi personalizzati, Etichette Jira, Assegnatario predefinito**, e altre impostazioni. + +Nota che una volta che un Engagement ha un proprio progetto Jira assegnato, non può più ereditare dal Prodotto. + +![immagine](images/Creating_Issues_in_Jira_5.png) + +## Passaggio 4: configurare la sincronizzazione bidirezionale: webhook Jira + +L'integrazione con Jira consente la sincronizzazione bidirezionale tramite webhook. DefectDojo riceve le notifiche di Jira a un indirizzo univoco, il che consente di ricevere commenti di Jira sui Riscontri, oppure di risolvere i Riscontri tramite Jira, a seconda della configurazione. + +### Individuazione dell'URL del webhook Jira + +Il webhook Jira si trova nel modulo delle impostazioni di sistema, sotto **Jira Integration Settings**: **Enterprise Settings \> System Settings** nella barra laterale. + +È inoltre necessario selezionare **Enable Jira Web Hook** nella stessa pagina prima che DefectDojo possa elaborare le notifiche Jira in arrivo. I webhook in arrivo vengono ignorati se questa casella oppure **Enable Jira Integration** (vedere [Passaggio 1](#step-1-enable-the-jira-integration-in-system-settings)) non sono selezionate. + +![image](images/Configuring_the_Jira_DefectDojo_Webhook.png) + +### Creazione del webhook Jira + +1. Visitare `**https:// \ /plugins/servlet/webhooks**` +2. Fare clic su «Create a Webhook». +3. Nel campo denominato «URL» inserire: `https:// \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>`. Il Web Hook Secret è indicato in Jira Integration Settings, come illustrato sopra. +4. In «Comments» attivare «Created». In Issue attivare «Updated». +5. Assicurarsi che l'istanza JIRA sia configurata per considerare attendibile il certificato SSL utilizzato dall'istanza DefectDojo. Per JIRA Cloud, DefectDojo deve utilizzare [un certificato SSL/TLS valido, firmato da un'autorità di certificazione riconosciuta a livello globale](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-registering-webhooks-with-non-secure-urls/) + +Da notare che non è necessario creare un Secret all'interno di Jira per utilizzare questo webhook. Il Secret è integrato nell'URL di DefectDojo, quindi è sufficiente aggiungere l'URL completo al modulo del webhook Jira. + +Le richieste webhook in arrivo vengono autenticate tramite il secret contenuto in tale URL: trattare quindi l'URL completo come una credenziale e mantenerlo riservato. + +#### Test del webhook + +Una volta create una o più Issue a partire dai Riscontri di DefectDojo, è possibile testare il webhook aggiungendo un commento a uno di questi Riscontri. Il commento dovrebbe essere ricevuto dal webhook Jira come nota. + +Se questo non funziona correttamente, potrebbe trattarsi di un problema del firewall sull'istanza Jira che blocca il webhook. + +* Le regole firewall di DefectDojo includono una casella di controllo per **Jira Cloud,** che deve essere abilitata prima che DefectDojo possa ricevere i messaggi webhook da Jira. + +### Alternativa: utilizzare Jira Automation (Send web request) + +Alcune istanze Jira non consentono i webhook di sistema in `/plugins/servlet/webhooks` — ad esempio quando quell'area di amministrazione è limitata e sono ammesse solo le regole **Jira Automation**. In tal caso è possibile ottenere la stessa sincronizzazione bidirezionale usando l'azione **Send web request** di Automation, che invia una richiesta allo stesso endpoint webhook di DefectDojo. + +L'endpoint webhook di DefectDojo accetta qualsiasi richiesta HTTP `POST` con `Content-Type: application/json` e un secret valido nel percorso dell'URL. **Non** richiede che la richiesta abbia origine dal meccanismo di webhook di sistema di Jira, quindi l'azione «Send web request» di Automation funziona come alternativa diretta. + +#### Prerequisiti + +Si applicano gli stessi prerequisiti del webhook di sistema: + +* **Enable JIRA integration** e **Enable JIRA web hook** sono entrambe selezionate nella pagina ⚙️ **Configuration \> System Settings**. +* Nella stessa pagina è impostato un **Jira webhook secret** non vuoto. Il secret può contenere solo i caratteri `A-Z`, `a-z`, `0-9`, `_` e `-`. +* Il Riscontro (o il Gruppo di Riscontri) è già collegato all'issue Jira. Se l'issue non è collegata a un Riscontro DefectDojo, la richiesta viene comunque accettata (HTTP `200`) ma non viene eseguita alcuna azione. + +#### Come DefectDojo elabora la richiesta + +* DefectDojo si basa su un campo di primo livello `webhookEvent`. Vengono elaborati solo `"jira:issue_updated"` e `"comment_created"`; qualsiasi altro valore viene accettato e ignorato. Automation **non** aggiunge questo campo automaticamente, quindi è necessario includerlo personalmente nel corpo della richiesta. +* Per questo motivo, impostare **Body** della richiesta su **Custom data** e fornire il JSON riportato di seguito. Le opzioni di corpo **Empty** e **Jira issue data** non includono il campo `webhookEvent` richiesto, pertanto DefectDojo le ignorerà. +* L'endpoint restituisce sempre HTTP `200`, indipendentemente dal fatto che sia stato applicato un aggiornamento. L'esito positivo o negativo è visibile solo nel corpo della risposta e nei log di DefectDojo — un `200` nel log di controllo di Automation **non** conferma da solo che l'aggiornamento abbia raggiunto un Riscontro. + +#### Regola 1 — Issue aggiornata + +Creare una regola Automation con: + +* **Trigger:** *Issue transitioned* (oppure un altro trigger che si attiva quando cambiano i campi sincronizzati, ad es. *Field value changed* su Status). +* **Action:** *Send web request* + * **Web request URL:** `https:///jira/webhook/` + * **HTTP method:** `POST` + * **Web request body:** *Custom data* + * **Headers:** `Content-Type: application/json` + * **Custom data:** + +```json +{ + "webhookEvent": "jira:issue_updated", + "issue": { + "id": "{{issue.id}}", + "fields": { + "updated": "{{issue.updated}}", + "resolution": null, + "status": { "statusCategory": { "key": "{{issue.status.statusCategory.key}}" } }, + "assignee": { "name": "{{issue.assignee.accountId}}", "displayName": "{{issue.assignee.displayName}}" } + } + } +} +``` + +Vincoli per gli aggiornamenti delle issue: + +* `issue.id` deve essere l'**ID numerico interno dell'issue Jira** (`{{issue.id}}`), non la chiave dell'issue (ad es. `PROJ-123`). DefectDojo associa l'aggiornamento a un Riscontro tramite questo ID numerico. +* I campi `resolution` e `updated` devono essere sempre presenti. `resolution` può essere `null`, ma se uno dei due campi manca, la richiesta viene accettata (`200`) e non viene elaborata, senza alcun avviso. +* La sincronizzazione dello stato e la mitigazione automatica sono determinate da `status.statusCategory.key`, i cui valori Jira sono `new` (To Do), `indeterminate` (In Progress) e `done` (Done). Un Riscontro viene mitigato solo quando l'issue è effettivamente chiusa, non semplicemente perché è presente un valore di resolution. + +#### Regola 2 — Issue commentata + +Creare una seconda regola Automation con: + +* **Trigger:** *Issue commented* +* **Action:** *Send web request* — stessi URL, metodo, header e opzione di corpo *Custom data* della Regola 1, con questo corpo: + +```json +{ + "webhookEvent": "comment_created", + "comment": { + "self": "https:///rest/api/2/issue/{{issue.id}}/comment/{{comment.id}}", + "body": "{{comment.body}}", + "updateAuthor": { "name": "{{comment.author.accountId}}", "displayName": "{{comment.author.displayName}}" } + } +} +``` + +Vincoli per i commenti: + +* Devono essere presenti sia `body` sia `updateAuthor`. +* DefectDojo ricava l'issue di destinazione dall'URL `comment.self` — nello specifico il `` nel segmento `.../issue//comment/...` — pertanto `{{issue.id}}` (l'ID numerico) deve comparire lì. +* **Prevenzione dei loop:** se l'autore del commento corrisponde all'account Jira che DefectDojo utilizza per pubblicare i propri commenti, DefectDojo ignora il commento per evitare un loop di eco. Per ingerire *tutti* i commenti, eseguire la regola Automation con un utente Jira **diverso** da quello configurato nell'istanza Jira di DefectDojo. + +#### Nota sugli smart values + +Gli smart values mostrati sopra (`{{issue.id}}`, `{{issue.status.statusCategory.key}}`, `{{comment.author.accountId}}`, e così via) sono i nomi standard di Jira Cloud, ma possono variare da un'istanza all'altra. Prima di andare in produzione, utilizzare l'anteprima del payload di Automation per verificare che ogni smart value venga risolto come previsto. + +## Test dell'integrazione Jira + +#### Test 1: i Riscontri vengono inviati correttamente a Jira? + +Per verificare che l'integrazione Jira funzioni correttamente, è possibile aggiungere un nuovo Riscontro vuoto al Prodotto associato a Jira in DefectDojo. **Prodotto \> Riscontri \> Add New Finding.** + +Aggiungere il titolo, la gravità e la descrizione desiderati, quindi fare clic su «Finished». Il Riscontro dovrebbe comparire come Issue in Jira con tutti i metadati pertinenti. + +Se le Issue Jira non vengono create correttamente, controllare le notifiche per individuare eventuali codici di errore. + +* Verificare che l'utente Jira associato alla configurazione Jira di DefectDojo disponga dei permessi per creare e aggiornare issue in quello specifico spazio Jira. + +#### Test 2: i webhook Jira inviano dati a DefectDojo + +Per testare i webhook Jira, aggiungere una Nota a un Riscontro che esiste anche in JIRA come Issue (ad esempio, l'issue di test della sezione precedente). + +Se i webhook sono configurati correttamente, la Nota dovrebbe comparire in Jira come commento sull'issue. + +Se questo non funziona correttamente, potrebbe trattarsi di un problema del firewall sull'istanza Jira che blocca il webhook. + +* Le regole firewall di DefectDojo includono una casella di controllo per **Jira Cloud,** che deve essere abilitata prima che DefectDojo possa ricevere i messaggi webhook da Jira. + +## Disconnessione da Jira + +Le integrazioni Jira possono essere rimosse dall'istanza solo se non sono state create Issue correlate. Se sono state create Issue, non è possibile rimuovere completamente un'istanza Jira da DefectDojo. + +È tuttavia possibile disabilitare l'integrazione Jira disattivandola a livello di Prodotto. Nella pagina **Jira Project Settings** (accessibile tramite il menu ⚙️ Gear su un Prodotto), deselezionare l'interruttore **Enabled**. Questa operazione non elimina né modifica alcun ticket Jira esistente creato da DefectDojo, ma disabilita eventuali aggiornamenti futuri. + +# Invio dei Riscontri a Jira + +Un Prodotto con un mapping JIRA può inviare i Riscontri a Jira come Issue utilizzando diversi metodi. È possibile inviare i Riscontri singolarmente, in blocco, come Gruppi di Riscontri, oppure automaticamente. + +## Invio di un singolo Riscontro + +1. Aprire il Riscontro che si desidera inviare. +2. Fare clic su **☰ Finding Menu** e selezionare **Push to Jira**. +3. Confermare l'invio quando richiesto. DefectDojo creerà un'Issue Jira e la collegherà al Riscontro. + +Una volta creata l'Issue, DefectDojo mostrerà un link all'Issue Jira nella pagina del Riscontro. + +![image](images/Creating_Issues_in_Jira_2.png) + +È anche possibile selezionare la casella **Push to Jira** durante la modifica di un Riscontro tramite il modulo **Edit Finding**. Quando il Riscontro viene salvato, verrà inviato a Jira. + +### Aggiornamento di un'Issue Jira collegata + +Se un Riscontro ha già un'Issue Jira collegata, selezionando nuovamente **Push to Jira** si aggiorna l'Issue Jira esistente con le modifiche effettuate in DefectDojo. Se **Push All Issues** è abilitato sul Prodotto, questa sincronizzazione avviene automaticamente. + +### Scollegamento di un Riscontro da Jira + +Per rimuovere l'associazione tra un Riscontro e la sua Issue Jira, fare clic su **☰ Finding Menu** e selezionare **Unlink From Jira**. Questo rimuove il collegamento in DefectDojo ma non elimina l'Issue Jira stessa. + +## Invio in blocco dei Riscontri + +È possibile inviare più Riscontri a Jira contemporaneamente utilizzando il modulo Bulk Update: + +1. Da un elenco di Riscontri, selezionare i Riscontri che si desidera inviare utilizzando le caselle di controllo. +2. Aprire il modulo **Bulk Update**. +3. In **Jira Settings**, selezionare la casella **Push to Jira**. +4. Fare clic su **Submit**. + +I Riscontri selezionati verranno messi in coda per l'invio a Jira. DefectDojo mostrerà un messaggio di conferma che indica quanti Riscontri sono stati messi in coda. + +## Invio degli Engagement come Epic + +Se **Enable Engagement Epic Mapping** è attivato nelle Jira Project Settings, è possibile inviare un Engagement a Jira come Epic. I Riscontri dell'Engagement verranno inviati come Child Issue all'interno di tale Epic. + +Per inviare un Engagement come Epic: + +1. Aprire l'Engagement che si desidera inviare. +2. Fare clic su **☰ Engagement Menu** e selezionare **Push to Jira**. +3. Facoltativamente, indicare un **Epic Name** (per impostazione predefinita corrisponde al nome dell'Engagement se lasciato vuoto) e una **Epic Priority**. +4. Selezionare **Push to Jira (Create Epic)** e inviare il modulo. + +## Invio dei Gruppi di Riscontri come Issue Jira + +Se i Gruppi di Riscontri sono abilitati, è possibile inviare un Gruppo di Riscontri a Jira come Issue singola anziché come Issue separate per ciascun Riscontro. + +Per inviare un Gruppo di Riscontri: + +1. Aprire il Gruppo di Riscontri. +2. Fare clic su **☰ Finding Group Menu** e selezionare **Push to Jira**, oppure selezionare la casella **Push to Jira** durante la modifica del Gruppo di Riscontri. + +Se è necessaria la rimozione, l'Issue Jira associata a un Gruppo di Riscontri deve essere eliminata direttamente dall'istanza Jira. + +### Creazione e invio automatico dei Gruppi di Riscontri + +Con **Push All Issues** abilitato sul Prodotto, e un'opzione **Group By** selezionata in fase di import: + +Finché i Gruppi di Riscontri vengono creati correttamente, è il Gruppo di Riscontri a essere inviato automaticamente a Jira come Issue, non i singoli Riscontri. + +![image](images/Creating_Issues_in_Jira_4.png) + +## Comportamento dell'invio automatico + +DefectDojo può inviare automaticamente Riscontri e aggiornamenti a Jira in diversi scenari: + +### Push All Issues + +Quando l'impostazione **Push All Issues** è abilitata nelle Jira Project Settings di un Prodotto, DefectDojo creerà automaticamente Issue Jira per tutti i Riscontri Attivi e Verificati. Questo include i Riscontri creati tramite import di una scansione. Una volta creata un'Issue Jira, questa continuerà a sincronizzarsi con DefectDojo anche se lo stato del Riscontro cambia. + +### Sincronizzazione automatica ai cambiamenti di stato + +Quando è abilitata l'impostazione **Push All Issues** oppure l'impostazione di sistema **Finding Jira Sync**, DefectDojo aggiornerà automaticamente le Issue Jira collegate quando vengono eseguite determinate azioni sui Riscontri: + +* **Request Review** \- Viene aggiunto un commento all'Issue Jira collegata (oppure all'Issue Jira del Gruppo di Riscontri, se il Riscontro appartiene a un gruppo). +* **Clear Review** \- Viene aggiunto un commento all'Issue Jira collegata. +* **Close Finding** \- L'Issue Jira collegata viene aggiornata per riflettere la chiusura. Se **Push Notes** è abilitato, viene aggiunto anche un commento. + +## Commenti e Note di Jira + +Quando **Push Notes** è abilitato nelle Jira Project Settings: + +* Se un commento viene aggiunto a un'Issue Jira, lo stesso commento verrà aggiunto al Riscontro, nella sezione **Note**. +* Allo stesso modo, se una Nota viene aggiunta a un Riscontro, la Nota verrà aggiunta all'issue Jira come commento. + +## Cambiamenti di stato Jira + +La configurazione dell'istanza Jira include voci per due Transizioni Jira che attivano un cambiamento di stato su un Riscontro. + +* Quando su Jira viene eseguita la **transizione «Close»**, anche il Riscontro associato si chiude e viene contrassegnato come **Inattivo** e **Mitigato** su DefectDojo. DefectDojo registrerà questa modifica nella pagina del Riscontro, sotto la voce **Mitigato da**. +​ +![image](images/Creating_Issues_in_Jira_3.png) + +* Quando sull'Issue Jira viene eseguita la **transizione «Reopen»**, il Riscontro associato verrà impostato come **Attivo** su DefectDojo, perdendo il suo stato **Mitigato**. + +## Mappatura delle Resolution di Jira su Accettazione del rischio / Falso positivo + +La configurazione dell'istanza Jira include due campi facoltativi che consentono di mappare una **Resolution** di Jira su uno stato del Riscontro di DefectDojo: + +* **Risk Accepted Finding Mapping Resolution** — quando un'issue Jira viene chiusa con questa Resolution, il Riscontro collegato diventa Rischio accettato in DefectDojo. +* **False Positive Finding Mapping Resolution** — quando un'issue Jira viene chiusa con questa Resolution, il Riscontro collegato diventa Falso positivo in DefectDojo. + +### Status contro Resolution: un punto di confusione comune + +Questi campi mappano la **Resolution** di Jira, non lo **Status** di Jira. Status e Resolution sono due concetti Jira indipendenti: lo Status descrive in quale punto del workflow si trova l'issue (Open, In Progress, Done), mentre la Resolution descrive il modo in cui è stata risolta (Fixed, Won't Do, Duplicate, False Positive, ecc.). + +### Prerequisito: una post-funzione «Set issue resolution» sulla transizione del workflow Jira + +Il motore dei workflow di Jira non compila automaticamente il campo Resolution. Ogni transizione che deve chiudere un'issue con una Resolution specifica richiede una post-funzione **Set issue resolution** configurata sulla transizione stessa. Senza questa post-funzione, l'issue passa al nuovo Status ma la Resolution resta vuota, e la mappatura di DefectDojo non ha nulla con cui corrispondere. + +Un amministratore Jira può aggiungere questa post-funzione da **Project Settings → Workflows → (edit workflow) → (select the closing transition) → Post Functions → Add post function → Set issue resolution**. + +# Campi personalizzati in Jira + +DefectDojo attualmente non supporta il passaggio di informazioni specifiche dell'Issue in questi campi personalizzati \- questi campi dovranno essere aggiornati manualmente in Jira dopo la creazione dell'issue. Ogni campo personalizzato verrà creato da DefectDojo solo con un valore predefinito. + + Jira Cloud ora consente di creare un valore predefinito per i campi personalizzati direttamente in-app. [Consultare la documentazione di Atlassian sui campi personalizzati](https://support.atlassian.com/jira-cloud-administration/docs/configure-a-custom-field/) per maggiori informazioni su come configurare questa funzionalità. + +I tipi di Issue Jira integrati di DefectDojo (**Bug, Task, Story** ed **Epic)** sono configurati per funzionare «pronti all'uso». I campi dati di DefectDojo verranno mappati automaticamente sui campi corrispondenti in Jira. Per impostazione predefinita, DefectDojo assegnerà Priority, Labels e un Reporter a ogni nuova Issue che crea. + +Alcune configurazioni Jira richiedono che vengano gestiti campi personalizzati aggiuntivi prima che un'issue possa essere creata. Questo processo consente di gestire questi campi personalizzati nell'integrazione DefectDojo \-\> Jira, garantendo che le issue vengano create correttamente. Questi campi personalizzati verranno aggiunti a tutte le chiamate API inviate da DefectDojo a un'istanza Jira collegata. + +Se non si utilizzano già campi personalizzati in Jira, non è necessario seguire questo processo. + +1. Registrazione dei nomi dei campi personalizzati in Jira (**interfaccia Jira**) +2. Determinazione dei valori Key per i nuovi campi personalizzati (Jira Field Spec Endpoint) +3. Individuazione dei dati accettabili per ciascun campo personalizzato, usando i valori Key come riferimento (Jira Issue Endpoint) +4. Creazione di un blocco JSON di riferimento dei campi per tenere traccia di tutte le Key dei campi personalizzati e dei dati accettabili (Jira Issue Endpoint) +5. Memorizzazione del blocco JSON nel Prodotto DefectDojo associato, per consentire la creazione dei campi personalizzati da Jira (interfaccia DefectDojo) +6. Verifica del lavoro svolto, assicurandosi che tutti i dati richiesti fluiscano correttamente da Jira + +#### Passaggio 1: registrare i nomi dei campi personalizzati in Jira + +Jira supporta diversi Context Field, tra cui selettori di data, etichette personalizzate e pulsanti di opzione. Ciascuno di questi Context Field avrà un valore Key diverso, reperibile nell'API di Jira. + +Annotare i nomi di ciascun campo personalizzato richiesto, poiché sarà necessario cercarli nell'API di Jira nel passaggio successivo. + +**Esempio di elenco di campi personalizzati (i nomi dei campi personalizzati saranno diversi):** + +* DefectDojo Custom URL Field +* Un altro esempio di campo personalizzato +* ... + +#### Passaggio 2: individuare i valori Key dei campi personalizzati di Jira + +Iniziare questo processo accedendo all'URL Field Spec dell'intera istanza Jira. + +Ecco un esempio di URL Field Spec: + +`https://yourcompany-example.atlassian.net/rest/api/2/field` + +L'API restituirà una lunga stringa JSON, che dovrà essere formattata in testo leggibile (utilizzando un editor di codice, un'estensione del browser oppure ). + +Il JSON restituito da questo URL conterrà tutti i campi personalizzati di Jira, la maggior parte dei quali non è rilevante per DefectDojo e presenta valori `"Null"`. Ogni oggetto in questa risposta API corrisponde a un campo diverso in Jira. Sarà necessario cercare gli oggetti il cui attributo `"name"` corrisponde ai nomi di ciascun campo personalizzato creato nell'interfaccia Jira, e quindi annotare il valore del relativo attributo "key". + +![image](images/Using_Custom_Fields.png) + +Una volta trovato l'oggetto corrispondente nell'output JSON, è possibile determinare il valore "key" \- in questo caso si tratta di `customfield_10050`. + +Jira genera valori Key diversi per ciascun campo personalizzato, ma questi valori Key non cambiano una volta creati. Se in futuro si crea un altro campo personalizzato, questo avrà un nuovo valore Key. + +**Espansione dell'elenco di campi personalizzati:** + +* "DefectDojo Custom URL Field" \= customfield\_10050 +* "Un altro esempio di campo personalizzato" \= customfield\_12345 +* ... + +#### Passaggio 3 \- Individuazione dei campi personalizzati in un'Issue Jira + +Individuare un'Issue in Jira che contenga i campi personalizzati annotati nel Passaggio 2\. Copiare la chiave dell'Issue dal titolo (dovrebbe avere un aspetto simile a "`EXAMPLE-123`") e accedere al seguente URL: + +`https://yourcompany-example.atlassian.net/rest/api/2/issue/EXAMPLE-123` + +Verrà restituita un'altra stringa JSON. + +Come in precedenza, l'output dell'API conterrà numerosi parametri oggetto `customfield_##` con valori `null` \- si tratta di campi personalizzati che Jira aggiunge per impostazione predefinita, non rilevanti per questa issue. Conterrà anche valori `customfield_##` che corrispondono ai valori Key dei campi personalizzati individuati nel passaggio precedente. A differenza dell'output di Field Spec, non si vedranno nomi che identificano questi campi personalizzati, motivo per cui è stato necessario annotare i valori key nel Passaggio 2\. + +![image](images/Using_Custom_Fields_2.png) + +**Esempio:** +Si sa che `customfield_10050` rappresenta il DefectDojo Custom URL Field poiché è stato annotato nel Passaggio 2\. È ora possibile vedere che `customfield_10050` contiene un valore `"https://google.com"` nell'issue `EXAMPLE-123`. + +#### Passaggio 4 \- Creazione di un riferimento JSON dei campi a partire da ogni Key dei campi personalizzati di Jira + +Sarà ora necessario prendere il valore di ciascuno dei campi personalizzati del proprio elenco e memorizzarli in un oggetto JSON (da utilizzare come riferimento). È possibile ignorare qualsiasi campo personalizzato che non corrisponda al proprio elenco. + +Questo oggetto JSON conterrà tutti i valori predefiniti per le nuove Issue Jira. Si consiglia di usare nomi facili da riconoscere per il proprio team come valori "predefiniti" da modificare: '`change-me.com`', '`Change this paragraph.`' ecc. + +**Esempio:** + +Dal Passaggio 3, si sa ora che Jira si aspetta una stringa URL per "`customfield_10050`". È possibile usare questo per costruire l'oggetto JSON di esempio. + +Si supponga di aver individuato anche un campo di testo breve relativo a DefectDojo, identificato come "`customfield_67890`". Si esaminerebbe questo campo nel secondo output dell'API, si osserverebbe il valore associato e si farebbe riferimento al valore memorizzato anche nell'oggetto JSON di esempio. +​ +L'oggetto JSON inizierà ad assomigliare a questo man mano che vi si aggiungono altri campi personalizzati. + +``` +{ + "customfield_10050": "https://change-me.com", + "customfield_67890": "This is the short text custom field." +} +``` + +Ripetere questo processo finché tutti i campi personalizzati di Jira rilevanti per DefectDojo non sono stati aggiunti al riferimento JSON dei campi. + +#### Tipi di dati \& sintassi Jira + +Alcuni campi, come i campi data, possono riguardare più campi personalizzati in Jira. In tal caso, sarà necessario aggiungere entrambi i campi al riferimento JSON dei campi. + +``` + "customfield_10040": "1970-01-01", + "customfield_10041": "1970-01-01T03:30:00.000+0200", +``` + +Altri campi, come il campo Label, possono essere tracciati come un elenco di stringhe \- assicurarsi che il riferimento JSON dei campi utilizzi un formato corrispondente all'output dell'API di Jira. + +``` +// a list of custom labels on a Jira object + "customfield_10042": [ + "custom-label-one", + "this-is-default", + "change-me-please" + ], +``` + +Altri campi personalizzati possono contenere informazioni aggiuntive e contestuali che dovrebbero essere rimosse dal riferimento dei campi. Ad esempio, il campo Custom Multichoice contiene un blocco aggiuntivo nell'output dell'API, che dovrà essere rimosso, poiché questo blocco memorizza il valore corrente del campo. + +* è necessario rimuovere l'oggetto aggiuntivo da questo campo: + +``` +"customfield_10047": [ + { + "value": "A" + }, + { + "self": "example.url...", + "value": "C", + "id": "example ID" + } +] +``` +* in alternativa, è possibile abbreviarlo come segue e ignorare la seconda parte: + +``` +"customfield_10047": [ + { + "value": "A" + } +] +``` + +#### Esempio di riferimento dei campi completo + +Ecco un riferimento JSON dei campi completo, con commenti in linea che spiegano a cosa si riferisce ciascun campo personalizzato. Questo vuole essere un esempio onnicomprensivo. Il JSON conterrà valori Key e dati diversi a seconda dei valori personalizzati che si desidera utilizzare durante la creazione dell'issue. + +``` +{ + "customfield_10050": "https://change-me.com", + + "customfield_10049": "This is a short text custom field", + +// two different fields, but both correspond to the same custom date attribute + "customfield_10040": "1970-01-01", + "customfield_10041": "1970-01-01T03:30:00.000+0200", + +// a list of custom labels on a Jira object + "customfield_10042": [ + "custom-label-one", + "this-is-default", + "change-me-please" + ], + +// custom number field + "customfield_10043": 0, + +// custom paragraph field + "customfield_10044": "This is a very long winded way to say CHANGE ME PLEASE", + +// custom radio button field + "customfield_10045": { + "value": "radio button option" + }, + +// custom multichoice field + "customfield_10047": [ + { + "value": "A" + } + ], + +// custom checkbox field + "customfield_10039": [ + { + "value": "A" + } + ], + +// custom select list (singlechoice) field + "customfield_10048": { + "value": "1" + } +} +``` + +#### Passaggio 5 \- Aggiunta dei campi personalizzati a un Prodotto DefectDojo + +È ora possibile aggiungere questi campi personalizzati al Prodotto DefectDojo associato, nella pagina Jira Project Settings (accessibile tramite il menu ⚙️ Gear sul Prodotto). Incollare il riferimento JSON dei campi come testo semplice nella casella **Custom Fields** e salvare. + +#### Passaggio 6 \- Test dei campi personalizzati Jira da un nuovo Riscontro: + +Ora, quando si crea un nuovo Riscontro nel Prodotto associato a Jira, Jira creerà automaticamente tutti questi campi personalizzati in Jira in base al blocco JSON in esso contenuto. Questi campi personalizzati verranno creati con i valori predefiniti ("change-me-please", ecc.). + +All'interno del Prodotto su DefectDojo, accedere alla pagina Riscontri \> Add New Finding. Assicurarsi che il Riscontro sia Attivo che Verificato per garantire l'invio a Jira, quindi confermare lato Jira che i campi personalizzati sono stati creati correttamente, senza incongruenze. diff --git a/docs/content/connectors/downstream/PRO__jira_guide.pt-br.md b/docs/content/connectors/downstream/PRO__jira_guide.pt-br.md new file mode 100644 index 0000000000..a35a6efe13 --- /dev/null +++ b/docs/content/connectors/downstream/PRO__jira_guide.pt-br.md @@ -0,0 +1,786 @@ +--- +title: Jira (Legado) +description: Trabalhe com a integração do Jira +weight: 1 +audience: pro +aliases: +- /pt-br/issue_tracking/jira/pro__jira_guide/ +- /pt-br/en/share_your_findings/jira_guide +--- + +> **Esta página documenta a integração legada do Jira.** A integração do Jira por produto descrita aqui foi substituída pelo **[Conector Downstream do Jira](/connectors/downstream/about/)**, que está disponível de forma geral em todas as instâncias do DefectDojo Pro e é a forma recomendada de enviar Achados para o Jira. Na barra lateral do Pro, **Connect > Jira** traz um selo `LEGACY` por esse motivo — veja [Menu Badges](/navigation/pro__menu_badges/). +> +> **Se você está configurando o Jira pela primeira vez, comece pelo [Conector Downstream](/connectors/downstream/about/) em vez deste guia.** +> +> **Já usa a integração legada?** O DefectDojo Pro inclui uma migração integrada que move sua configuração clássica existente do Jira para os Conectores Downstream, incluindo os tickets que você já enviou — veja [Migrando para o Conector Downstream do Jira](#migrating-to-the-jira-downstream-connector) abaixo. +> +> A integração legada continua funcionando, e este guia permanece válido para ela. + +A integração do Jira do DefectDojo pode ser usada para enviar dados de Achados para um ou mais Espaços do Jira. Ao fazer isso, você pode integrar o DefectDojo ao seu fluxo de trabalho de desenvolvimento padrão. Aqui estão alguns exemplos de como isso pode funcionar: + +* A equipe de AppSec pode enviar seletivamente Achados para um Espaço do Jira usado pelos desenvolvedores, para que a correção de problemas possa ser adequadamente priorizada junto com o desenvolvimento normal. Os desenvolvedores nesse quadro não precisam acessar o DefectDojo - eles podem manter todo o trabalho deles em um só lugar. +* O DefectDojo pode enviar TODOS os Achados para um Espaço do Jira bidirecional que a equipe de AppSec usa, o que permite que eles dividam a validação de problemas. Esse quadro se mantém sincronizado com o DefectDojo e permite fluxos de correção complexos. +* O DefectDojo pode enviar seletivamente Achados de Produtos e/ou Engajamentos separados para Espaços do Jira separados, para manter as coisas em seu contexto adequado. + +## Migrando para o Conector Downstream do Jira + +O DefectDojo Pro pode converter uma configuração clássica existente do Jira em uma configuração de Conector Downstream para você, em vez de exigir que você a reconstrua manualmente. + +**Onde encontrar:** acesse **Connect \> Downstream** para abrir a página **Downstream Connectors**, e use o cartão **Classic Jira Migration**. Clique em **Migrate from classic Jira** e depois confirme. + +O cartão só aparece se houver configuração clássica do Jira para migrar, ou uma execução anterior a reportar — então uma instância que nunca usou o Jira clássico não vai vê-lo. Depois que tudo tiver sido migrado, o cartão permanece, mas o botão fica desabilitado, porque não há mais nada a fazer. + +Executar a migração exige **permissões globais de nível Maintainer** (especificamente, permissão para editar integrações), e ela precisa ser executada a partir de uma sessão de navegador autenticada — não pode ser feita com um token de API. + +### O que acontece com os tickets que você já enviou + +**Seus tickets existentes do Jira são mantidos e vinculados novamente — eles não ficam órfãos, e o conector não abre duplicatas.** Cada Achado que o Jira clássico já havia enviado mantém seu ticket, e o conector passa a atualizar esse mesmo ticket a partir de então. Os links em Grupos de Achados são transferidos da mesma forma. + +A única exceção são os **epics de Engajamento**. O Conector Downstream não tem o conceito de epics, então os problemas do tipo epic são reportados nos avisos da migração e deixados intocados. + +### O que é migrado + +* Sua conexão de **instância** do Jira — URL e credenciais — se torna uma instância de integração de Conector Downstream, mantendo seu nome. +* Os **mapeamentos de severidade** e os **mapeamentos de status** (suas chaves de transição de abertura e fechamento) são transferidos. +* Cada configuração de **Projeto do Jira** se torna um mapeamento de rastreador de problemas, mantendo sua chave de projeto e tipo de issue, e permanece atribuída ao mesmo Produto ou Engajamento. +* **Push All Issues** é preservado: projetos que tinham essa opção habilitada continuam enviando automaticamente. +* **Campos personalizados**, **campos de transição de fechamento/reabertura**, **componente**, **responsável padrão** e **labels** são convertidos em mapeamentos de campo. Onde você usava *Add Vulnerability Id as a Jira label*, isso também se torna um mapeamento de label. +* Um diretório de **modelo de issue personalizado** se torna um modelo de ticket. Os modelos padrão não são copiados, porque o conector já traz equivalentes. + +### O que não é transferido + +Esses itens são reportados como avisos na execução da migração — eles não a interrompem. Procure pela lista *"things the connector cannot carry over"* nos resultados. + +* **Sincronização reversa do Jira → DefectDojo.** Esse é o ponto importante. O Conector Downstream não sincroniza alterações *de volta* a partir do Jira, então os mapeamentos de resolução que aplicam Risco aceito ou Falso positivo a partir de uma resolução do Jira não são migrados. **Se você depende da sincronização reversa, mantenha a instância clássica do Jira configurada** — a migração não a remove. +* **Engagement Epic Mapping** — o conector não tem o conceito de epic. +* **Push Notes**, **comentários de notificação de SLA** e **comentários de expiração de aceitação de risco** — o conector não publica esses itens no Jira. +* Campos personalizados chamados `summary`, `description`, `project`, `issuetype` ou `status` — esses são reservados pelo conector, e um mapeamento de campo que use um deles é ignorado. +* Valores de campo personalizado com mais de 512 caracteres — são ignorados em vez de truncados. +* Um Projeto do Jira que não está vinculado a nenhum Produto nem Engajamento não gera nenhuma atribuição. + +### O que acontece com a integração clássica depois + +**Nada é enviado duas vezes.** Para cada projeto que migra, a migração desativa o projeto clássico do Jira, de modo que somente o conector envia a partir desse ponto. Você não precisa desabilitar nada manualmente. + +Sua configuração clássica é **mantida, não excluída** — a instância, o projeto e os registros de issue permanecem todos, apenas com as configurações de envio desativadas. Isso é proposital: é o que torna a mudança reversível, e é o que mantém a sincronização reversa funcionando caso você dependa dela. + +**Para reverter**, reative as configurações do projeto clássico do Jira e remova a configuração do conector criada pela migração. Não existe um desfazer com um clique. + +**Executar novamente é seguro.** A migração registra o que já foi convertido e ignora isso em uma segunda execução, então nada é duplicado. Se um projeto ou instância falhar, o restante ainda é migrado — um projeto com falha é deixado em execução na integração clássica em vez de ser desativado, para que continue funcionando enquanto você investiga. + +### Enquanto ela é executada + +A migração é executada em segundo plano e reporta o progresso conforme avança. Quando termina, você recebe um resumo — quantos conectores, mapeamentos, atribuições, modelos e vínculos de ticket foram criados, quantos projetos clássicos foram desativados, e o que foi ignorado — junto com os avisos descritos acima. Apenas uma migração é executada por vez. + +# Configurando o Jira + +Configurar o Jira exige as seguintes etapas: +1. Habilite a integração do Jira em System Settings. Até que você faça isso, o restante das configurações do Jira fica oculto em todo o DefectDojo. +2. Conecte uma Instância do Jira, seja com um nome de usuário / senha ou com um token de API. Múltiplas instâncias podem ser vinculadas. +3. Adicione essa Instância do Jira a um ou mais Produtos ou Engajamentos dentro do DefectDojo. +4. Se desejar usar sincronização bidirecional, crie um Webhook do Jira que enviará atualizações ao DefectDojo. + +## Etapa 1: Habilitar a integração do Jira em System Settings + +A integração do Jira fica desativada por padrão, e enquanto estiver desativada o DefectDojo oculta todos os demais controles do Jira na interface. Isso é a primeira coisa a configurar: nenhuma das etapas abaixo fica disponível até que ela seja habilitada. + +Enquanto a integração está desabilitada, não há uma entrada **Jira Instances** na barra lateral, então não há onde adicionar uma Instância do Jira: + +![image](images/jira-menu-hidden-pro.png) + +### Habilitar a integração + +1. Navegue até **Settings \> System \> System Settings** a partir da barra lateral do DefectDojo. Em instâncias que ainda usam o layout de menu anterior, isso fica em um grupo nomeado de acordo com seu pacote de licença — **Pro Settings** ou **Enterprise Settings**. Veja [The Settings Menu](/navigation/pro__settings_menu/). +​ +2. Na seção **Jira Integration Settings**, marque **Enable Jira Integration**. +​ +3. Clique em **Submit**. **Jira Instances** aparece na barra lateral imediatamente, sem recarregar a página: + +![image](images/jira-enable-system-settings-pro.png) + +### O que a configuração controla + +Habilitar **Enable Jira Integration** é o que faz o restante da interface do Jira aparecer. Com ela ativada, você obtém: + +* o menu **Jira Instances**, onde as Instâncias do Jira são adicionadas e editadas +* a página **Jira Project Settings** no menu ⚙️ do Ativo, e as configurações do Jira nos Engajamentos +* as ações **Push to Jira** em Achados e Grupos de Achados, os campos do Jira nos formulários de Achado e edição em massa, e as colunas do Jira nas listas de Ativo, Engajamento, Achado e Grupo de Achados (incluindo exportações CSV) + +A configuração também controla a integração fora da interface: enquanto estiver desativada, o DefectDojo não enviará Achados para o Jira (incluindo requisições `push_to_jira` enviadas pela API), e os webhooks recebidos do Jira são ignorados. + +Os demais campos do Jira em **Jira Integration Settings** (**Add Vulnerability ID as Jira Label**, **Enable Jira Web Hook**, **Disable Jira Web Hook Secret**, **Jira Web Hook Secret**, **Jira Minimum Severity**) permanecem visíveis independentemente de a integração estar ativada ou desativada, mas não têm efeito até que ela seja habilitada. + +## Etapa 2: Conectar uma Instância do Jira + +Com a integração habilitada, conectar uma Instância do Jira é a próxima etapa na configuração da integração do Jira no DefectDojo. Observe que o Jira Service Management não é suportado atualmente. + +#### Informações necessárias do Jira + +A Atlassian usa formas diferentes de autenticação entre o Jira Cloud e o Jira Data Center. + +para **Jira Cloud**, você precisará de: +* uma URL do Jira, ex.: https://yourcompany.atlassian.net/ +* uma conta com permissões para criar e atualizar issues na sua instância do Jira. Isso pode ser: + * Uma combinação padrão de **usuário / senha** + * Uma combinação de **usuário / Token de API** + +para **Jira Data Center (ou Server)**, você precisará de: +* uma URL do Jira, ex.: https://jira.yourcompany.com +* uma conta com permissões para criar e atualizar issues na sua instância do Jira. Isso pode ser: + * Uma combinação padrão de **usuário / senha** + * Uma combinação de **endereço de e-mail / Personal Access Token** + +Opcionalmente, você pode mapear: +* Transições do Jira para acionar a Reabertura e o Fechamento de Achados +* Resoluções do Jira que podem aplicar os status de Risco aceito e Falso positivo aos Achados (opcional) + +Múltiplos Espaços do Jira podem ser tratados por uma única conexão de Instância do Jira, desde que a conta / token do Jira usado pelo DefectDojo tenha permissão para criar Issues no Espaço do Jira associado. + +### Adicionar uma Instância do Jira + +1. Certifique-se de que **Enable Jira Integration** esteja marcado em System Settings, conforme descrito na [Etapa 1](#step-1-enable-the-jira-integration-in-system-settings). O menu **Jira Instances** não aparece na barra lateral até que isso ocorra. + +2. Navegue até a página **Enterprise Settings \> Jira Instances \> + New Jira Instance** a partir da barra lateral do DefectDojo. + +![image](images/jira-instance-beta.png) + +3. Selecione um **Configuration Name** para essa Instância do Jira usar no DefectDojo. Esse nome é simplesmente um rótulo para a conexão da Instância no DefectDojo, e não precisa estar relacionado a nenhum dado do Jira. + +4. Selecione a URL da instância do Jira da sua empresa \- provavelmente semelhante a `https://**yourcompany**.atlassian.net` se você estiver usando uma instalação do Jira Cloud. + +5. Informe um método de autenticação apropriado nos campos Username / Password do Jira: + * Para a **autenticação padrão de usuário / senha do Jira**, informe um Nome de Usuário do Jira e a Senha correspondente nesses campos. + * Para autenticação com um **token de API do usuário (Jira Cloud)**, informe o Nome de Usuário com o **token de API** correspondente no campo de senha. + * Para autenticação com um **Personal Access Token** do Jira (também conhecido como PAT, usado apenas no Jira Data Center e no Jira Server), informe o PAT no campo de senha. O Nome de Usuário não é usado para autenticação com um PAT do Jira, mas o campo ainda é obrigatório neste formulário, então você pode usar um valor de referência aqui para identificar seu PAT. + +Observe que o usuário associado a essa conexão precisa ter permissão para criar Issues e acessar dados na sua instância do Jira. + +6. Você precisará fornecer valores para um Epic Name ID, Re-open Transition ID e Close Transition ID. Esses valores podem ser alterados depois. Estando conectado ao Jira, você pode acessar esses valores a partir das seguintes URLs: +- **Epic Name ID**: visite `https:///rest/api/2/field` e procure por Epic Name. Copie o número em `number` e cole aqui. Se você não tiver um Epic Name ID associado ao seu Espaço no Jira (por usar um Espaço Gerenciado por Equipe, por exemplo), informe 0 nesse campo. +- **Re-open Transition ID**: visite `https:///rest/api/latest/issue//transitions?expand-transitions.fields` para encontrar o ID da sua instância do Jira. Cole no campo Reopen Transition ID. +- **Close Transition ID**: Visite `https:///rest/api/latest/issue//transitions?expand-transitions.fields` para encontrar o ID da sua instância do Jira. Cole no campo Close Transition ID. + +7. Selecione o tipo de issue padrão que você deseja usar ao criar Issues no Jira. As opções são **Bug, Task, Story** e **Epic** (que são tipos de issue padrão do Jira), além de **Spike** e **Security**, que são tipos de issue personalizados. Se você tiver um Tipo de Issue diferente que deseja usar, entre em contato com [support@defectdojo.com](mailto:support@defectdojo.com) para obter assistência. + +8. Selecione seu Modelo de Issue, que determinará a Descrição da Issue quando as Issues forem criadas no Jira. + +Os dois tipos são: +- **Jira\_full**, que incluirá todas as informações do Achado nas Issues do Jira +- **Jira\_limited**, que incluirá uma quantidade menor de informações e metadados do Achado. + +Se você deixar esse campo em branco, o padrão será **Jira\_full.** Se precisar de um tipo diferente de modelo, entre em contato com [support@defectdojo.com](mailto:support@defectdojo.com). + +9. Se desejar, informe o nome de uma Resolução do Jira que alterará o status de um Achado para Aceito ou para Falso positivo (quando a Resolução for acionada na Issue). + +O formulário pode ser enviado a partir daqui. Se desejar, você pode personalizar ainda mais sua integração do Jira em Optional Fields. Clicar nesse botão permitirá aplicar texto genérico às Issues do Jira ou alterar o mapeamento de Jira Severity Mappings. + +## Etapa 3: Conectar um Produto ou Engajamento ao Jira + +Cada Produto ou Engajamento no DefectDojo tem suas próprias configurações que determinam como os Achados são convertidos em Issues do JIRA. A partir daqui, você pode decidir o Espaço do Jira associado e definir o comportamento padrão para criação de Issues, Epics, Labels e outros metadados do JIRA. + +### Adicionar o Jira a um Produto + +Você pode encontrar essa página clicando no menu de Engrenagem em um Produto ⚙️ e abrindo a página **Jira Project Settings**. + +![image](images/jira-project-settings.png) + +#### Instância do Jira + +Se você tiver múltiplas instâncias do Jira configuradas, para produtos ou equipes separados dentro da sua organização, você pode indicar em qual Espaço do Jira deseja que o DefectDojo crie Issues. Selecione um Espaço no menu suspenso. + +Se esse menu não listar nenhuma instância do Jira, confirme que esses Espaços estão conectados na sua Configuração Global do Jira para o DefectDojo \- yourcompany.defectdojo.com/jira. + +#### Chave do projeto + +Essa é a chave do Espaço que você deseja usar com o DefectDojo. A Chave do Espaço para um determinado Espaço pode ser encontrada na URL. (Isso antes era chamado de **Jira Project Key**, mas a partir de setembro de 2025, isso agora é chamado no Jira de **Space Key**). + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_3.png) + +#### Nome do tipo de issue Epic + +O nome do tipo de issue Epic no Jira. O padrão é "Epic", mas pode ser alterado se sua instância do Jira usar um nome diferente. + +#### Modelo de issue + +Aqui você pode determinar quantos metadados do DefectDojo deseja enviar ao Jira. Selecione uma das duas opções: + +* **jira\_full**: as Issues rastrearão todos os parâmetros do DefectDojo \- uma Descrição completa, CVE, Severidade, etc. Útil se você precisar de contexto completo do Achado no Jira (por exemplo, se alguém está trabalhando nessa Issue e não tem acesso ao DefectDojo). + +Aqui está um exemplo de uma Issue **jira\_full**: +​ +![image](images/Add_a_Connected_Jira_Project_to_a_Product_4.png) + +* **Jira\_limited:** as Issues rastrearão apenas o link do DefectDojo, os links de Produto/Engajamento/Teste, os campos Reporter e Environment. Todos os outros campos são rastreados apenas no DefectDojo. Útil se você não precisar de contexto completo do Achado no Jira (por exemplo, se alguém está trabalhando nessa Issue e trabalha principalmente no DefectDojo, sem precisar do quadro completo também no JIRA). + +​Aqui está um exemplo de uma Issue **jira\_limited**: + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_5.png) + +#### Componente + +Se você gerencia seu Espaço do Jira usando Componentes, pode atribuir aqui o Componente apropriado para o DefectDojo. Para atribuir mais de um Componente, informe uma lista separada por vírgulas (por exemplo, `Security, DevSecOps`); cada valor é enviado ao Jira como um componente separado. + +#### Campos personalizados + +Se você não precisar usar Campos Personalizados com issues do DefectDojo, pode deixar esse campo como 'null'. + +No entanto, se as Configurações do seu Espaço do Jira **exigirem** que você use Campos Personalizados em novas Issues, você precisará codificar esses mapeamentos. + +Observe que o DefectDojo não consegue enviar metadados específicos de uma Issue como Campos Personalizados, apenas um valor padrão. Essa seção só deve ser configurada se o seu Espaço do Jira **exigir que esses Campos Personalizados existam** em todas as Issues do seu Espaço. + +Siga **[este guia](#custom-fields-in-jira)** para começar a trabalhar com Campos Personalizados. + +#### Campos de transição de fechamento / reabertura + +Alguns fluxos de trabalho do Jira **exigem** que determinados campos sejam definidos como parte de uma transição — por exemplo, um fluxo de trabalho que se recusa a fechar uma Issue a menos que um campo de Resolução e um campo de Justificativa sejam fornecidos na tela de fechamento. A configuração de Campos personalizados acima só se aplica quando uma Issue é *criada*, então ela não consegue atender a esses fluxos de trabalho. + +Sem essas configurações, o DefectDojo envia transições de fechamento / reabertura sem nenhum campo. Um fluxo de trabalho que exige campos rejeitará essa transição, e o Achado e a Issue do Jira ficam dessincronizados: o Achado aparece como Mitigado no DefectDojo enquanto a Issue permanece aberta no Jira. + +As configurações **Close Transition fields** e **Reopen Transition fields** aceitam um objeto JSON que é enviado como o payload `fields` da chamada de transição de fechamento / reabertura. Por exemplo, para fechar Issues com uma Resolução de *Won't Fix* mais um valor de justificativa: + +```json +{ + "resolution": {"name": "Won't Fix"}, + "customfield_10200": "Risk accepted by security team #report-false-positive" +} +``` + +Deixe essas configurações como 'null' se o seu fluxo de trabalho do Jira não exigir campos nas transições. + +**Quais campos você precisa?** + +* Pergunte ao seu administrador do Jira quais campos estão nas **telas de transição** de fechamento / reabertura, e quais deles são exigidos por um validador. O JSON configurado precisa atender **todos** os campos obrigatórios: se algum campo obrigatório estiver ausente do payload, o Jira rejeita toda a transição e não define nada — fornecer apenas alguns dos campos obrigatórios não ajuda. +* Por outro lado, os campos precisam estar presentes **na tela de transição** para serem enviados: o Jira rejeita transições que tentam definir campos que não estão na tela dessa transição. +* Em fluxos de trabalho construídos com o editor de fluxo de trabalho atual do Jira Cloud, o Jira preenche automaticamente a Resolução padrão do site quando uma Issue passa para um status da categoria concluído. Assim, uma Resolução obrigatória sozinha não bloqueará uma transição simples nesse caso, e o uso prático de `"resolution"` neste payload é escolher um valor *significativo* (por exemplo, *False Positive*) em vez do padrão do site. Fluxos de trabalho construídos com o editor clássico, ou com aplicativos validadores do marketplace, ainda podem exigir a Resolução de forma obrigatória. +* As transições de reabertura tipicamente limpam a Resolução através do próprio fluxo de trabalho, então **Reopen Transition fields** geralmente só precisa dos campos personalizados que seu fluxo de trabalho exige. + +**Observações:** + +* O mesmo JSON é enviado para *toda* transição de fechamento (ou reabertura) do Produto ou Engajamento — os valores são estáticos e não variam por Achado. Se você precisar de campos diferentes por disposição (por exemplo, uma Resolução diferente para achados Falso positivo do que para achados corrigidos), use o DefectDojo Pro Jira Integrator, que suporta mapeamentos de campo de transição por status. +* Os valores usam o mesmo formato da API REST do Jira: strings para campos de texto, `{"name": ...}` para resoluções, `[{"name": ...}]` para campos de múltipla seleção, e assim por diante. +* Se as transições foram rejeitadas enquanto essas configurações estavam ausentes ou incompletas, corrigir as configurações repara a divergência: o próximo envio de status para o Achado tenta novamente a transição com os campos configurados. +* Ambas as configurações também estão disponíveis no endpoint REST `/api/v2/jira_projects/` (`close_transition_fields` / `reopen_transition_fields`), então podem ser gerenciadas via API. +* Esses campos também são aplicados quando o DefectDojo fecha uma Issue porque seu Achado foi **excluído** — os valores são capturados no momento em que o fechamento é enfileirado. + +#### Labels do Jira + +Selecione os labels relevantes com os quais você deseja que a Issue seja criada no Jira, ex.: **DefectDojo**, **YourProductName..** + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_6.png) + +#### Responsável padrão + +O nome do responsável padrão no Jira. Se deixado em branco, o DefectDojo seguirá o comportamento padrão do seu Espaço do Jira ao criar Issues. + +### Jira Project Settings + +#### Habilitado + +Esse alternador controla se o DefectDojo envia Achados para o Jira nesse Produto. Desabilitar isso não excluirá nem alterará nenhum ticket do Jira existente criado pelo DefectDojo, mas impedirá quaisquer atualizações adicionais ou a criação de novas Issues. + +As integrações do Jira só podem ser removidas da sua instância se nenhuma Issue relacionada tiver sido criada. Se Issues já foram criadas, não há como remover completamente uma Instância do Jira do DefectDojo. + +#### Adicionar o Vulnerability Id como um label do Jira + +Isso permite adicionar automaticamente os dados de Vulnerability ID como um Label do Jira. Os IDs de Vulnerabilidade são adicionados aos Achados por ferramentas de segurança individuais \- podem ser IDs de Common Vulnerabilities and Exposures (CVE) ou um formato diferente, específico da ferramenta que reporta o Achado. + +#### Push All Issues + +Se marcado, o DefectDojo enviará automaticamente todos os Achados Ativos e Verificados ao Jira como Issues. Se deixado desmarcado, todos os Achados precisarão ser enviados ao Jira manualmente (individualmente ou por envio em massa). + +Quando essa configuração está habilitada, as Issues do Jira continuarão sincronizadas com o DefectDojo mesmo se o status do Achado mudar. + +#### Habilitar Engagement Epic Mapping + +No DefectDojo, os Engajamentos representam uma coleção de trabalho. Cada Engajamento contém um ou mais testes, que contêm um ou mais Achados que precisam ser mitigados. Os Epics no Jira funcionam de forma semelhante, e essa caixa de seleção permite enviar Engajamentos ao Jira como Epics. + +* Um Engajamento no DefectDojo \- observe os três achados listados na parte inferior. +​ +![image](images/Add_a_Connected_Jira_Project_to_a_Product_8.png) +* Como o mesmo Engajamento se torna um Epic quando enviado ao JIRA \- os Achados do Engajamento também são enviados, e residem dentro do Epic como Issues filhas. + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_9.png) + +#### Push Notes + +Se habilitado, os comentários do Jira serão exibidos no Achado associado no DefectDojo, em Notas, e vice-versa; Notas em Achados serão adicionadas à Issue do Jira associada como Comentários. + +#### Enviar Notificações de SLA Como Comentários + +Se habilitado, qualquer Issue que viole as regras de Acordo de Nível de Serviço do DefectDojo terá comentários adicionados na issue do Jira indicando isso. Esses comentários serão publicados diariamente até que a Issue seja resolvida. + +Os Acordos de Nível de Serviço podem ser configurados em **Configuration \> SLA Configuration** no DefectDojo e atribuídos a cada Produto. + +#### Enviar Notificações de Expiração de Aceitação de Risco Como Comentário + +Se habilitado, qualquer Issue cuja Aceitação de Risco associada no DefectDojo expire terá um comentário adicionado na issue do Jira indicando isso. Esses comentários serão publicados diariamente até que a Issue seja resolvida. + +### Configurações de Jira em Nível de Engajamento + +Por padrão, os Engajamentos **herdam as configurações do Jira do seu Produto**. No entanto, você pode sobrepor as configurações do Jira para Engajamentos individuais. + +Para acessar as configurações de Jira em nível de Engajamento, clique no menu de Engrenagem ⚙️ em um Engajamento e abra a página **Jira Project Settings**. + +A partir daqui, você pode desmarcar **Inherit from Product** e fornecer valores específicos do Engajamento para: **Project Key**, **Issue Template, Custom Fields, Jira Labels, Default Assignee**, e outras configurações. + +Observe que, uma vez que um Engajamento tenha seu próprio projeto do Jira atribuído, ele não pode mais herdar do Produto. + +![image](images/Creating_Issues_in_Jira_5.png) + +## Etapa 4: Configurar Sincronização Bidirecional: Webhook do Jira + +A integração com o Jira permite sincronização bidirecional via webhook. O DefectDojo recebe notificações do Jira em um endereço exclusivo, o que permite que comentários do Jira sejam recebidos nos Achados, ou que Achados sejam resolvidos via Jira, dependendo da sua configuração. + +### Localizando a URL do seu Webhook do Jira + +Seu Webhook do Jira está localizado no formulário de Configurações do Sistema, em **Configurações de Integração do Jira**: **Configurações Corporativas \> Configurações do Sistema** na barra lateral. + +Você também precisa marcar **Habilitar Webhook do Jira** na mesma página antes que o DefectDojo processe as notificações recebidas do Jira. Os webhooks recebidos são ignorados se essa caixa ou **Habilitar Integração com o Jira** (veja a [Etapa 1](#step-1-enable-the-jira-integration-in-system-settings)) estiver desmarcada. + +![image](images/Configuring_the_Jira_DefectDojo_Webhook.png) + +### Criando o Webhook do Jira + +1. Acesse `**https:// \ /plugins/servlet/webhooks**` +2. Clique em 'Create a Webhook'. +3. No campo chamado 'URL', insira: `https:// \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>`. O Web Hook Secret está listado em Configurações de Integração do Jira, conforme mencionado acima. +4. Em 'Comments', habilite 'Created'. Em 'Issue', habilite 'Updated'. +5. Certifique-se de que sua instância do JIRA confia no certificado SSL usado pela sua instância do DefectDojo. Para o JIRA Cloud, o DefectDojo deve usar [um certificado SSL/TLS válido, assinado por uma autoridade certificadora globalmente confiável](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-registering-webhooks-with-non-secure-urls/) + +Observe que você não precisa criar um Secret dentro do Jira para usar esse webhook. O Secret já está embutido na URL do DefectDojo, portanto basta adicionar a URL completa ao formulário de Webhook do Jira. + +As requisições de webhook recebidas são autenticadas pelo secret contido nessa URL, portanto trate a URL completa como uma credencial e mantenha-a privada. + +#### Testando o Webhook + +Depois de ter uma ou mais Issues criadas a partir de Achados do DefectDojo, você pode testar o Webhook adicionando um Comentário a um desses Achados. O Comentário deve ser recebido pelo webhook do Jira como uma nota. + +Se isso não funcionar corretamente, pode ser devido a um problema de firewall na sua instância do Jira bloqueando o Webhook. + +* As Regras de Firewall do DefectDojo incluem uma caixa de seleção para o **Jira Cloud,** que precisa ser habilitada antes que o DefectDojo possa receber mensagens de Webhook do Jira. + +### Alternativa: Usando o Jira Automation (Send web request) + +Algumas instâncias do Jira não permitem webhooks de sistema em `/plugins/servlet/webhooks` — por exemplo, quando essa área de administração é restrita e somente regras do **Jira Automation** são permitidas. Nesse caso, você pode obter a mesma sincronização bidirecional usando a ação **Send web request** do Automation, que envia os dados para o mesmo endpoint de webhook do DefectDojo. + +O endpoint de webhook do DefectDojo aceita qualquer `POST` HTTP com `Content-Type: application/json` e um secret válido no caminho da URL. Ele **não** exige que a requisição venha do mecanismo de webhook de sistema do Jira, portanto a ação "Send web request" do Automation funciona como uma alternativa direta. + +#### Pré-requisitos + +Aplicam-se os mesmos pré-requisitos do webhook de sistema: + +* **Enable JIRA integration** e **Enable JIRA web hook** estão ambas marcadas na página ⚙️ **Configuration \> System Settings**. +* Um **Jira webhook secret** não vazio está definido nessa página. O secret pode conter apenas os caracteres `A-Z`, `a-z`, `0-9`, `_` e `-`. +* O Achado (ou Grupo de Achados) já está vinculado à issue do Jira. Se a issue não estiver vinculada a um Achado do DefectDojo, a requisição ainda é aceita (HTTP `200`), mas nenhuma ação é executada. + +#### Como o DefectDojo processa a requisição + +* O DefectDojo direciona o processamento com base em um campo `webhookEvent` de nível superior. Somente `"jira:issue_updated"` e `"comment_created"` são processados; qualquer outro valor é aceito e ignorado. O Automation **não** adiciona esse campo automaticamente, portanto você precisa incluí-lo você mesmo no corpo da requisição. +* Por isso, defina o **Body** da requisição como **Custom data** e forneça o JSON abaixo. As opções de body **Empty** e **Jira issue data** não incluem o campo `webhookEvent` obrigatório, portanto o DefectDojo as ignorará. +* O endpoint sempre retorna HTTP `200`, independentemente de uma atualização ter sido aplicada ou não. O sucesso ou a falha só ficam visíveis no corpo da resposta e nos logs do DefectDojo — um `200` no log de auditoria do Automation **não** confirma, por si só, que a atualização chegou a um Achado. + +#### Rule 1 — Issue atualizada + +Crie uma regra do Automation com: + +* **Trigger:** *Issue transitioned* (ou outro trigger que seja disparado quando os campos que você sincroniza mudarem, por exemplo *Field value changed* em Status). +* **Action:** *Send web request* + * **Web request URL:** `https:///jira/webhook/` + * **HTTP method:** `POST` + * **Web request body:** *Custom data* + * **Headers:** `Content-Type: application/json` + * **Custom data:** + +```json +{ + "webhookEvent": "jira:issue_updated", + "issue": { + "id": "{{issue.id}}", + "fields": { + "updated": "{{issue.updated}}", + "resolution": null, + "status": { "statusCategory": { "key": "{{issue.status.statusCategory.key}}" } }, + "assignee": { "name": "{{issue.assignee.accountId}}", "displayName": "{{issue.assignee.displayName}}" } + } + } +} +``` + +Restrições para atualizações de issue: + +* `issue.id` deve ser o **ID numérico interno da issue no Jira** (`{{issue.id}}`), não a chave da issue (por exemplo, `PROJ-123`). O DefectDojo associa a atualização a um Achado por meio desse ID numérico. +* Os campos `resolution` e `updated` devem sempre estar presentes. `resolution` pode ser `null`, mas se qualquer um dos dois campos estiver ausente, a requisição é aceita (`200`) e silenciosamente não processada. +* A sincronização de status e a auto-mitigação são controladas por `status.statusCategory.key`, cujos valores no Jira são `new` (To Do), `indeterminate` (In Progress) e `done` (Done). Um Achado só é mitigado quando a issue é realmente fechada, e não apenas porque um valor de resolution está presente. + +#### Rule 2 — Issue comentada + +Crie uma segunda regra do Automation com: + +* **Trigger:** *Issue commented* +* **Action:** *Send web request* — mesma URL, método, header e opção de body *Custom data* que na Rule 1, com este body: + +```json +{ + "webhookEvent": "comment_created", + "comment": { + "self": "https:///rest/api/2/issue/{{issue.id}}/comment/{{comment.id}}", + "body": "{{comment.body}}", + "updateAuthor": { "name": "{{comment.author.accountId}}", "displayName": "{{comment.author.displayName}}" } + } +} +``` + +Restrições para comentários: + +* Tanto `body` quanto `updateAuthor` devem estar presentes. +* O DefectDojo deriva a issue de destino a partir da URL `comment.self` — especificamente o `` no segmento `.../issue//comment/...` — portanto `{{issue.id}}` (o ID numérico) precisa aparecer ali. +* **Prevenção de loop:** se o autor do comentário corresponder à conta do Jira que o DefectDojo usa para postar seus próprios comentários, o DefectDojo ignora o comentário para evitar um loop de eco. Se você quiser que *todos* os comentários sejam ingeridos, execute a regra do Automation como um usuário do Jira **diferente** daquele configurado na instância do Jira do DefectDojo. + +#### Uma observação sobre smart values + +Os smart values mostrados acima (`{{issue.id}}`, `{{issue.status.statusCategory.key}}`, `{{comment.author.accountId}}`, e assim por diante) são os nomes padrão do Jira Cloud, mas podem variar entre instâncias. Antes de colocar em produção, use o payload preview do Automation para confirmar que cada smart value resolve para o valor esperado. + +## Testando a integração com o Jira + +#### Teste 1: os Achados são enviados corretamente para o Jira? + +Para testar se a integração com o Jira está funcionando corretamente, você pode adicionar um novo Achado em branco ao Produto associado ao Jira no DefectDojo. **Product \> Findings \> Add New Finding.** + +Adicione o título, a severidade e a descrição que desejar, e clique em "Finished". O Achado deve aparecer como uma Issue no Jira com todos os metadados relevantes. + +Se as Issues do Jira não estiverem sendo criadas corretamente, verifique suas Notificações para códigos de erro. + +* Confirme que o Usuário do Jira associado à Configuração do Jira do DefectDojo tem permissão para criar e atualizar issues naquele Jira Space específico. + +#### Teste 2: os Webhooks do Jira enviam dados para o DefectDojo + +Para testar os webhooks do Jira, adicione uma Nota a um Achado que também exista no JIRA como uma Issue (por exemplo, a issue de teste da seção acima). + +Se os webhooks estiverem configurados corretamente, você deverá ver a Nota no Jira como um Comentário na issue. + +Se isso não funcionar corretamente, pode ser devido a um problema de firewall na sua instância do Jira bloqueando o Webhook. + +* As Regras de Firewall do DefectDojo incluem uma caixa de seleção para o **Jira Cloud,** que precisa ser habilitada antes que o DefectDojo possa receber mensagens de Webhook do Jira. + +## Desconectando do Jira + +As integrações com o Jira só podem ser removidas da sua instância se nenhuma Issue relacionada tiver sido criada. Se Issues já tiverem sido criadas, não há como remover completamente uma instância do Jira do DefectDojo. + +No entanto, você pode desabilitar sua integração com o Jira desabilitando-a no nível do Produto. Na página **Jira Project Settings** (acessível pelo menu ⚙️ Engrenagem em um Produto), desmarque a opção **Enabled**. Isso não excluirá nem alterará nenhum ticket do Jira já criado pelo DefectDojo, mas desabilitará futuras atualizações. + +# Enviando Achados para o Jira + +Um Produto com um mapeamento do JIRA pode enviar Achados para o Jira como Issues usando vários métodos. Você pode enviar Achados individualmente, em massa, como Grupos de Achados, ou automaticamente. + +## Enviar um Único Achado + +1. Abra o Achado que deseja enviar. +2. Clique no **☰ Finding Menu** e selecione **Push to Jira**. +3. Confirme o envio quando solicitado. O DefectDojo criará uma Issue no Jira e a vinculará ao Achado. + +Depois que a Issue for criada, o DefectDojo exibirá um link para a Issue do Jira na página do Achado. + +![image](images/Creating_Issues_in_Jira_2.png) + +Você também pode marcar a caixa de seleção **Push to Jira** ao editar um Achado pelo formulário **Edit Finding**. Quando o Achado for salvo, ele será enviado para o Jira. + +### Atualizando uma Issue do Jira Vinculada + +Se um Achado já tiver uma Issue do Jira vinculada, selecionar **Push to Jira** novamente atualizará a Issue existente no Jira com quaisquer alterações feitas no DefectDojo. Se **Push All Issues** estiver habilitado no Produto, essa sincronização acontece automaticamente. + +### Desvinculando um Achado do Jira + +Para remover a associação entre um Achado e sua Issue do Jira, clique no **☰ Finding Menu** e selecione **Unlink From Jira**. Isso remove o vínculo no DefectDojo, mas não exclui a Issue do Jira em si. + +## Enviar Achados em Massa + +Você pode enviar vários Achados para o Jira de uma vez usando o formulário **Bulk Update**: + +1. Em uma lista de Achados, selecione os Achados que deseja enviar usando as caixas de seleção. +2. Abra o formulário **Bulk Update**. +3. Em **Jira Settings**, marque a caixa de seleção **Push to Jira**. +4. Clique em **Submit**. + +Os Achados selecionados serão colocados na fila para envio ao Jira. O DefectDojo exibirá uma mensagem de confirmação indicando quantos Achados foram enfileirados. + +## Enviar Engajamentos como Epics + +Se **Enable Engagement Epic Mapping** estiver ativado nas **Jira Project Settings**, você pode enviar um Engajamento para o Jira como um Epic. Os Achados do Engajamento serão enviados como Issues filhas dentro desse Epic. + +Para enviar um Engajamento como um Epic: + +1. Abra o Engajamento que deseja enviar. +2. Clique no **☰ Engagement Menu** e selecione **Push to Jira**. +3. Opcionalmente, forneça um **Epic Name** (o padrão é o nome do Engajamento, se deixado em branco) e uma **Epic Priority**. +4. Marque **Push to Jira (Create Epic)** e envie o formulário. + +## Enviar Grupos de Achados como Issues do Jira + +Se você tiver Finding Groups habilitados, pode enviar um Grupo de Achados para o Jira como uma única Issue, em vez de Issues separadas para cada Achado. + +Para enviar um Grupo de Achados: + +1. Abra o Finding Group. +2. Clique no **☰ Finding Group Menu** e selecione **Push to Jira**, ou marque a caixa de seleção **Push to Jira** ao editar o Finding Group. + +A Issue do Jira associada a um Grupo de Achados deve ser excluída diretamente na instância do Jira, caso a remoção seja necessária. + +### Criar e Enviar Grupos de Achados Automaticamente + +Com **Push All Issues** habilitado no Produto, e uma opção de **Group By** selecionada na importação: + +Desde que os Finding Groups sejam criados com sucesso, é o Grupo de Achados que será enviado automaticamente para o Jira como uma Issue, e não os Achados individuais. + +![image](images/Creating_Issues_in_Jira_4.png) + +## Comportamento de Envio Automático + +O DefectDojo pode enviar Achados e atualizações automaticamente para o Jira em vários cenários: + +### Push All Issues + +Quando a configuração **Push All Issues** está habilitada nas Jira Project Settings de um Produto, o DefectDojo criará automaticamente Issues no Jira para todos os Achados Ativos e Verificados. Isso inclui Achados criados por importação de scan. Depois que uma Issue do Jira é criada, ela continuará sincronizada com o DefectDojo mesmo que o status do Achado mude. + +### Auto-Sincronização em Mudanças de Status + +Quando **Push All Issues** ou a configuração de nível de sistema **Finding Jira Sync** está habilitada, o DefectDojo atualizará automaticamente as Issues do Jira vinculadas quando determinadas ações forem realizadas nos Achados: + +* **Request Review** \- Um comentário é adicionado à Issue do Jira vinculada (ou à Issue do Jira do Finding Group, se o Achado pertencer a um grupo). +* **Clear Review** \- Um comentário é adicionado à Issue do Jira vinculada. +* **Close Finding** \- A Issue do Jira vinculada é atualizada para refletir o fechamento. Se **Push Notes** estiver habilitado, um comentário também é adicionado. + +## Comentários e Notas do Jira + +Quando **Push Notes** está habilitado nas Jira Project Settings: + +* Se um comentário for adicionado a uma Issue do Jira, o mesmo comentário será adicionado ao Achado, na seção **Notes**. +* Da mesma forma, se uma Nota for adicionada a um Achado, a Nota será adicionada à issue do Jira como um comentário. + +## Mudanças de Status no Jira + +A configuração da Jira Instance tem entradas para duas Jira Transitions que acionarão uma mudança de status em um Achado. + +* Quando a **'Close' Transition** é executada no Jira, o Achado associado também será fechado, e ficará marcado como **Inactive** e **Mitigated** no DefectDojo. O DefectDojo registrará essa mudança na página do Achado, no campo **Mitigated By**. +​ +![image](images/Creating_Issues_in_Jira_3.png) + +* Quando a **'Reopen' Transition** é executada na Issue do Jira, o Achado associado será definido como **Active** no DefectDojo, e perderá seu status de **Mitigated**. + +## Mapeando Resoluções do Jira para Aceitação de Risco / Falso Positivo + +A configuração da Jira Instance inclui dois campos opcionais que permitem mapear uma **Resolution** do Jira para um status de Achado no DefectDojo: + +* **Risk Accepted Finding Mapping Resolution** — quando uma issue do Jira é fechada com essa Resolution, o Achado vinculado se torna Risco Aceito no DefectDojo. +* **False Positive Finding Mapping Resolution** — quando uma issue do Jira é fechada com essa Resolution, o Achado vinculado se torna Falso Positivo no DefectDojo. + +### Status vs Resolution: um Ponto Comum de Confusão + +Esses campos mapeiam a **Resolution** do Jira, não o **Status** do Jira. Status e Resolution são dois conceitos independentes no Jira: Status descreve em que ponto do fluxo de trabalho a issue está (Open, In Progress, Done), enquanto Resolution descreve como ela foi resolvida (Fixed, Won't Do, Duplicate, False Positive, etc.). + +### Pré-requisito: uma pós-função "Set issue resolution" na transição do fluxo de trabalho do Jira + +O motor de fluxo de trabalho do Jira não preenche o campo Resolution automaticamente. Cada transição que deve fechar uma issue com uma Resolution específica precisa de uma pós-função **Set issue resolution** configurada na própria transição. Sem essa pós-função, a issue passa para o novo Status, mas a Resolution permanece em branco, e o mapeamento do DefectDojo não tem com o que fazer a correspondência. + +Um administrador do Jira pode adicionar essa pós-função em **Project Settings → Workflows → (edit workflow) → (selecione a transição de fechamento) → Post Functions → Add post function → Set issue resolution**. + +# Custom Fields no Jira + +Atualmente, o DefectDojo não oferece suporte para passar informações específicas de uma Issue para esses Custom Fields \- esses campos precisarão ser atualizados manualmente no Jira depois que a issue for criada. Cada Custom Field só será criado a partir do DefectDojo com um valor padrão. + + O Jira Cloud agora permite criar um valor padrão de Custom Field diretamente no aplicativo. [Consulte a documentação da Atlassian sobre Custom Fields](https://support.atlassian.com/jira-cloud-administration/docs/configure-a-custom-field/) para mais informações sobre como configurar isso. + +Os Jira Issue Types integrados ao DefectDojo (**Bug, Task, Story** e **Epic)** são configurados para funcionar 'prontos para uso'. Os campos de dados no DefectDojo serão mapeados automaticamente para os campos correspondentes no Jira. Por padrão, o DefectDojo atribuirá Priority, Labels e um Reporter a qualquer nova Issue que criar. + +Algumas configurações do Jira exigem que campos personalizados adicionais sejam levados em conta antes que uma issue possa ser criada. Este processo permitirá que você contemple esses custom fields na sua integração DefectDojo \-\> Jira, garantindo que as issues sejam criadas com sucesso. Esses custom fields serão adicionados a todas as chamadas de API enviadas do DefectDojo para uma instância do Jira vinculada. + +Se você ainda não usa Custom Fields no Jira, não há necessidade de seguir este processo. + +1. Registrar os nomes dos seus Custom Fields no Jira (**Jira UI**) +2. Determinar os valores de Key para os novos Custom Fields (Jira Field Spec Endpoint) +3. Localizar os dados aceitáveis para cada Custom Field, usando os valores de Key como referência (Jira Issue Endpoint) +4. Criar um bloco JSON de referência de campos para rastrear todas as Keys dos Custom Fields e os dados aceitáveis (Jira Issue Endpoint) +5. Armazenar o bloco JSON no Product do DefectDojo associado, para permitir que os Custom Fields sejam criados a partir do Jira (DefectDojo UI) +6. Testar seu trabalho e garantir que todos os dados obrigatórios estejam fluindo corretamente a partir do Jira + +#### Etapa 1: Registre os nomes dos seus Custom Fields no Jira + +O Jira oferece suporte a uma variedade de Context Fields diferentes, incluindo Date Pickers, Custom Labels, Radio Buttons. Cada um desses Context Fields terá um valor de Key diferente, que pode ser encontrado na API do Jira. + +Anote os nomes de cada Custom Field necessário, pois você precisará pesquisar na API do Jira para encontrá-los na próxima etapa. + +**Exemplo de uma lista de Custom Fields (os nomes dos seus Custom Fields serão diferentes):** + +* DefectDojo Custom URL Field +* Outro exemplo de Custom Field +* ... + +#### Etapa 2: Encontrando os Valores de Key dos seus Jira Custom Fields + +Comece este processo navegando até a URL de Field Spec da sua instância inteira do Jira. + +Aqui está um exemplo de uma URL de Field Spec: + +`https://yourcompany-example.atlassian.net/rest/api/2/field` + +A API retornará uma longa string de JSON, que deve ser formatada em texto legível (usando um editor de código, uma extensão de navegador ou ). + +O JSON retornado por essa URL conterá todos os seus custom fields do Jira, a maioria dos quais é irrelevante para o DefectDojo e tem valores `"Null"`. Cada objeto nessa resposta da API corresponde a um campo diferente no Jira. Você precisará procurar os objetos cujos atributos `"name"` correspondam aos nomes de cada Custom Field que você criou na Jira UI, e então anotar o valor do atributo "key" deles. + +![image](images/Using_Custom_Fields.png) + +Depois de encontrar o objeto correspondente na saída JSON, você pode determinar o valor de "key" \- neste caso, é `customfield_10050`. + +O Jira gera valores de key diferentes para cada Custom Field, mas esses valores de key não mudam depois de criados. Se você criar outro Custom Field no futuro, ele terá um novo valor de key. + +**Expandindo nossa lista de Custom Fields:** + +* "DefectDojo Custom URL Field" \= customfield\_10050 +* "Outro exemplo de Custom Field" \= customfield\_12345 +* ... + +#### Etapa 3 \- Encontrando os Custom Fields em uma Jira Issue + +Localize uma Issue no Jira que contenha os Custom Fields que você registrou na Etapa 2\. Copie a Issue Key do título (deve se parecer com "`EXAMPLE-123`") e navegue até a seguinte URL: + +`https://yourcompany-example.atlassian.net/rest/api/2/issue/EXAMPLE-123` + +Isso retornará outra string de JSON. + +Como antes, a saída da API conterá muitos parâmetros de objeto `customfield_##` com valores `null` \- esses são custom fields que o Jira adiciona por padrão, que não são relevantes para essa issue. Ela também conterá valores `customfield_##` que correspondem aos valores de Key dos Custom Fields que você encontrou na etapa anterior. Diferente da saída do Field Spec, você não verá nomes identificando nenhum desses custom fields, e é por isso que você precisou registrar os valores de key na Etapa 2\. + +![image](images/Using_Custom_Fields_2.png) + +**Exemplo:** +Sabemos que `customfield_10050` representa o DefectDojo Custom URL Field porque o registramos na Etapa 2\. Agora podemos ver que `customfield_10050` contém o valor `"https://google.com"` na issue `EXAMPLE-123`. + +#### Etapa 4 \- Criando uma Referência de Campos JSON a partir de cada Jira Custom Field Key + +Agora você precisará pegar o valor de cada um dos Custom Fields da sua lista e armazená-los em um objeto JSON (para usar como referência). Você pode ignorar quaisquer Custom Fields que não correspondam à sua lista. + +Esse objeto JSON conterá todos os valores padrão para novas Issues do Jira. Recomendamos usar nomes que sejam fáceis para sua equipe reconhecer como valores 'padrão' que precisam ser alterados: '`change-me.com`', '`Change this paragraph.`' etc. + +**Exemplo:** + +Da etapa 3, agora sabemos que o Jira espera uma string de URL para "`customfield_10050`". Podemos usar isso para construir nosso objeto JSON de exemplo. + +Digamos que também tivéssemos localizado um campo de texto curto relacionado ao DefectDojo, que identificamos como "`customfield_67890`". Nós observaríamos esse campo na nossa segunda saída de API, veríamos o valor associado, e referenciaríamos o valor armazenado no nosso objeto JSON de exemplo também. +​ +Seu objeto JSON começará a ficar assim, à medida que você adiciona mais Custom Fields a ele. + +``` +{ + "customfield_10050": "https://change-me.com", + "customfield_67890": "This is the short text custom field." +} +``` + +Repita esse processo até que todos os custom fields relevantes do DefectDojo no Jira tenham sido adicionados à sua Referência de Campos JSON. + +#### Tipos de Dados e Sintaxe do Jira + +Alguns campos, como campos de Date, podem estar relacionados a múltiplos custom fields no Jira. Se for esse o caso, você precisará adicionar ambos os campos à sua Referência de Campos JSON. + +``` + "customfield_10040": "1970-01-01", + "customfield_10041": "1970-01-01T03:30:00.000+0200", +``` + +Outros campos, como o campo Label, podem ser rastreados como uma lista de strings \- certifique-se de que sua Referência de Campos JSON use um formato que corresponda à saída da API do Jira. + +``` +// a list of custom labels on a Jira object + "customfield_10042": [ + "custom-label-one", + "this-is-default", + "change-me-please" + ], +``` + +Outros custom fields podem conter informações contextuais adicionais que devem ser removidas da Referência de Campos. Por exemplo, o Custom Multichoice Field contém um bloco extra na saída da API, que você precisará remover, pois esse bloco armazena o valor atual do campo. + +* você deve remover o objeto extra deste campo: + +``` +"customfield_10047": [ + { + "value": "A" + }, + { + "self": "example.url...", + "value": "C", + "id": "example ID" + } +] +``` +* em vez disso, você pode reduzir isso para o seguinte e desconsiderar a segunda parte: + +``` +"customfield_10047": [ + { + "value": "A" + } +] +``` + +#### Exemplo de Referência de Campos Completa + +Aqui está uma Referência de Campos JSON completa, com comentários inline explicando a que cada custom field se refere. Isso serve como um exemplo abrangente. Seu JSON conterá valores de key e dados diferentes, dependendo dos Custom Values que você deseja usar durante a criação da issue. + +``` +{ + "customfield_10050": "https://change-me.com", + + "customfield_10049": "This is a short text custom field", + +// two different fields, but both correspond to the same custom date attribute + "customfield_10040": "1970-01-01", + "customfield_10041": "1970-01-01T03:30:00.000+0200", + +// a list of custom labels on a Jira object + "customfield_10042": [ + "custom-label-one", + "this-is-default", + "change-me-please" + ], + +// custom number field + "customfield_10043": 0, + +// custom paragraph field + "customfield_10044": "This is a very long winded way to say CHANGE ME PLEASE", + +// custom radio button field + "customfield_10045": { + "value": "radio button option" + }, + +// custom multichoice field + "customfield_10047": [ + { + "value": "A" + } + ], + +// custom checkbox field + "customfield_10039": [ + { + "value": "A" + } + ], + +// custom select list (singlechoice) field + "customfield_10048": { + "value": "1" + } +} +``` + +#### Etapa 5 \- Adicionando os Custom Fields a um Product do DefectDojo + +Agora você pode adicionar esses custom fields ao Product associado no DefectDojo, na página Jira Project Settings (acessível pelo menu ⚙️ Engrenagem no Product). Cole a Referência de Campos JSON como texto simples na caixa **Custom Fields** e salve. + +#### Etapa 6 \- Testando seus Jira Custom Fields a partir de um novo Achado: + +Agora, quando você criar um novo Achado no Product associado ao Jira, o Jira criará automaticamente todos esses Custom Fields de acordo com o bloco JSON contido nele. Esses Custom Fields serão criados com os valores padrão ("change\-me\-please", etc.). + +Dentro do Product no DefectDojo, navegue até a página Findings \> Add New Finding. Certifique-se de que o Achado esteja Active e Verified para garantir que ele seja enviado ao Jira, e então confirme, no lado do Jira, que os Custom Fields foram criados com sucesso, sem inconsistências. diff --git a/docs/content/connectors/downstream/PRO__jira_guide.zh-hans.md b/docs/content/connectors/downstream/PRO__jira_guide.zh-hans.md new file mode 100644 index 0000000000..f75ac46f3a --- /dev/null +++ b/docs/content/connectors/downstream/PRO__jira_guide.zh-hans.md @@ -0,0 +1,786 @@ +--- +title: Jira（旧版） +description: 使用 Jira 集成 +weight: 1 +audience: pro +aliases: +- /zh-hans/issue_tracking/jira/pro__jira_guide/ +- /zh-hans/en/share_your_findings/jira_guide +--- + +> **本页介绍的是旧版 Jira 集成。** 这里所述的按产品配置的 Jira 集成已被 **[Jira 下游连接器](/connectors/downstream/about/)** 取代；该连接器目前已在每个 DefectDojo Pro 实例上全面提供，是将发现项推送到 Jira 的推荐方式。因此，在 Pro 侧边栏中，**Connect > Jira** 带有 `LEGACY` 徽章——详见[菜单徽章](/navigation/pro__menu_badges/)。 +> +> **如果您是第一次配置 Jira，请从 [下游连接器](/connectors/downstream/about/) 开始，而不是本指南。** +> +> **已经在使用旧版集成？** DefectDojo Pro 提供内置的迁移功能，可将您现有的经典 Jira 配置迁移到下游连接器，其中包括已经推送过的工单——详见下文的[迁移到 Jira 下游连接器](#migrating-to-the-jira-downstream-connector)。 +> +> 旧版集成会继续正常运作，本指南的内容对其仍然准确适用。 + +DefectDojo 的 Jira 集成可用于将发现项数据推送到一个或多个 Jira Space。这样一来，您就可以将 DefectDojo 整合到标准的开发工作流程中。下面是几个具体的应用示例： + +* AppSec 团队可以有选择地将发现项推送到开发人员使用的 Jira Space，从而使问题修复工作能够与日常开发工作一起得到合理的优先级排序。使用该看板的开发人员无需访问 DefectDojo——他们可以将所有工作都集中在一个地方进行。 +* DefectDojo 可以将所有发现项推送到 AppSec 团队使用的双向同步 Jira Space，从而让团队能够分工进行问题验证。该看板会与 DefectDojo 保持同步，并支持复杂的修复工作流程。 +* DefectDojo 可以有选择地将来自不同产品和/或测试活动的发现项推送到不同的 Jira Space，从而使每项内容都保持在恰当的上下文中。 + +## 迁移到 Jira 下游连接器 + +DefectDojo Pro 可以自动将您现有的经典 Jira 配置转换为下游连接器配置，无需您手动重新搭建。 + +**入口位置：** 前往 **Connect \> Downstream** 打开**下游连接器**页面，然后使用 **Classic Jira Migration** 卡片。点击 **Migrate from classic Jira**，然后确认。 + +只有在存在待迁移的经典 Jira 配置，或存在需要报告的历史运行记录时，该卡片才会出现——因此从未使用过经典 Jira 的实例不会看到它。全部迁移完成后，卡片仍会保留，但按钮会被禁用，因为已经没有可执行的操作。 + +运行迁移需要具备**全局 Maintainer 级别权限**（具体而言，是编辑集成的权限），并且必须在已登录的浏览器会话中执行——无法通过 API 令牌来驱动。 + +### 已推送的工单会发生什么变化 + +**您现有的 Jira 工单会被保留并重新关联——不会成为孤立工单，连接器也不会重复创建。** 每一个此前已由经典 Jira 推送过的发现项都会保留其原有工单，此后由连接器接管，就地更新同一张工单。发现项组上的关联链接也会以同样的方式延续下来。 + +唯一的例外是**测试活动 Epic**。下游连接器没有 Epic 的概念，因此 Epic 工单会在迁移的警告信息中列出，并保持不变。 + +### 迁移的内容 + +* 您的 Jira**实例**连接——包括 URL 和凭据——会成为一个下游连接器集成实例，并保留其原有名称。 +* **严重程度映射**和**状态映射**（即您的打开与关闭转换键）都会被迁移过去。 +* 每个 **Jira Project** 配置都会成为一个工单跟踪器映射，保留其项目密钥和问题类型，并仍然分配给原来的产品或测试活动。 +* **Push All Issues** 设置会被保留：原先启用该设置的项目会继续自动推送。 +* **自定义字段**、**关闭/重新打开转换字段**、**组件**、**默认经办人**以及**标签**都会被转换为字段映射。如果您此前使用过 *Add Vulnerability Id as a Jira label*，它也会被转换为一个标签映射。 +* **自定义 Issue 模板**目录会成为一个工单模板。标准模板不会被复制，因为连接器本身已经内置了相应的等效模板。 + +### 不会被迁移的内容 + +这些内容会在迁移运行时以警告形式报告——但不会中止迁移。请在结果中查找*"连接器无法迁移的内容"*列表。 + +* **Jira → DefectDojo 反向同步。** 这是最重要的一点。下游连接器不会将 Jira 中的更改*反向*同步回来，因此那些根据 Jira 的解决方案（resolution）将发现项状态设置为风险接受或误报的解决方案映射不会被迁移。**如果您依赖反向同步功能，请保留经典 Jira 实例的现有配置**——迁移不会将其移除。 +* **测试活动 Epic 映射**——连接器没有 Epic 的概念。 +* **推送备注**、**SLA 通知评论**以及**风险接受到期评论**——连接器不会将这些内容发布到 Jira。 +* 名为 `summary`、`description`、`project`、`issuetype` 或 `status` 的自定义字段——这些名称已被连接器保留，使用其中任何一个的字段映射都会被跳过。 +* 超过 512 个字符的自定义字段值——会被跳过，而不是截断。 +* 未关联任何产品或测试活动的 Jira Project 不会产生任何分配。 + +### 迁移后经典集成会发生什么 + +**不会出现重复推送。** 对于每一个被迁移的 project，迁移过程都会关闭该经典 Jira project，此后只有连接器会继续推送。您无需手动禁用任何内容。 + +您的经典配置会**被保留，而不是删除**——实例、project 和 issue 记录都会完整保留，只是推送设置会被关闭。这是有意为之的设计：正是这一点使得该变更可以撤销，也正是这一点让反向同步在您依赖它时能够继续正常工作。 + +**如需回滚**，请重新启用经典 Jira project 设置，并移除迁移过程创建的连接器配置。目前没有一键撤销功能。 + +**重复运行是安全的。** 迁移过程会记录已经转换过的内容，并在第二次运行时跳过这些内容，因此不会产生重复项。如果某个 project 或实例迁移失败，其余部分仍会继续完成迁移——迁移失败的 project 会继续在经典集成上运行，而不会被关闭，因此在您排查问题期间，它仍能正常工作。 + +### 运行期间 + +迁移过程会在后台运行，并随时报告进度。完成后，您会收到一份汇总信息——包括创建了多少个连接器、映射、分配、模板和工单链接，关闭了多少个经典 project，以及跳过了哪些内容——同时附带上文所述的各类警告。同一时间只能运行一个迁移任务。 + +# 配置 Jira + +配置 Jira 需要完成以下步骤： +1. 在 System Settings 中启用 Jira 集成。在启用之前，DefectDojo 中其余的 Jira 相关设置都会处于隐藏状态。 +2. 使用用户名/密码或 API 令牌连接一个 Jira 实例。可以关联多个实例。 +3. 将该 Jira 实例添加到 DefectDojo 内的一个或多个产品或测试活动。 +4. 如果您希望使用双向同步，请创建一个 Jira Webhook，用于向 DefectDojo 发送更新。 + +## 步骤 1：在 System Settings 中启用 Jira 集成 + +Jira 集成默认处于关闭状态，在关闭期间，DefectDojo 会隐藏界面中所有其他 Jira 相关控件。这是需要配置的第一项内容：在启用之前，下面的所有步骤都无法使用。 + +在集成被禁用期间，侧边栏中不会出现 **Jira Instances** 条目，因此也就没有地方可以添加 Jira 实例： + +![image](images/jira-menu-hidden-pro.png) + +### 启用集成 + +1. 从 DefectDojo 侧边栏进入 **Settings \> System \> System Settings**。在仍使用先前菜单布局的实例上，该项位于以您的许可证套餐命名的分组下——**Pro Settings** 或 **Enterprise Settings**。参见[设置菜单](/navigation/pro__settings_menu/)。 +​ +2. 在 **Jira Integration Settings** 部分，勾选 **Enable Jira Integration**。 +​ +3. 点击 **Submit**。**Jira Instances** 会立即出现在侧边栏中，无需重新加载页面： + +![image](images/jira-enable-system-settings-pro.png) + +### 该设置会控制哪些内容 + +启用 **Enable Jira Integration** 之后，才会显示其余的 Jira 相关界面。启用后，您将获得： + +* **Jira Instances** 菜单，用于添加和编辑 Jira 实例 +* 资产 ⚙️ 菜单上的 **Jira Project Settings** 页面，以及测试活动上的 Jira 相关设置 +* 发现项和发现项组上的 **Push to Jira** 操作、发现项表单与批量编辑表单中的 Jira 相关字段，以及资产、测试活动、发现项和发现项组列表（包括 CSV 导出）中的 Jira 相关列 + +该设置同样会在界面之外控制集成的启用状态：在关闭期间，DefectDojo 不会将发现项推送到 Jira（包括通过 API 发送的 `push_to_jira` 请求），传入的 Jira Webhook 也会被忽略。 + +**Jira Integration Settings** 中其余的 Jira 相关字段（**Add Vulnerability ID as Jira Label**、**Enable Jira Web Hook**、**Disable Jira Web Hook Secret**、**Jira Web Hook Secret**、**Jira Minimum Severity**）无论集成是开启还是关闭都会保持可见，但在集成启用之前不会产生任何效果。 + +## 步骤 2：连接 Jira 实例 + +启用集成后，连接 Jira 实例是配置 DefectDojo 的 Jira 集成的下一步。请注意，目前尚不支持 Jira Service Management。 + +#### 需要从 Jira 获取的信息 + +Atlassian 在 Jira Cloud 和 Jira Data Center 之间使用不同的身份验证方式。 + +对于 **Jira Cloud**，您需要准备： +* 一个 Jira URL，例如 https://yourcompany.atlassian.net/ +* 一个在您的 Jira 实例中拥有创建和更新 Issue 权限的账户。可以是以下形式之一： + * 标准的**用户名/密码**组合 + * **用户名/API Token** 组合 + +对于 **Jira Data Center（或 Server）**，您需要准备： +* 一个 Jira URL，例如 https://jira.yourcompany.com +* 一个在您的 Jira 实例中拥有创建和更新 Issue 权限的账户。可以是以下形式之一： + * 标准的**用户名/密码**组合 + * **邮箱地址/Personal Access Token** 组合 + +此外，您还可以选择映射： +* 用于触发发现项重新打开和关闭的 Jira Transitions +* 可为发现项应用风险接受和误报状态的 Jira Resolutions（可选） + +只要 DefectDojo 使用的 Jira 账户/令牌拥有在相应 Jira Space 中创建 Issue 的权限，一个 Jira Instance 连接就可以处理多个 Jira Space。 + +### 添加 Jira 实例 + +1. 请确认已按照[步骤 1](#step-1-enable-the-jira-integration-in-system-settings)所述，在 System Settings 中勾选了 **Enable Jira Integration**。在勾选之前，侧边栏不会出现 **Jira Instances** 菜单。 + +2. 从 DefectDojo 侧边栏进入 **Enterprise Settings \> Jira Instances \> + New Jira Instance** 页面。 + +![image](images/jira-instance-beta.png) + +3. 为此 Jira Instance 选择一个 **Configuration Name**，供 DefectDojo 使用。这个名称只是 DefectDojo 中该实例连接的一个标签，不需要与任何 Jira 数据相关联。 + +4. 选择您公司 Jira 实例的 URL——如果您使用的是 Jira Cloud，通常会类似于 `https://**yourcompany**.atlassian.net`。 + +5. 在 Jira 的 Username / Password 字段中填入合适的身份验证方式： + * 若使用标准的**用户名/密码 Jira 身份验证**，请在这些字段中填入 Jira 用户名和对应的密码。 + * 若使用**用户 API token（Jira Cloud）**进行身份验证，请在用户名字段填入用户名，并在密码字段填入对应的 **API token**。 + * 若使用 Jira 的**Personal Access Token（简称 PAT，仅适用于 Jira Data Center 和 Jira Server）**进行身份验证，请在密码字段中填入该 PAT。使用 Jira PAT 进行身份验证时不会用到用户名，但该表单中此字段仍为必填项，因此您可以在此填入一个占位值，用于标识您的 PAT。 + +请注意，与此连接关联的用户必须拥有在您的 Jira 实例中创建 Issue 及访问数据的权限。 + +6. 您需要提供 Epic Name ID、Re-open Transition ID 和 Close Transition ID 的值。这些值之后可以修改。登录 Jira 后，您可以通过以下 URL 获取这些值： +- **Epic Name ID**：访问 `https:///rest/api/2/field` 并搜索 Epic Name。将 `number` 中的数字复制出来并粘贴到这里。如果您的 Jira Space 没有关联 Epic Name ID（例如因为使用的是 Team-Managed Space），请在此字段中填入 0。 +- **Re-open Transition ID**：访问 `https:///rest/api/latest/issue//transitions?expand-transitions.fields` 来查找您 Jira 实例对应的 ID。将其粘贴到 Reopen Transition ID 字段中。 +- **Close Transition ID**：访问 `https:///rest/api/latest/issue//transitions?expand-transitions.fields` 来查找您 Jira 实例对应的 ID。将其粘贴到 Close Transition ID 字段中。 + +7. 选择您希望在 Jira 中创建 Issue 时所使用的 Default issue type。可选项包括标准 Jira issue type 中的**Bug、Task、Story** 和 **Epic**，以及自定义 issue type 中的 **Spike** 和 **Security**。如果您希望使用其他 Issue Type，请联系 [support@defectdojo.com](mailto:support@defectdojo.com) 寻求协助。 + +8. 选择您的 Issue Template，它将决定在 Jira 中创建 Issue 时的 Issue Description。 + +共有两种类型： +- **Jira\_full**，会在 Jira Issue 中包含全部发现项信息 +- **Jira\_limited**，只会包含少量发现项信息和元数据 + +如果将此字段留空，将默认使用 **Jira\_full。** 如果您需要其他类型的模板，请联系 [support@defectdojo.com](mailto:support@defectdojo.com)。 + +9. 如果需要，可以填写一个 Jira Resolution 的名称，当该 Resolution 在 Issue 上被触发时，会将发现项的状态更改为风险已接受或误报。 + +此时即可提交表单。如果需要，您还可以在 Optional Fields 下进一步自定义您的 Jira 集成。点击该按钮后，您可以为 Jira Issue 添加通用文本，或更改 Jira Severity Mappings 的映射方式。 + +## 步骤 3：将产品或测试活动连接到 Jira + +DefectDojo 中的每个产品或测试活动都拥有各自的设置，用于控制发现项如何转换为 JIRA Issue。您可以在此决定关联的 Jira Space，并设置创建 Issue、Epic、Label 及其他 JIRA 元数据时的默认行为。 + +### 为产品添加 Jira + +点击产品上的齿轮菜单 ⚙️，即可打开 **Jira Project Settings** 页面。 + +![image](images/jira-project-settings.png) + +#### Jira Instance(Jira 实例) + +如果您为组织内不同的产品或团队配置了多个 Jira 实例，可以在此指定您希望 DefectDojo 在哪个 Jira Space 中创建 Issue。请从下拉菜单中选择一个 Space。 + +如果此菜单没有列出任何 Jira 实例，请确认这些 Space 已在 DefectDojo 的全局 Jira Configuration 中完成连接——yourcompany.defectdojo.com/jira。 + +#### Project key(项目密钥) + +这是您希望与 DefectDojo 搭配使用的 Space 的密钥。给定 Space 的 Space Key 可以在 URL 中找到。（此前这被称为 **Jira Project Key**，但自 2025 年 9 月起，Jira 中已将其改称为 **Space Key**。） + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_3.png) + +#### Epic Issue Type Name(Epic Issue 类型名称) + +Jira 中 Epic issue type 的名称。默认值为 "Epic"，如果您的 Jira 实例使用了不同的名称，可以进行修改。 + +#### Issue template(Issue 模板) + +在这里，您可以决定希望向 Jira 发送多少 DefectDojo 元数据。请从以下两个选项中选择一个： + +* **jira\_full**：Issue 会记录来自 DefectDojo 的全部参数——完整的 Description、CVE、Severity 等。如果您需要在 Jira 中呈现完整的发现项上下文（例如处理该 Issue 的人员没有 DefectDojo 访问权限），这个选项会很有用。 + +以下是一个 **jira\_full** Issue 的示例： +​ +![image](images/Add_a_Connected_Jira_Project_to_a_Product_4.png) + +* **Jira\_limited：** Issue 只会记录 DefectDojo 链接、产品/测试活动/测试链接，以及 Reporter 和 Environment 字段。其余所有字段仅在 DefectDojo 中记录。如果您不需要在 Jira 中呈现完整的发现项上下文（例如处理该 Issue 的人员主要在 DefectDojo 中工作，不需要在 JIRA 中也看到完整信息），这个选项会很有用。 + +​以下是一个 **jira\_limited** Issue 的示例： + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_5.png) + +#### Component(组件) + +如果您使用 Component 来管理 Jira Space，可以在此为 DefectDojo 指定合适的 Component。如需指定多个 Component，请输入以逗号分隔的列表（例如 `Security, DevSecOps`）；每个值都会作为一个独立的 component 发送到 Jira。 + +#### Custom fields(自定义字段) + +如果您不需要在 DefectDojo 的 issue 中使用 Custom Fields，可以将此字段保留为 'null'。 + +但是，如果您的 Jira Space Settings **要求您**在新建 Issue 时使用 Custom Fields，则需要对这些映射进行硬编码。 + +请注意，DefectDojo 无法将任何特定于某个 Issue 的元数据作为 Custom Fields 发送，只能发送一个默认值。只有当您的 Jira Space **要求这些 Custom Fields 必须存在**于该 Space 内的每个 Issue 中时，才需要设置此部分。 + +请参照**[本指南](#custom-fields-in-jira)**开始使用 Custom Fields。 + +#### Close / Reopen Transition fields(关闭/重新打开转换字段) + +有些 Jira workflow **要求**在执行 transition 时必须设置某些字段——例如，某些 workflow 会拒绝关闭 Issue，除非在关闭界面提供了 Resolution 和 Justification 字段。上面的 Custom fields 设置只在 Issue *创建*时生效，因此无法满足这类 workflow 的要求。 + +如果没有这些设置，DefectDojo 发送的 close / reopen transition 将不带任何字段。要求必须提供字段的 workflow 会拒绝该 transition，导致发现项和 Jira Issue 失去同步：该发现项在 DefectDojo 中显示为已缓解，而对应的 Issue 在 Jira 中仍保持打开状态。 + +**Close Transition fields** 和 **Reopen Transition fields** 设置接受一个 JSON 对象，该对象会作为 close / reopen transition 调用的 `fields` 载荷发送。例如，要以 *Won't Fix* 的 Resolution 外加一个 justification 值来关闭 Issue： + +```json +{ + "resolution": {"name": "Won't Fix"}, + "customfield_10200": "Risk accepted by security team #report-false-positive" +} +``` + +如果您的 Jira workflow 在 transition 时不需要任何字段，请将这些设置保留为 'null'。 + +**您需要哪些字段？** + +* 请向您的 Jira 管理员确认，close / reopen 的**transition 界面**上有哪些字段，其中哪些是由 validator 强制要求的。所配置的 JSON 必须满足**每一个**必填字段：只要载荷中缺少任意一个必填字段，Jira 就会拒绝整个 transition，不会设置任何内容——只提供部分必填字段并无帮助。 +* 反过来，字段必须**出现在该 transition 界面上**才能被发送：对于尝试设置该 transition 界面上不存在的字段的 transition，Jira 会予以拒绝。 +* 对于使用 Jira Cloud 当前 workflow 编辑器构建的 workflow，当 Issue 进入 done 类别的状态时，Jira 会自动填入站点默认的 Resolution。因此，仅仅要求填写 Resolution 并不会阻止这里的普通 transition，此时在该载荷中使用 `"resolution"` 的实际作用，是选择一个*有意义*的值（例如 *False Positive*），而不是使用站点默认值。使用经典编辑器或 marketplace validator 应用构建的 workflow，仍可能会硬性要求填写 Resolution。 +* Reopen transition 通常会通过 workflow 本身清除 Resolution，因此 **Reopen Transition fields** 通常只需要填写您的 workflow 所要求的自定义字段即可。 + +**说明：** + +* 对于某个产品或测试活动，*每一次* close（或 reopen）transition 发送的都是同一份 JSON——这些值是固定的，不会因发现项而异。如果您需要针对不同的处理结果使用不同的字段（例如，误报的发现项和已修复的发现项需要使用不同的 Resolution），请使用支持按状态配置 transition 字段映射的 DefectDojo Pro Jira Integrator。 +* 值的格式与 Jira REST API 所使用的格式相同：文本字段使用字符串，resolution 使用 `{"name": ...}`，多选字段使用 `[{"name": ...}]`，依此类推。 +* 如果此前因为这些设置缺失或不完整而导致 transition 被拒绝，只要修正这些设置，就能修复由此产生的偏差：该发现项下一次状态推送时，会使用配置好的字段重新尝试该 transition。 +* 这两项设置在 `/api/v2/jira_projects/` REST 接口（`close_transition_fields` / `reopen_transition_fields`）中同样可用，因此也可以通过 API 进行管理。 +* 当 DefectDojo 因为某个发现项被**删除**而关闭对应的 Issue 时，同样会应用这些字段——这些值会在关闭操作被加入队列的那一刻被捕获。 + +#### Jira labels(Jira 标签) + +选择您希望在 Jira 中创建 Issue 时附带的相关 label，例如 **DefectDojo**、**YourProductName..** + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_6.png) + +#### Default assignee(默认经办人) + +在 Jira 中默认经办人的名称。如果留空，DefectDojo 在创建 Issue 时将遵循您 Jira Space 中的默认行为。 + +### Jira Project Settings + +#### Enabled(启用) + +此开关用于控制 DefectDojo 是否为该产品将发现项推送到 Jira。关闭此开关不会删除或更改 DefectDojo 已创建的任何现有 Jira 工单，但会阻止后续的更新以及新 Issue 的创建。 + +只有在没有创建任何相关 Issue 的情况下，才能从您的实例中移除 Jira 集成。如果已经创建了 Issue，则无法从 DefectDojo 中完全移除某个 Jira Instance。 + +#### Add Vulnerability Id as a Jira label(将漏洞 ID 添加为 Jira 标签) + +此选项可让您自动将漏洞 ID 数据添加为 Jira Label。漏洞 ID 是由各安全工具添加到发现项上的——它们可能是 Common Vulnerabilities and Exposures（CVE）ID，也可能是特定于报告该发现项的工具的其他格式。 + +#### Push All Issues(推送所有问题) + +勾选后，DefectDojo 会自动将所有活动且已验证的发现项作为 Issue 推送到 Jira。如果不勾选，则所有发现项都需要手动推送到 Jira（可逐个推送，也可批量推送）。 + +启用此设置后，即使发现项的状态发生变化，Jira Issue 也会持续与 DefectDojo 保持同步。 + +#### Enable Engagement Epic Mapping(启用测试活动 Epic 映射) + +在 DefectDojo 中，测试活动代表一组工作。每个测试活动包含一个或多个测试，每个测试又包含一个或多个需要缓解的发现项。Jira 中的 Epic 与此类似，此复选框可让您将测试活动作为 Epic 推送到 Jira。 + +* DefectDojo 中的一个测试活动——请注意底部列出的三个发现项。 +​ +![image](images/Add_a_Connected_Jira_Project_to_a_Product_8.png) +* 同一个测试活动推送到 JIRA 后如何变为一个 Epic——该测试活动的发现项也会一并推送，并作为 Child Issue 存在于该测试活动内部。 + +![image](images/Add_a_Connected_Jira_Project_to_a_Product_9.png) + +#### Push Notes(推送备注) + +启用后，Jira 上的 comment 会填充到 DefectDojo 中对应发现项的备注下；反之亦然——发现项上的备注也会作为 comment 添加到对应的 Jira Issue 上。 + +#### Send SLA Notifications As Comments(以评论形式发送 SLA 通知) + +启用后，任何违反 DefectDojo Service Level Agreement 规则的 Issue，都会在对应的 Jira issue 上添加相应的 comment 予以说明。这些 comment 会每天发布一次，直到该 Issue 被解决为止。 + +Service Level Agreement 可以在 DefectDojo 的 **Configuration \> SLA Configuration** 下进行配置，并分配给每个产品。 + +#### Send Risk Acceptance Expiration Notifications As Comment(以评论形式发送风险接受到期通知) + +启用后，只要某个 Issue 关联的 DefectDojo 风险接受到期，就会在对应的 Jira issue 上添加一条 comment 予以说明。这些 comment 会每天发布一次，直到该 Issue 被解决为止。 + +### 测试活动级别的 Jira 设置 + +默认情况下，测试活动会**从其所属产品继承 Jira 设置**。不过，您也可以针对单个测试活动覆盖这些 Jira 设置。 + +如需访问测试活动级别的 Jira 设置，请点击某个测试活动上的齿轮菜单 ⚙️，打开 **Jira Project Settings** 页面。 + +在此，您可以取消勾选 **Inherit from Product**，并为以下设置提供该测试活动专属的值：**Project Key**、**Issue Template, Custom Fields, Jira Labels, Default Assignee** 等。 + +请注意，一旦某个测试活动被分配了自己的 Jira project，它就无法再从产品继承设置。 + +![image](images/Creating_Issues_in_Jira_5.png) + +## 步骤 4:配置双向同步:Jira Webhook + +Jira 集成支持通过 Webhook 进行双向同步。DefectDojo 会在一个唯一的地址接收 Jira 通知,根据您的配置,这既可以让 Jira 中的评论同步到发现项,也可以让发现项通过 Jira 得到解决。 + +### 查找您的 Jira Webhook URL + +您的 Jira Webhook 位于系统设置表单中的 **Jira 集成设置**下:即侧边栏中的 **企业设置 \> 系统设置**。 + +在 DefectDojo 处理传入的 Jira 通知之前,您还需要在同一页面上勾选 **启用 Jira Webhook**。 如果该复选框或 **启用 Jira 集成**(参见[步骤 1](#step-1-enable-the-jira-integration-in-system-settings))未勾选,传入的 Webhook 都会被忽略。 + +![image](images/Configuring_the_Jira_DefectDojo_Webhook.png) + +### 创建 Jira Webhook + +1. 访问 `**https:// \ /plugins/servlet/webhooks**` +2. 点击 'Create a Webhook'。 +3. 对于标记为 'URL' 的字段,请输入:`https:// \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>`。Web Hook 密钥已在上文所述的 Jira 集成设置中列出。 +4. 在 'Comments' 下启用 'Created'。在 Issue 下启用 'Updated'。 +5. 请确保您的 JIRA 实例信任 DefectDojo 实例所使用的 SSL 证书。对于 JIRA Cloud,DefectDojo 必须使用[由全球可信证书颁发机构签发的有效 SSL/TLS 证书](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-registering-webhooks-with-non-secure-urls/) + +请注意,您无需在 Jira 中创建密钥即可使用此 Webhook。该密钥已内置于 DefectDojo 的 URL 中,因此只需将完整的 URL 添加到 Jira Webhook 表单中即可。 + +传入的 Webhook 请求通过该 URL 中的密钥进行身份验证,因此请将完整 URL 视为凭据并妥善保密。 + +#### 测试 Webhook + +在您根据 DefectDojo 发现项创建了一个或多个 Issue 后,您可以通过向其中一个发现项添加评论来测试该 Webhook。此评论应会被 Jira Webhook 作为备注接收。 + +如果此操作无法正常工作,可能是您的 Jira 实例上存在防火墙问题,阻止了该 Webhook。 + +* DefectDojo 的防火墙规则中包含一个 **Jira Cloud** 复选框,必须先启用该复选框,DefectDojo 才能接收来自 Jira 的 Webhook 消息。 + +### 备选方案:使用 Jira Automation(Send web request) + +某些 Jira 实例不允许在 `/plugins/servlet/webhooks` 下使用系统 Webhook —— 例如该管理区域受限,只允许使用 **Jira Automation** 规则时。在这种情况下,您可以使用 Automation 的 **Send web request** 操作来实现相同的双向同步,该操作会向同一个 DefectDojo Webhook 端点发送请求。 + +DefectDojo 的 Webhook 端点接受任何带有 `Content-Type: application/json` 的 HTTP `POST` 请求,只要 URL 路径中包含有效的密钥即可。它**并不**要求请求必须源自 Jira 的系统 Webhook 机制,因此 Automation 的 "Send web request" 操作可以作为替代方案直接使用。 + +#### 前提条件 + +与系统 Webhook 相同的前提条件同样适用: + +* 在 ⚙️ **配置 \> 系统设置** 页面上,**启用 JIRA 集成** 和 **启用 JIRA Webhook** 均已勾选。 +* 该页面上已设置了非空的 **Jira webhook 密钥**。该密钥只能包含字符 `A-Z`、`a-z`、`0-9`、`_` 和 `-`。 +* 该发现项(或发现项组)已经关联到对应的 Jira issue。如果该 issue 未关联到任何 DefectDojo 发现项,请求仍会被接受(HTTP `200`),但不会执行任何操作。 + +#### DefectDojo 如何处理该请求 + +* DefectDojo 会根据顶层的 `webhookEvent` 字段进行分支处理。只有 `"jira:issue_updated"` 和 `"comment_created"` 会被处理;其他任何值都会被接受但忽略。Automation **不**会自动添加此字段,因此您必须自行将其包含在请求正文中。 +* 正因如此,请将请求的 **Body** 设置为 **Custom data**,并提供下方的 JSON。**Empty** 和 **Jira issue data** 这两个正文选项不包含所需的 `webhookEvent` 字段,因此 DefectDojo 会忽略它们。 +* 该端点始终返回 HTTP `200`,无论更新是否实际生效。成功或失败只能在响应正文和 DefectDojo 日志中查看——Automation 审计日志中的 `200` 本身并**不**能确认更新已到达某个发现项。 + +#### 规则 1 —— Issue 已更新 + +创建一条 Automation 规则,内容如下: + +* **Trigger:** *Issue transitioned*(或其他会在您同步的字段发生变化时触发的触发器,例如 Status 上的 *Field value changed*)。 +* **Action:** *Send web request* + * **Web request URL:** `https:///jira/webhook/` + * **HTTP method:** `POST` + * **Web request body:** *Custom data* + * **Headers:** `Content-Type: application/json` + * **Custom data:** + +```json +{ + "webhookEvent": "jira:issue_updated", + "issue": { + "id": "{{issue.id}}", + "fields": { + "updated": "{{issue.updated}}", + "resolution": null, + "status": { "statusCategory": { "key": "{{issue.status.statusCategory.key}}" } }, + "assignee": { "name": "{{issue.assignee.accountId}}", "displayName": "{{issue.assignee.displayName}}" } + } + } +} +``` + +Issue 更新的约束条件: + +* `issue.id` 必须是 **Jira issue 的数字内部 ID**(`{{issue.id}}`),而不是 issue key(例如 `PROJ-123`)。DefectDojo 会通过这个数字 ID 将更新与某个发现项进行匹配。 +* `resolution` 和 `updated` 字段必须始终存在。`resolution` 可以为 `null`,但只要有任一字段缺失,请求就会被接受(`200`)但被静默忽略,不会被处理。 +* 状态同步和自动缓解由 `status.statusCategory.key` 驱动,其 Jira 取值为 `new`(To Do)、`indeterminate`(In Progress)和 `done`(Done)。只有当 issue 被真正关闭时,发现项才会被标记为已缓解,而不仅仅是因为存在某个 resolution 值。 + +#### 规则 2 —— Issue 已评论 + +再创建第二条 Automation 规则,内容如下: + +* **Trigger:** *Issue commented* +* **Action:** *Send web request* —— URL、方法、请求头以及 *Custom data* 正文选项均与规则 1 相同,正文如下: + +```json +{ + "webhookEvent": "comment_created", + "comment": { + "self": "https:///rest/api/2/issue/{{issue.id}}/comment/{{comment.id}}", + "body": "{{comment.body}}", + "updateAuthor": { "name": "{{comment.author.accountId}}", "displayName": "{{comment.author.displayName}}" } + } +} +``` + +评论的约束条件: + +* `body` 和 `updateAuthor` 必须都存在。 +* DefectDojo 会从 `comment.self` URL 中推导出目标 issue —— 具体来说是 `.../issue//comment/...` 部分中的 ``—— 因此 `{{issue.id}}`(数字 ID)必须出现在其中。 +* **循环预防:** 如果评论作者与 DefectDojo 用于发布自身评论的 Jira 账户相同,DefectDojo 会跳过该评论,以避免出现回音循环。如果您希望**所有**评论都被摄取,请使用与 DefectDojo 的 Jira 实例中配置的账户不同的 Jira 用户来运行该 Automation 规则。 + +#### 关于智能值的说明 + +上面展示的智能值(`{{issue.id}}`、`{{issue.status.statusCategory.key}}`、`{{comment.author.accountId}}` 等)是 Jira Cloud 的标准名称,但在不同实例之间可能会有所差异。在正式上线前,请使用 Automation 的负载预览功能,确认每个智能值都能解析为您期望的结果。 + +## 测试 Jira 集成 + +#### 测试 1:发现项能否成功推送到 Jira? + +为了测试 Jira 集成是否正常工作,您可以在 DefectDojo 中向与 Jira 关联的产品添加一个新的空白发现项。**产品 \> 发现项 \> 新增发现项。** + +填写您想要的标题、严重程度和描述,然后点击 "Finished"。该发现项应会作为一个 Issue 出现在 Jira 中,并带有所有相关的元数据。 + +如果 Jira Issue 没有被正确创建,请检查您的通知中是否存在错误代码。 + +* 请确认与 DefectDojo 的 Jira 配置相关联的 Jira 用户,拥有在该 Jira Space 上创建和更新 issue 的权限。 + +#### 测试 2:Jira Webhook 发送到 DefectDojo + +为了测试 Jira Webhook,请向一个在 JIRA 中也以 Issue 形式存在的发现项添加一条备注(例如上文测试中创建的那个 issue)。 + +如果 Webhook 配置正确,您应该会在 Jira 中看到该备注作为该 issue 的一条评论出现。 + +如果此操作无法正常工作,可能是您的 Jira 实例上存在防火墙问题,阻止了该 Webhook。 + +* DefectDojo 的防火墙规则中包含一个 **Jira Cloud** 复选框,必须先启用该复选框,DefectDojo 才能接收来自 Jira 的 Webhook 消息。 + +## 断开与 Jira 的连接 + +只有在没有创建任何相关 Issue 的情况下,才能从您的实例中移除 Jira 集成。 如果已经创建了 Issue,则无法将某个 Jira 实例从 DefectDojo 中完全移除。 + +不过,您可以通过在产品级别禁用 Jira 集成来关闭它。 在 **Jira 项目设置**页面(可通过产品上的 ⚙️ 齿轮菜单访问)中,取消勾选 **已启用**开关。这不会删除或更改 DefectDojo 已创建的任何现有 Jira 工单,但会停止后续的所有更新。 + +# 将发现项推送到 Jira + +具有 JIRA 映射的产品可以通过多种方式将发现项作为 Issue 推送到 Jira。您可以逐条、批量、以发现项组的方式,或自动地推送发现项。 + +## 推送单个发现项 + +1. 打开您要推送的发现项。 +2. 点击 **☰ 发现项菜单**,然后选择 **推送到 Jira**。 +3. 在提示时确认推送。DefectDojo 将创建一个 Jira Issue 并将其关联到该发现项。 + +Issue 创建后,DefectDojo 会在发现项页面上显示指向该 Jira Issue 的链接。 + +![image](images/Creating_Issues_in_Jira_2.png) + +您也可以在通过 **编辑发现项** 表单编辑某个发现项时,勾选 **推送到 Jira** 复选框。保存该发现项时,它将被推送到 Jira。 + +### 更新已关联的 Jira Issue + +如果某个发现项已经关联了一个 Jira Issue,再次选择 **推送到 Jira** 会用 DefectDojo 中所做的任何更改来更新现有的 Jira Issue。如果产品上启用了 **推送所有 Issue**,这种同步会自动发生。 + +### 取消发现项与 Jira 的关联 + +要移除某个发现项与其 Jira Issue 之间的关联,请点击 **☰ 发现项菜单**,然后选择 **取消与 Jira 的关联**。此操作会移除 DefectDojo 中的关联,但不会删除 Jira Issue 本身。 + +## 批量推送发现项 + +您可以使用批量更新表单一次性将多个发现项推送到 Jira: + +1. 在发现项列表中,使用复选框选择您要推送的发现项。 +2. 打开 **批量更新** 表单。 +3. 在 **Jira 设置** 下,勾选 **推送到 Jira** 复选框。 +4. 点击 **提交**。 + +所选的发现项将被加入 Jira 推送队列。DefectDojo 会显示一条确认消息,说明有多少个发现项已被加入队列。 + +## 将测试活动推送为 Epic + +如果您的 Jira 项目设置中开启了 **启用测试活动 Epic 映射**,您就可以将某个测试活动作为 Epic 推送到 Jira。该测试活动的发现项将作为该 Epic 下的子 Issue 被推送。 + +要将某个测试活动推送为 Epic: + +1. 打开您要推送的测试活动。 +2. 点击 **☰ 测试活动菜单**,然后选择 **推送到 Jira**。 +3. 您可以选择性地提供一个 **Epic 名称**(留空则默认使用测试活动名称)和一个 **Epic 优先级**。 +4. 勾选 **推送到 Jira(创建 Epic)** 并提交表单。 + +## 将发现项组推送为 Jira Issue + +如果您启用了发现项组功能,就可以将一组发现项作为单个 Issue(而不是为每个发现项分别创建 Issue)推送到 Jira。 + +要推送一个发现项组: + +1. 打开该发现项组。 +2. 点击 **☰ 发现项组菜单**,然后选择 **推送到 Jira**,或者在编辑该发现项组时勾选 **推送到 Jira** 复选框。 + +如果需要移除某个发现项组关联的 Jira Issue,必须直接在 Jira 实例中删除。 + +### 自动创建并推送发现项组 + +在产品上启用 **推送所有 Issue**,并在导入时选择了 **分组依据** 选项后: + +只要发现项组被成功创建,自动推送到 Jira 的将是该发现项组本身(作为一个 Issue),而不是各个单独的发现项。 + +![image](images/Creating_Issues_in_Jira_4.png) + +## 自动推送行为 + +DefectDojo 可以在多种场景下自动将发现项和更新推送到 Jira: + +### 推送所有 Issue + +当产品的 Jira 项目设置中启用了 **推送所有 Issue** 时,DefectDojo 会自动为所有活动且已验证的发现项创建 Jira Issue,其中也包括通过扫描导入创建的发现项。Jira Issue 一经创建,即使该发现项的状态发生变化,它也会持续与 DefectDojo 保持同步。 + +### 状态变化时的自动同步 + +当启用了 **推送所有 Issue** 或系统级别的 **发现项 Jira 同步** 设置后,DefectDojo 会在对发现项执行某些操作时,自动更新已关联的 Jira Issue: + +* **请求审查** \- 系统会在已关联的 Jira Issue 上添加一条评论(如果该发现项属于某个发现项组,则添加到该发现项组的 Jira Issue 上)。 +* **清除审查** \- 系统会在已关联的 Jira Issue 上添加一条评论。 +* **关闭发现项** \- 已关联的 Jira Issue 会被更新以反映该关闭状态。如果启用了 **推送备注**,系统还会添加一条评论。 + +## Jira 评论与备注 + +启用 Jira 项目设置中的 **推送备注** 后: + +* 如果在某个 Jira Issue 上添加了一条评论,同样的评论会被添加到该发现项的 **备注** 部分下。 +* 反过来,如果在某个发现项上添加了一条备注,该备注也会作为评论被添加到对应的 Jira issue 上。 + +## Jira 状态变化 + +Jira 实例配置中包含两个 Jira 转换(Transition)条目,它们会触发发现项的状态变化。 + +* 当在 Jira 上执行 **'Close' 转换** 时,相关联的发现项也会随之关闭,并在 DefectDojo 上被标记为 **非活动** 和 **已缓解**。DefectDojo 会在发现项页面的 **缓解方式** 标题下记录此变化。 +​ +![image](images/Creating_Issues_in_Jira_3.png) + +* 当在该 Jira Issue 上执行 **'Reopen' 转换** 时,相关联的发现项会在 DefectDojo 上被设置为 **活动**,并失去其 **已缓解** 状态。 + +## 将 Jira 解决方案映射到风险接受/误报 + +Jira 实例配置包含两个可选字段,可让您将某个 Jira **解决方案(Resolution)** 映射到某个 DefectDojo 发现项状态: + +* **风险已接受发现项映射解决方案** —— 当某个 Jira issue 以此解决方案关闭时,关联的发现项会在 DefectDojo 中变为风险已接受。 +* **误报发现项映射解决方案** —— 当某个 Jira issue 以此解决方案关闭时,关联的发现项会在 DefectDojo 中变为误报。 + +### 状态与解决方案:一个常见的混淆点 + +这些字段映射的是 Jira 的 **解决方案(Resolution)**,而不是 Jira 的 **状态(Status)**。状态和解决方案是两个相互独立的 Jira 概念:状态描述的是该 issue 在工作流中所处的位置(Open、In Progress、Done),而解决方案描述的是它是如何被解决的(Fixed、Won't Do、Duplicate、False Positive 等)。 + +### 前提条件:Jira 工作流转换上的 "Set issue resolution" 后置功能 + +Jira 的工作流引擎不会自动填充 Resolution 字段。 每一个应当以特定解决方案关闭 issue 的转换,都需要在该转换本身上配置一个 **Set issue resolution** 后置功能。如果没有这个后置功能,issue 会转移到新的状态,但 Resolution 会保持为空,DefectDojo 的映射也就没有可匹配的内容。 + +Jira 管理员可以通过 **Project Settings → Workflows →(编辑工作流)→(选择要关闭的转换)→ Post Functions → Add post function → Set issue resolution** 来添加此后置功能。 + +# Jira 中的自定义字段 + +DefectDojo 目前尚不支持将任何 Issue 特定信息传递到这些自定义字段中 \- 这些字段需要在 issue 创建后于 Jira 中手动更新。每个自定义字段在从 DefectDojo 创建时都只会带有一个默认值。 + + Jira Cloud 现已支持直接在应用内创建自定义字段的默认值。有关如何配置此功能的更多信息,请参阅[Atlassian 关于自定义字段的文档](https://support.atlassian.com/jira-cloud-administration/docs/configure-a-custom-field/)。 + +DefectDojo 内置的 Jira Issue 类型(**Bug、Task、Story** 和 **Epic)** 都已配置为可以'开箱即用'。DefectDojo 中的数据字段会自动映射到 Jira 中对应的字段。默认情况下,DefectDojo 会为其创建的任何新 Issue 分配 Priority、Labels 和 Reporter。 + +某些 Jira 配置在创建 issue 之前需要先处理额外的自定义字段。以下流程可让您在 DefectDojo \-\> Jira 集成中处理这些自定义字段,确保 issue 能够成功创建。这些自定义字段会被添加到 DefectDojo 发送给已关联 Jira 实例的所有 API 调用中。 + +如果您尚未在 Jira 中使用自定义字段,则无需遵循此流程。 + +1. 记录您在 Jira 中的自定义字段名称(**Jira UI**) +2. 确定新自定义字段的键值(Jira 字段规范端点) +3. 参照键值,定位每个自定义字段可接受的数据(Jira Issue 端点) +4. 创建一个字段参考 JSON 块,以记录所有自定义字段的键及其可接受的数据(Jira Issue 端点) +5. 将该 JSON 块存储到关联的 DefectDojo 产品中,以便从 Jira 创建自定义字段(DefectDojo UI) +6. 测试您的成果,确保所有必需的数据都能从 Jira 正确地流转过来 + +#### 步骤 1:记录您在 Jira 中的自定义字段名称 + +Jira 支持多种不同的上下文字段,包括日期选择器、自定义标签、单选按钮。每一种上下文字段在 Jira API 中都会有不同的键值。 + +请记下每个所需自定义字段的名称,因为您将需要在下一步中通过 Jira API 搜索它们。 + +**自定义字段列表示例(您的自定义字段名称会有所不同):** + +* DefectDojo Custom URL Field +* Another example of a Custom Field +* ... + +#### 步骤 2:查找您的 Jira 自定义字段键值 + +首先,请导航到您整个 Jira 实例的字段规范 URL。 + +以下是字段规范 URL 的一个示例: + +`https://yourcompany-example.atlassian.net/rest/api/2/field` + +该 API 会返回一长串 JSON,您应将其格式化为可读文本(可使用代码编辑器、浏览器扩展,或 )。 + +该 URL 返回的 JSON 会包含您所有的 Jira 自定义字段,其中大多数与 DefectDojo 无关,其值为 `"Null"`。此 API 响应中的每个对象都对应 Jira 中的一个不同字段。您需要查找那些 `"name"` 属性与您在 Jira UI 中创建的每个自定义字段名称相匹配的对象,然后记下它们的 "key" 属性的值。 + +![image](images/Using_Custom_Fields.png) + +在 JSON 输出中找到匹配的对象后,您就可以确定其 "key" 值 \- 在本例中为 `customfield_10050`。 + +Jira 会为每个自定义字段生成不同的键值,但这些键值一旦创建就不会更改。如果您以后再创建另一个自定义字段,它将拥有一个新的键值。 + +**扩展我们的自定义字段列表:** + +* "DefectDojo Custom URL Field" \= customfield\_10050 +* "Another example of a Custom Field" \= customfield\_12345 +* ... + +#### 步骤 3 \- 在 Jira Issue 上查找自定义字段 + +在 Jira 中找到一个包含您在步骤 2 中记录的自定义字段的 issue。复制作为标题的 Issue Key(应类似于 "`EXAMPLE-123`"),然后导航到以下 URL: + +`https://yourcompany-example.atlassian.net/rest/api/2/issue/EXAMPLE-123` + +这将返回另一段 JSON。 + +和之前一样,该 API 输出会包含许多值为 `null` 的 `customfield_##` 对象参数 \- 这些是 Jira 默认添加的自定义字段,与该 issue 无关。它也会包含与您在上一步中找到的自定义字段键值相匹配的 `customfield_##` 值。与字段规范的输出不同的是,您在这里不会看到用于标识这些自定义字段的名称,这也是为什么您需要在步骤 2 中记录键值的原因。 + +![image](images/Using_Custom_Fields_2.png) + +**示例:** +我们在步骤 2 中已经记录过,知道 `customfield_10050` 代表 DefectDojo Custom URL Field。现在我们可以看到,在 `EXAMPLE-123` 这个 issue 中,`customfield_10050` 的值为 `"https://google.com"`。 + +#### 步骤 4 \- 根据每个 Jira 自定义字段键创建 JSON 字段参考 + +接下来,您需要获取列表中每个自定义字段的值,并将它们存储在一个 JSON 对象中(用作参考)。您可以忽略任何不在您列表中的自定义字段。 + +这个 JSON 对象将包含新建 Jira Issue 所需的全部默认值。我们建议使用便于团队识别的名称,将其标记为需要更改的'默认'值,例如:'`change-me.com`'、'`Change this paragraph.`' 等。 + +**示例:** + +根据步骤 3,我们现在知道 Jira 期望 "`customfield_10050`" 是一个 URL 字符串。我们可以据此构建示例 JSON 对象。 + +假设我们还找到了一个与 DefectDojo 相关的短文本字段,并将其识别为 "`customfield_67890`"。我们会在第二次的 API 输出中查看该字段,查看其对应的值,并同样将该存储值引用到我们的示例 JSON 对象中。 +​ +随着您不断添加自定义字段,您的 JSON 对象将逐渐变成下面这样。 + +``` +{ + "customfield_10050": "https://change-me.com", + "customfield_67890": "This is the short text custom field." +} +``` + +重复此过程,直到已将 Jira 中所有与 DefectDojo 相关的自定义字段都添加到您的 JSON 字段参考中。 + +#### 数据类型与 Jira 语法 + +某些字段(例如日期字段)可能对应 Jira 中的多个自定义字段。如果是这种情况,您需要将这两个字段都添加到您的 JSON 字段参考中。 + +``` + "customfield_10040": "1970-01-01", + "customfield_10041": "1970-01-01T03:30:00.000+0200", +``` + +其他字段(例如 Label 字段)可能以字符串列表的形式被跟踪 \- 请确保您的 JSON 字段参考所使用的格式与 Jira 的 API 输出格式相匹配。 + +``` +// a list of custom labels on a Jira object + "customfield_10042": [ + "custom-label-one", + "this-is-default", + "change-me-please" + ], +``` + +其他自定义字段可能包含应从字段参考中移除的额外上下文信息。例如,自定义多选字段在 API 输出中包含一个额外的代码块,您需要将其移除,因为该代码块存储的是该字段的当前值。 + +* 您应从该字段中移除这个额外的对象: + +``` +"customfield_10047": [ + { + "value": "A" + }, + { + "self": "example.url...", + "value": "C", + "id": "example ID" + } +] +``` +* 您可以将其简化为以下内容,并忽略第二部分: + +``` +"customfield_10047": [ + { + "value": "A" + } +] +``` + +#### 已完成字段参考示例 + +以下是一份完整的 JSON 字段参考,并附有行内注释说明每个自定义字段所对应的内容。这只是一个综合性的示例。您的 JSON 会包含不同的键值和数据,具体取决于您希望在创建 issue 时使用的自定义值。 + +``` +{ + "customfield_10050": "https://change-me.com", + + "customfield_10049": "This is a short text custom field", + +// two different fields, but both correspond to the same custom date attribute + "customfield_10040": "1970-01-01", + "customfield_10041": "1970-01-01T03:30:00.000+0200", + +// a list of custom labels on a Jira object + "customfield_10042": [ + "custom-label-one", + "this-is-default", + "change-me-please" + ], + +// custom number field + "customfield_10043": 0, + +// custom paragraph field + "customfield_10044": "This is a very long winded way to say CHANGE ME PLEASE", + +// custom radio button field + "customfield_10045": { + "value": "radio button option" + }, + +// custom multichoice field + "customfield_10047": [ + { + "value": "A" + } + ], + +// custom checkbox field + "customfield_10039": [ + { + "value": "A" + } + ], + +// custom select list (singlechoice) field + "customfield_10048": { + "value": "1" + } +} +``` + +#### 步骤 5 \- 将自定义字段添加到 DefectDojo 产品 + +现在,您可以在 Jira 项目设置页面(可通过产品上的 ⚙️ 齿轮菜单访问)中,将这些自定义字段添加到关联的 DefectDojo 产品。请将 JSON 字段参考以纯文本形式粘贴到 **自定义字段** 框中并保存。 + +#### 步骤 6 \- 通过新建发现项测试您的 Jira 自定义字段: + +现在,当您在与 Jira 关联的产品中创建一个新的发现项时,Jira 会根据其中包含的 JSON 块自动创建所有这些自定义字段。这些自定义字段将以默认值("change\-me\-please" 等)被创建。 + +在 DefectDojo 的该产品中,导航到 发现项 \> 新增发现项 页面。请确保该发现项同时处于活动和已验证状态,以确保它会被推送到 Jira,然后在 Jira 一侧确认这些自定义字段已成功创建且没有任何不一致之处。 diff --git a/docs/content/connectors/downstream/_index.it.md b/docs/content/connectors/downstream/_index.it.md new file mode 100644 index 0000000000..7a020b633b --- /dev/null +++ b/docs/content/connectors/downstream/_index.it.md @@ -0,0 +1,19 @@ +--- +title: Connettori a valle +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +aliases: +- /it/issue_tracking/pro_integration/ +--- diff --git a/docs/content/connectors/downstream/_index.pt-br.md b/docs/content/connectors/downstream/_index.pt-br.md new file mode 100644 index 0000000000..0a27d08391 --- /dev/null +++ b/docs/content/connectors/downstream/_index.pt-br.md @@ -0,0 +1,19 @@ +--- +title: Conectores Downstream +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +aliases: +- /pt-br/issue_tracking/pro_integration/ +--- diff --git a/docs/content/connectors/downstream/_index.zh-hans.md b/docs/content/connectors/downstream/_index.zh-hans.md new file mode 100644 index 0000000000..8a31e97f3f --- /dev/null +++ b/docs/content/connectors/downstream/_index.zh-hans.md @@ -0,0 +1,19 @@ +--- +title: 下游连接器 +description: '' +summary: '' +date: 2023-09-07 16:06:50+02:00 +lastmod: 2023-09-07 16:06:50+02:00 +draft: false +weight: 3 +chapter: true +seo: + title: '' + description: '' + canonical: '' + robots: '' +exclude_search: true +audience: pro +aliases: +- /zh-hans/issue_tracking/pro_integration/ +--- diff --git a/docs/content/connectors/downstream/about.it.md b/docs/content/connectors/downstream/about.it.md new file mode 100644 index 0000000000..41e17bfa6e --- /dev/null +++ b/docs/content/connectors/downstream/about.it.md @@ -0,0 +1,137 @@ +--- +title: Connettori a valle +weight: 1 +audience: pro +aliases: +- /it/en/share_your_findings/integrations +- /it/issue_tracking/pro_integration/integrations/ +--- + +**Disponibilità:** i Connettori a valle sono generalmente disponibili e attivi su ogni istanza di DefectDojo Pro, sia Cloud che On-Premise. Non c'è nulla da abilitare e non sono più elencati nella pagina Feature Flags. + +I Connettori a valle consentono di inviare i Riscontri e i Gruppi di riscontri a sistemi di ticket tracking, per integrare facilmente la remediation della sicurezza con i flussi di lavoro di sviluppo già in uso dal team. + +Connettori a valle supportati: +- Azure Devops +- Bitbucket +- Freshservice +- GitHub +- GitLab Boards +- Jira +- Linear +- Opsgenie +- PagerDuty +- ServiceDesk Plus +- ServiceNow +- ServiceNow SecOps / Vulnerability Response +- Shortcut +- Zendesk + +## Apertura della pagina Connettori a valle + +La pagina Connettori a valle si trova in **Import > Connectors > Downstream Connectors** nella barra laterale. + +![image](images/integrators_3.png) + +## Configurazione di un Connettore a valle + +Un Connettore a valle è configurato con tre componenti principali: + +- **Istanza di integrazione**: è il metodo di connessione primario che DefectDojo utilizzerà con un sistema di terze parti. L'Istanza include dettagli come un'etichetta, una posizione e le credenziali con cui connettersi, oltre a qualsiasi altra informazione richiesta dal fornitore. +- **Mappatura dell'Issue Tracker**: è il punto in cui vengono memorizzate le informazioni di mappatura, ovvero i dettagli necessari per connettersi a un determinato "progetto" all'interno del fornitore. Questi dettagli includono il nome o l'ID del "progetto" e le mappature tra la gravità e lo stato dei Riscontri di DefectDojo e il campo corrispondente nel "ticket" del fornitore. È possibile configurare più mappature se si desidera inviare i Riscontri a più "progetti". +- **Assegnazione dell'Issue Tracker**: è il punto in cui i Prodotti e gli Engagement di DefectDojo vengono assegnati a una determinata Mappatura dell'Issue Tracker, con opzioni per Prodotto/Engagement che definiscono come un Riscontro verrà inviato a un determinato sistema del fornitore. + +Questi componenti sono gerarchici: ogni **Istanza** ha una o più **Mappature**, che a loro volta hanno una o più **Assegnazioni dell'Issue Tracker**. + +![image](images/integrators_2.png) + +## Invio di Riscontri e Gruppi di riscontri + +Una volta configurati questi componenti, i Riscontri e i Gruppi di riscontri possono essere inviati a un determinato Issue Tracker in due modi: manualmente o automaticamente. + +- **Manualmente**: i Riscontri e i Gruppi di riscontri contenuti in un Prodotto/Engagement con una Mappatura dell'Issue Tracker assegnata avranno un'opzione "Push to Integrator". Questa creerà un Issue nell'Issue Tracker con le informazioni corrispondenti del Riscontro/Gruppo di riscontri. Push to Integrator può essere usato anche per aggiornare un Issue esistente. + +### Invio automatico dei Riscontri + +I Riscontri possono anche essere inviati automaticamente, con l'**Assegnazione dell'Issue Tracker** che stabilisce come questi oggetti verranno inviati. Sono disponibili quattro opzioni: + +- **Only Explicitly Publish Changes to Target**: questa opzione disabilita qualsiasi comportamento automatico nel Prodotto o Engagement assegnato. L'unico modo per inviare un Riscontro o un Gruppo di riscontri sarà farlo esplicitamente, come descritto sopra. +- **Automatically Link New Finding to Target**: quando nuovi Riscontri o Gruppi di riscontri vengono **creati** nel Prodotto o Engagement assegnato, DefectDojo invierà automaticamente l'oggetto all'Issue Tracker. Una volta creati, questi Riscontri o Gruppi di riscontri non verranno aggiornati senza un'azione manuale di Push to Integrator. +- **Automatically Update Existing Link on Finding Edit**: quando i Riscontri o i Gruppi di riscontri vengono **aggiornati** nel Prodotto o Engagement assegnato, l'oggetto viene inviato automaticamente all'Issue Tracker se un collegamento esistente è già stato creato manualmente. +- **Automatically Link New and Update Existing Link on Finding Edit**: quando i Riscontri o i Gruppi di riscontri vengono creati **o** aggiornati nel Prodotto o Engagement assegnato, l'oggetto viene inviato automaticamente all'Issue Tracker. + +#### Filtri di invio + +Ogni Assegnazione dell'Issue Tracker può facoltativamente restringere quali Riscontri vengono inviati **automaticamente**: + +- **Minimum Severity**: crea automaticamente i ticket solo per i Riscontri con gravità pari o superiore a quella selezionata. Lasciare vuoto per includere tutte le gravità. +- **Active findings only**: crea automaticamente i ticket solo per i Riscontri attivi, escludendo quelli già mitigati, falsi positivi o con rischio accettato nel momento in cui l'assegnazione li rileva per la prima volta. + +Questi filtri si applicano solo alla **creazione** automatica. Gli aggiornamenti a un Riscontro che ha già un ticket collegato vengono sempre inviati, quindi i cambiamenti di stato (comprese le chiusure) continuano a essere propagati. Un **Push to Integrator** manuale ignora sempre i filtri. Lasciare entrambi i valori predefiniti mantiene il comportamento originale di invio di ogni Riscontro. + +#### Assegnazione di più Prodotti + +Un'Assegnazione dell'Issue Tracker punta a un singolo Prodotto o Engagement. Per coprire più asset, creare un'Assegnazione per ogni Prodotto (o Engagement). Se è inoltre necessario che i campi del fornitore differiscano per asset — ad esempio un diverso **Assignment group** o **Assigned to** di ServiceNow, oppure un progetto Jira diverso — creare una Mappatura dell'Issue Tracker separata (con le proprie Mappature dei campi personalizzati) per ciascun asset e far puntare ogni Assegnazione alla Mappatura corrispondente. + +## Rappresentazione del ticket dell'Issue Tracker + +I ticket dell'Issue Tracker sono rappresentati da una serie di icone nella colonna "Integrator Tickets" durante la visualizzazione e l'elenco +dei Riscontri e dei Gruppi di riscontri + +Icone da sinistra a destra: + +- **Integration Type**: il tipo di Issue Tracker a cui è associato il ticket +- **Ticket ID**: l'ID del ticket, come definito dall'Issue Tracker +- **Ticket Link**: il collegamento diretto al ticket, come definito dall'Issue Tracker +- **Changelog**: indica quando il ticket dell'Issue Tracker è stato associato a un Riscontro o Gruppo di riscontri, oltre all'ultima volta che DefectDojo ha apportato una modifica al ticket + +![image](images/integrators_1.png) + +## Requisiti specifici per fornitore + +Ogni fornitore avrà requisiti diversi per il modo in cui DefectDojo dovrà interagire con esso. Questo può presentarsi sotto forma di un meccanismo di autenticazione, campi aggiuntivi su base "progetto" o mappature di gravità/stato. + +Per l'elenco completo dei requisiti, aprire le pagine specifiche per fornitore riportate di seguito: + +- [Azure Devops](/connectors/downstream/downstream_toolreference/#azure-devops-boards) +- [Bitbucket](/connectors/downstream/downstream_toolreference/#bitbucket) +- [Freshservice](/connectors/downstream/downstream_toolreference/#freshservice) +- [GitHub](/connectors/downstream/downstream_toolreference/#github) +- [GitLab Boards](/connectors/downstream/downstream_toolreference/#gitlab) +- [Jira](/connectors/downstream/downstream_toolreference/#jira) +- [Linear](/connectors/downstream/downstream_toolreference/#linear) +- [Opsgenie](/connectors/downstream/downstream_toolreference/#opsgenie) +- [PagerDuty](/connectors/downstream/downstream_toolreference/#pagerduty) +- [ServiceDesk Plus](/connectors/downstream/downstream_toolreference/#servicedesk-plus) +- [ServiceNow](/connectors/downstream/downstream_toolreference/#servicenow) +- [ServiceNow SecOps / Vulnerability Response](/connectors/downstream/downstream_toolreference/#servicenow-secops) +- [Shortcut](/connectors/downstream/downstream_toolreference/#shortcut) +- [Zendesk](/connectors/downstream/downstream_toolreference/#zendesk) + +## Gestione degli errori e debug + +I Connettori a valle possono generare errori per svariati motivi, come problemi di connettività, autenticazione, permessi, ecc. Per facilitare +il debug di questi errori, ogni Mappatura dell'Issue Tracker dispone di una tabella di errori che elenca quando si è verificato l'errore, il motivo per cui si è +verificato e il Riscontro o Gruppo di riscontri che non è stato possibile inviare. + +Questi errori si trovano nella pagina All Issue Tracker Mappings & Assignments, nella colonna ⚠️ Total Errors. + +![image](images/integrators_4.png) + +Facendo clic sulla voce Total Errors si accede a una pagina con descrizioni più dettagliate degli errori associati a questo Connettore a valle. + +### Vedere tutti i fallimenti in un unico posto + +La tabella degli errori per singola mappatura copre un solo Connettore a valle. [Diagnostics](/admin/diagnostics/pro__diagnostics/) li copre tutti, insieme a ogni altro tentativo di integrazione sull'istanza — connettori a monte, importazioni, Jira, SSO e il motore delle regole — con lo stesso filtraggio e ordinamento su tutto quanto. + +Usarla quando la domanda è più ampia di una singola mappatura: + +* un tentativo che **non si è mai concluso** piuttosto che fallito, cosa che nessuna tabella degli errori riporta, perché non si è verificato alcun errore +* se un fallimento è specifico di un'integrazione o si sta verificando contemporaneamente su più integrazioni +* chi o cosa ha avviato un tentativo, e rispetto a quale configurazione + +Le credenziali citate in un errore vengono rimosse prima che la riga venga memorizzata, e il dettaglio tecnico completo è riservato ai superuser. + +## Struttura della pagina Connettori a valle + +I Connettori a valle sono elencati in due sezioni, **Configured Connectors** e **Available Connectors**, ciascuna ordinata alfabeticamente con un conteggio di quanto viene mostrato accanto al proprio titolo. Uno strumento può contenere più configurazioni; ciascuna è un riquadro a sé, intitolato ` -