Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add sarif output changes #152

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add sarif output changes #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
337a323
fix:docs sarif update commands and flags
HenriqueZup Apr 11, 2022
6e9b6af
docs: update FAQ with SARIF info
HenriqueZup Apr 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions content/en/cli/commands-and-flags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -329,8 +329,7 @@ On the table below, you can see all the available flags. To see it better, just
<td style="text-align:left">output-format</td>
<td style="text-align:left">o</td>
<td style="text-align:left">text</td>
<td style="text-align:left">The exit can be changed among <code>json</code> or <code>sonarqube </code> or <code>text</code>
</td>
<td style="text-align:left">The exit can be changed among <code>json</code>, <code>sonarqube </code>, <code>text</code> or <code>sarif</code></td>
</tr>
<tr>
<td style="text-align:left"></td>
Expand All @@ -349,9 +348,10 @@ On the table below, you can see all the available flags. To see it better, just
<td style="text-align:left">json-output-file</td>
<td style="text-align:left">O</td>
<td style="text-align:left"></td>
<td style="text-align:left">In case the exit is <code>sonarqube</code> or <code>json</code> it must have
<td style="text-align:left">In case the exit is <code>sonarqube</code>, <code>json</code> or <code>sarif</code> it must have
a name to be saved.
<br />Ex.:<code>./output.json</code>
<br /><strong>Note:</strong> For sarif output you must use: <code>./output.sarif.json</code> or <code>./output.sarif</code>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -674,7 +674,7 @@ In this example, we used:
horusec start -p="/home/user/project" -a="REPOSITORY_TOKEN" -i="**/node_modules/**, **/vendor/**, **/*_test.go"
```

### Example 4: To get the JSON exit
### Example 4: Using to get the JSON exit

In this example, we are using:

Expand All @@ -699,7 +699,23 @@ In this example, we are using:
horusec start -p="/home/user/project" -a="REPOSITORY_TOKEN" -o="sonarqube" -O="./sonarqube.json"
```

### Example 6: Using as docker image locally
### Example 6: Using to get sarif exit

In this example, we are using:

* A `flag -p` to inform where the project is;
* A `flag -a` passing the authorization token to send the analysis to our web interface;
* A `flag -o` where the output is being used is `“sarif”` and the local file output will be `“./output-horusec.sarif.json”`

```bash
horusec start -p="/home/user/project" -a="REPOSITORY_TOKEN" -o="sarif" -O="./output-horusec.sarif.json"
```

{{% alert color="info" %}}
The `json-output-file` or `-O` flag, must be in the `.sarif` or `.sarif.json` extension.
{{% /alert %}}

### Example 7: Using as docker image locally

See, this example the `horusec start` command is already executed. When starting the image, just add the flag you want.

Expand Down
14 changes: 13 additions & 1 deletion content/en/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "FAQ"
linkTitle: "FAQ"
weight: 51
weight: 10
type: list
description: >-
In this section, you will find frequently asked questions about Horusec.
Expand Down Expand Up @@ -90,3 +90,15 @@ Yes, all the market tools have its own data output. Horusec reads and puts it in

### **19. Is it possible to contribute to the project with a tool I already know?**
Yes, check out the tutorial to add [**tool you want in Horusec**]({{< ref path="/cli/analysis-tools/security-tools.md" lang="en">}}), you can use Horusec's analysis engine or an existing tool.

### **20. Horusec now supports the SARIF output format, but how does this file work?**

**SARIF (Static Analysis Results Interchange Format)**, is a file format based on the JSON standard used in the output of static analysis tools. However, unlike the output file in JSON format, SARIF has a dictionary with all the rules of all the engines, this simplifies the use of several analysis tools for the same analyzed target.

**Why use SARIF as output in Horusec?**

