-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #9 from CoinFabrik/improve-action
Update docs
- Loading branch information
Showing
1 changed file
with
22 additions
and
67 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -20,97 +20,52 @@ jobs: | |
| - uses: actions/checkout@v4 | ||
| - uses: coinfabrik/scout-actions@v3 | ||
| with: | ||
| target: './target' | ||
| scout_args: (scout arguments) | ||
| scout_extra_args: (scout extra arguments) | ||
| working_directory: "." | ||
| verbose: false | ||
| fail_on_error: true | ||
| comment_pr: false | ||
| github_token: ${{ secrets.GITHUB_TOKEN }} | ||
| scout_extra_args: "" | ||
| ``` | ||
| ### YML Description | ||
| - **name: Scout-actions**: This is the name of the GitHub Action which will be viewed on the GitHub Actions dashboard. | ||
| - **on: [push]**: This line specifies the event that will trigger the action. In this case, the GitHub Action fires whenever a push is made to the repository. | ||
| - **jobs**: GitHub Actions can contain several jobs. In this case, only one job named analyze has been set up. | ||
| - **analyze**: This is the name of the job. | ||
| - **runs-on: ubuntu-latest**: This specifies the runtime environment for the job. Here, the job will run on the latest available Ubuntu version. | ||
| - **steps**: This is a list of tasks to be carried out in the job. In this case, there are two tasks. | ||
| - **steps**: This is a list of tasks to be carried out in the job. | ||
| - **uses: actions/checkout@v4**: The first task uses a GitHub Action called 'checkout@v4'. This is a predefined Action that allows GitHub Actions to work with a copy of your repository. | ||
| - **uses: coinfabrik/scout-actions@v3**: The second task uses the GitHub Action 'scout-actions@v3', a version specified by coinfabrik. | ||
| - **with** and **target**: **'./target'**: Under the 'coinfabrik/scout-actions@v3' task, an additional option | ||
| with is configured, which sets a specific target for the action under with. In this case, the target is the path `./target`, and scout will run on sub/project: `./target/Cargo.toml`. | ||
| This toml file in the target directory likely has the dependencies and project configuration that will undergo analysis. | ||
| - **with/scout_args**: allows you to overwrite current arguments for scout, which make it generate a markdown report which can be later included in PRs and tickets. Most users don't need to change this. | ||
| - **with/scout_extra_args**: allows you to specify extra arguments for scout, which will be added to the already present for markdown report generation. Most users don't need to change this. | ||
|
|
||
|
|
||
| In short, this .yml file sets up a GitHub Action that activates on any push to the repository. When triggered, it will checkout the repository and then run the 'scout-actions@v3' Action on the './target' path. | ||
|
|
||
| - **uses: coinfabrik/scout-actions@v3**: The second task uses the GitHub Action 'scout-actions@v3'. | ||
| ### Options | ||
| | Key | Description | | ||
| |--------------------|--------------------------------------------------------------------------------------------------------------------------------| | ||
| | `target` | The path to the root of the project to be analyzed by Scout. It can be a path of `Cargo.toml`, and it defaults to the repo root. | | ||
| | `scout_args` | Allows you to overwrite the arguments for scout. The default makes scout output a markdown output. | | ||
| | `scout_extra_args` | This parameter allows you to add arguments for scout execution while keeping the required for markdown output. | | ||
|
|
||
| | Key | Description | Required | Default | | ||
| | ------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------- | | ||
| | `working_directory` | Directory containing the Cargo.toml file to analyze. Examples: ".", "./my-project", "packages/rust-project" | No | "." | | ||
| | `verbose` | Enable verbose output for detailed analysis information | No | false | | ||
| | `fail_on_error` | Controls whether the action should fail if Scout finds security issues | No | true | | ||
| | `comment_pr` | Automatically comment analysis results on the PR | No | false | | ||
| | `github_token` | GitHub token for PR commenting functionality. Required when comment_pr is true | No | - | | ||
| | `scout_extra_args` | Additional arguments to pass to Scout CLI. Example: "--exclude [DETECTOR_NAME]" | No | "" | | ||
|
|
||
| ## Detectors | ||
|
|
||
| Refer to Scout's [documentation site](https://coinfabrik.github.io/scout-audit/docs/intro) for a full list of the detectors for Ink, Soroban and Substrate. | ||
|
|
||
| ## Full example | ||
|
|
||
| ```yaml | ||
| name: scout-audit | ||
| on: | ||
| pull_request: | ||
| branches: | ||
| - main | ||
| jobs: | ||
| scout-audit: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| pull-requests: write | ||
| contents: write | ||
| repository-projects: write | ||
| steps: | ||
| - name: checkout | ||
| uses: actions/checkout@v4 | ||
| - name: do scout | ||
| uses: coinfabrik/[email protected] | ||
| with: | ||
| target: '' # Path of the project/file to execute Scout on. | ||
| - uses: mshick/[email protected] | ||
| with: | ||
| message-path: ${{ github.workspace }}/report.md | ||
| # # Optional: Add the following step to block the merge of the commit if Scout finds any issues. | ||
| - name: Check for error | ||
| run: | | ||
| if [ -f "${{ github.workspace }}/FAIL" ]; then | ||
| echo "Error: Scout found issues." | ||
| exit 1 | ||
| fi | ||
| ``` | ||
|
|
||
|
|
||
| ## Acknowledgements | ||
|
|
||
| Scout is an open source vulnerability analyzer developed by [CoinFabrik's](https://www.coinfabrik.com/) Research and Development team. | ||
|
|
||
| We received support through grants from the [Web3 Foundation Grants Program](https://github.com/w3f/Grants-Program/tree/master), the [Aleph Zero Ecosystem Funding Program](https://alephzero.org/ecosystem-funding-program) and the [Stellar Community Fund](https://communityfund.stellar.org). | ||
|
|
||
|
|
||
| | Grant Program | Description | | ||
| |:-------------:|-------------| | ||
| |  | **Proof of Concept:** We collaborated with the [Laboratory on Foundations and Tools for Software Engineering (LaFHIS)](https://lafhis.dc.uba.ar/) at the [University of Buenos Aires](https://www.uba.ar/internacionales/index.php?lang=en) to establish analysis techniques and tools for our detectors, as well as to create an initial list of vulnerability classes and code examples. [View Grant](https://github.com/CoinFabrik/web3-grant) \| [Application Form](https://github.com/w3f/Grants-Program/blob/master/applications/ScoutCoinFabrik.md).<br><br>**Prototype:** We built a functioning prototype using linting detectors built with [Dylint](https://github.com/trailofbits/dylint) and expanded the list of vulnerability classes, detectors, and test cases. [View Prototype](https://coinfabrik.github.io/scout/) \| [Application Form](https://github.com/w3f/Grants-Program/blob/master/applications/ScoutCoinFabrik_2.md). | | ||
| |  | We improved the precision and number of detectors for the tool with a multi-phase approach. This included a manual vulnerability analysis of projects within the Aleph Zero ecosystem, comprehensive testing of the tool on leading projects, and refining its detection accuracy. | | ||
| |  | We added support for Stellar's smart contract language, Soroban. We included various output formats, such as an HTML report, improved the tool's precision and recall, and added a GitHub action to run the tool with pull requests.| | ||
| |  | We added support for Substrate pallets in all of Scout's features: CLI, VS Code extension and GitHub Action. | | ||
| | Grant Program | Description | | ||
| | :----------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| |  | **Proof of Concept:** We collaborated with the [Laboratory on Foundations and Tools for Software Engineering (LaFHIS)](https://lafhis.dc.uba.ar/) at the [University of Buenos Aires](https://www.uba.ar/internacionales/index.php?lang=en) to establish analysis techniques and tools for our detectors, as well as to create an initial list of vulnerability classes and code examples. [View Grant](https://github.com/CoinFabrik/web3-grant) \| [Application Form](https://github.com/w3f/Grants-Program/blob/master/applications/ScoutCoinFabrik.md).<br><br>**Prototype:** We built a functioning prototype using linting detectors built with [Dylint](https://github.com/trailofbits/dylint) and expanded the list of vulnerability classes, detectors, and test cases. [View Prototype](https://coinfabrik.github.io/scout/) \| [Application Form](https://github.com/w3f/Grants-Program/blob/master/applications/ScoutCoinFabrik_2.md). | | ||
| |  | We improved the precision and number of detectors for the tool with a multi-phase approach. This included a manual vulnerability analysis of projects within the Aleph Zero ecosystem, comprehensive testing of the tool on leading projects, and refining its detection accuracy. | | ||
| |  | We added support for Stellar's smart contract language, Soroban. We included various output formats, such as an HTML report, improved the tool's precision and recall, and added a GitHub action to run the tool with pull requests. | | ||
| |  | We added support for Substrate pallets in all of Scout's features: CLI, VS Code extension and GitHub Action. | | ||
|
|
||
| ## About CoinFabrik | ||
|
|
||
|
|
||