- Supports all engines with less effort in deployment, as it requires few adjustments such as semantic changes or basic adjustments to the file structure.
- Using an output file in SARIF format in Horusec avoids errors in converting a JSON file to SARIF.
- It has native integration with [**Github's security dashboard.**](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#example-showing-all-supported-sarif-properties)

See in this section [**how to get a SARIF output**]({{< ref path="/cli/commands-and-flags.md#example-6-using-to-get-sarif-exit" lang="en" >}}).
24 changes: 21 additions & 3 deletions content/pt-br/cli/commands-and-flags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,15 +312,17 @@ Na tabela abaixo, você confere todas as flags disponíveis. Para melhor visuali
<td style="text-align:left">output-format</td>
<td style="text-align:left">o</td>
<td style="text-align:left">text</td>
<td style="text-align:left">A saída pode ser alterada entre <code>json</code> ou <code>sonarqube</code> ou <code>text</code></td>
<td style="text-align:left">A saída pode ser alterada entre <code>json</code>, <code>sonarqube</code>, <code>text</code> ou <code>sarif</code></td>
</tr>
<tr>
<td style="text-align:left">HORUSEC_CLI_JSON_OUTPUT_FILEPATH</td>
<td style="text-align:left">horusecCliJsonOutputFilepath</td>
<td style="text-align:left">json-output-file</td>
<td style="text-align:left">O</td>
<td style="text-align:left"></td>
<td style="text-align:left">Caso a saída seja <code>sonarqube</code> ou <code>json</code> deverá ter um nome do arquivo a ser salvo. Ex.:<code>./output.json</code></td>
<td style="text-align:left">Caso a saída seja <code>sonarqube</code>, <code>json</code> ou <code>sarif</code> deverá ter um nome do arquivo a ser salvo.
<br />Ex.:<code>./output.json</code>
<br /><strong>Nota:</strong> Para o formato sarif, você deve usar: <code>./output.sarif.json</code> ou <code>./output.sarif</code></td>
</tr>
<tr>
<td style="text-align:left">HORUSEC_CLI_FILES_OR_PATHS_TO_IGNORE</td>
Expand Down Expand Up @@ -638,7 +640,23 @@ Neste exemplo, estamos utilizando:
horusec start -p="/home/user/project" -a="REPOSITORY_TOKEN" -o="sonarqube" -O="./sonarqube.json"
```

### Exemplo 6: Usando como imagem docker localmente
### Exemplo 6: Usando para obter uma saída Sarif

Neste exemplo, estamos utilizando:

* A `flag -p` para informar o local onde está o projeto;
* A `flag -a` passando o token de autorização a fim de enviar essa análise para nossa interface web;
* A `flag -o` onde o output está sendo utilizado é `“sarif”` e o local do arquivo de saída será em `“./output-horusec.sarif.json”`

```bash
horusec start -p="/home/user/project" -a="REPOSITORY_TOKEN" -o="sarif" -O="./output-horusec.sarif.json"
```

{{% alert color="info" %}}
A flag `json-output-file` ou `-O`, deve ser na extensão `.sarif` ou `.sarif.json`.
{{% /alert %}}

### Exemplo 7: Usando como imagem docker localmente

Veja que, neste exemplo, o comando `horusec start` já é executado. Por isso, ao iniciar a imagem, basta adicionar as flags que deseja.

Expand Down
13 changes: 12 additions & 1 deletion content/pt-br/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "FAQ"
linkTitle: "FAQ"
weight: 7
weight: 10
type: list
description: >-
Nesta seção, você vai encontrar perguntas e respostas mais realizadas pela comunidade sobre o Horusec.
Expand Down Expand Up @@ -102,3 +102,14 @@ Sim, todas as ferramentas de mercado tem a sua própria saída de dados. O Horus
### **19. É possível contribuir para o projeto com uma ferramenta que já conheço?**
Sim, veja o tutorial para adicionar a [**ferramenta que você deseja no Horusec**]({{< ref path="/cli/analysis-tools/security-tools.md" lang="pt-br">}}), você pode usar o motor de análise do Horusec ou uma ferramenta de mercado já existente.

### **20. O Horusec agora suporta o formato de saída SARIF, mas como esse arquivo funciona?**

**SARIF (Static Analysis Results Interchange Format)**, é um formato de arquivo baseado no padrão JSON utilizado na saída de ferramentas de análise estática. Entretanto, diferente do arquivo de saída no formato JSON, o SARIF possui um dicionário com todas as regras de todas as engines, isso simplifica o uso de várias ferramentas de análise para um mesmo alvo analisado.

**Porque usar SARIF como saída no Horusec?**

- Suporta todas as engines com um menor esforço na implantação, pois exige poucos ajustes como mudanças semânticas ou ajustes básicos na estrutura do arquivo.
- O uso de um arquivo de saída no formato SARIF no Horusec evita erros de conversão de um arquivo JSON para SARIF.
- Possui integração nativa com [**Github security dashboard.**](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#example-showing-all-supported-sarif-properties)

Veja nessa seção [**como obter uma saída SARIF**]({{< ref path="/cli/commands-and-flags.md#exemplo-6-usando-para-obter-uma-saída-sarif" lang="pt-br">}}).