From d19dd40e0e8e942b4dfcd97463358c229a5e7e39 Mon Sep 17 00:00:00 2001 From: Nicolas Vuillamy Date: Mon, 24 Jul 2023 10:20:29 +0200 Subject: [PATCH] Doc v0 --- CONTRIBUTING.md | 419 ++++++++++++++++++++++++++++ README.md | 419 +--------------------------- docs/assets/images/ox-icon.jpg | Bin 0 -> 3002 bytes docs/{ => assets/images}/screen.jpg | Bin docs/index.md | 0 docs/javascripts/gtag.js | 20 ++ docs/javascripts/quickfixes.js | 17 ++ docs/javascripts/tables.js | 6 + docs/stylesheets/extra.css | 76 +++++ mkdocs.yml | 62 ++++ 10 files changed, 601 insertions(+), 418 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/assets/images/ox-icon.jpg rename docs/{ => assets/images}/screen.jpg (100%) create mode 100644 docs/index.md create mode 100644 docs/javascripts/gtag.js create mode 100644 docs/javascripts/quickfixes.js create mode 100644 docs/javascripts/tables.js create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..01105eb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,419 @@ + # Contributing to MegaLinter + +- [Development Mode](#development-mode) +- [Available Scripts](#available-scripts) +- [Config](#config) +- [Building For Production](#building-for-production) +- [Debugging in VSCode](#debugging-in-vscode) +- [Messages from MegaLinter server](#messages-from-megalinter-server) + - [Start Megalinter analysis](#start-megalinter-analysis) + - [Start Linter analysis](#start-linter-analysis) + - [Complete Linter analysis](#complete-linter-analysis) + - [Complete Megalinter analysis](#complete-megalinter-analysis) + - [MegaLinter server error](#megalinter-server-error) + +## Development Mode + +- Clone this repo +- Run `npm i` to install dependencies +- Start megalinter server `npm run start:megalinter` +- Run `npm start` +- Open [`codetotal app`](http://localhost:3000) + +## Available Scripts + +- `npm start` start all projects in development mode +- `npm run lint` lint all projects +- `npm run build:be` build the backend (used by `launch.json` file for debugging) +- `npm run start:fe` start the FE in development mode +- `npm test` run all unit tests + +## Config + +Add a `.env` file in the root of the project. +Only variables starting with the `CODETOTAL_` prefix will be injected into the frontend bundle. + +```ini +# MEGALINTER +MEGALINTER_ANALYSIS_URL=http://127.0.0.1:8000/analysis +MEGALINTER_UPLOAD_URL=http://127.0.0.1:8000/upload-file +MEGALINTER_REDIS_URL=redis://127.0.0.1:6379 +MEGALINTER_REDIS_CHANNEL=megalinter:pubsub: + +# BACKEND +CODETOTAL_HTTP_PORT=8081 +CODETOTAL_HTTP_HOST=127.0.0.1 +CODETOTAL_WS_PORT=8080 +CODETOTAL_WS_HOST=127.0.0.1 +DEBUG_MODULES=actions,megalinter,stores,transport + +# FRONTEND +CODETOTAL_UPLOAD_FILE_LIMIT_BYTES=10000000 +``` + +## Building For Production + +- Config files must be set before the build (see `Config` section) +- Run `npm run build` at the root folder +- This will create a `dist` folder with the backend code +- The frontend code will be under `dist/public` +- Run using `npm run production` (equivilant to `node dist/index.js`) + +## Debugging in VSCode + +Add a `launch.json` file under the `.vscode` folder with the following content: + +```typescript +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Build Project", + "program": "${workspaceFolder}/packages/backend/dist/index.js", + "preLaunchTask": "npm: build:be", + "sourceMaps": true, + "smartStep": true, + "internalConsoleOptions": "openOnSessionStart", + "outFiles": ["${workspaceFolder}/packages/backend/dist/**/*.js"] + } + ] +} +``` + +## Messages from MegaLinter server + +Event-based management of MegaLinter Server can send the following list of messages into Redis PUBSUB channel built the following way: **megalinter:pubsub:REQUEST_ID** + +Example: `megalinter:pubsub:RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004` + +### Start Megalinter analysis + +This message is sent once by analysis, when a **MegaLinter instance has identified the linters to run** and is about to start them. + +Example of **megalinterStart** messageType: + +```json +{ + "messageType": "megalinterStart", + "megaLinterStatus": "created", + "linters": [ + { + "descriptorId": "BASH", + "linterId": "bash-exec", + "linterKey": "BASH_EXEC", + "linterVersion": "5.2.15", + "linterCliLintMode": "file", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/bash_bash_exec", + "isFormatter": false, + "isSBOM": false, + "filesNumber": 1 + }, + { + "descriptorId": "BASH", + "linterId": "shellcheck", + "linterKey": "BASH_SHELLCHECK", + "linterVersion": "0.9.0", + "linterCliLintMode": "list_of_files", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/bash_shellcheck", + "isFormatter": false, + "isSBOM": false, + "filesNumber": 1 + }, + { + "descriptorId": "BASH", + "linterId": "shfmt", + "linterKey": "BASH_SHFMT", + "linterVersion": "ERROR", + "linterCliLintMode": "list_of_files", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/bash_shfmt", + "isFormatter": true, + "isSBOM": false, + "filesNumber": 1 + }, + { + "descriptorId": "COPYPASTE", + "linterId": "jscpd", + "linterKey": "COPYPASTE_JSCPD", + "linterVersion": "ERROR", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/copypaste_jscpd", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "checkov", + "linterKey": "REPOSITORY_CHECKOV", + "linterVersion": "3.11", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_checkov", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "devskim", + "linterKey": "REPOSITORY_DEVSKIM", + "linterVersion": "1.0.11", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_devskim", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "dustilock", + "linterKey": "REPOSITORY_DUSTILOCK", + "linterVersion": "1.2.0", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_dustilock", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "git_diff", + "linterKey": "REPOSITORY_GIT_DIFF", + "linterVersion": "2.38.5", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_git_diff", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "gitleaks", + "linterKey": "REPOSITORY_GITLEAKS", + "linterVersion": "8.17.0", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_gitleaks", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "kics", + "linterKey": "REPOSITORY_KICS", + "linterVersion": "1.7.3", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_kics", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "secretlint", + "linterKey": "REPOSITORY_SECRETLINT", + "linterVersion": "7.0.3", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_secretlint", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "semgrep", + "linterKey": "REPOSITORY_SEMGREP", + "linterVersion": "1.31.2", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_semgrep", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "REPOSITORY", + "linterId": "trivy", + "linterKey": "REPOSITORY_TRIVY", + "linterVersion": "0.43.1", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", + "isFormatter": false, + "isSBOM": false + }, + { + "descriptorId": "SPELL", + "linterId": "cspell", + "linterKey": "SPELL_CSPELL", + "linterVersion": "ERROR", + "linterCliLintMode": "list_of_files", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/spell_cspell", + "isFormatter": false, + "filesNumber": 1, + "isSBOM": false + } + ], + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004" +} +``` + +### Start Linter analysis + +This message is sent once by linter run, it indicates that **a single linter has started running**. + +Example of **linterStart** messageType with `linterCliLintMode=project`: + +```json +{ + "messageType": "linterStart", + "linterStatus": "started", + "descriptorId": "REPOSITORY", + "linterId": "trivy", + "linterKey": "REPOSITORY_TRIVY", + "linterVersion": "0.43.1", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", + "isFormatter": false, + "isSBOM": false +} +``` + +Example of **linterStart** messageType with `linterCliLintMode=list_of_files` (with **filesNumber** additional property): + +```json +{ + "messageType": "linterStart", + "linterStatus": "started", + "descriptorId": "BASH", + "linterId": "shellcheck", + "linterKey": "BASH_SHELLCHECK", + "linterVersion": "0.9.0", + "linterCliLintMode": "list_of_files", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/bash_shellcheck", + "isFormatter": false, + "isSBOM": false, + "filesNumber": 1 +} +``` + +### Complete Linter analysis + +This message is sent once by linter run, it indicates that **a single linter has been completed**. + +If SARIF is available, it will be located in `outputSarif` property, otherwise results can be found in `outputText` and or `outputJson`. + +Example of **linterComplete** messageType: + +```json +{ + "messageType": "linterComplete", + "linterStatus": "success", + "linterErrorNumber": 0, + "linterStatusMessage": "No errors were found in the linting process", + "linterElapsedTime": 11.16, + "linterCliCommand": [ + "trivy", + "fs", + "--scanners", + "vuln,config", + "--exit-code", + "1", + "--format", + "sarif", + "-o", + "/tmp/ct-megalinter-xmv82bvyv/megalinter-reports/sarif/REPOSITORY_TRIVY.sarif", + "." + ], + "descriptorId": "REPOSITORY", + "linterId": "trivy", + "linterKey": "REPOSITORY_TRIVY", + "linterVersion": "0.43.1", + "linterCliLintMode": "project", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", + "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", + "isFormatter": false, + "isSBOM": false, + "outputSarif": { + "$schema": "https://json.schemastore.org/sarif-2.1.0.json", + "runs": [ + { + "columnKind": "utf16CodeUnits", + "originalUriBaseIds": { + "ROOTPATH": { + "uri": "file:///" + } + }, + "properties": { + "megalinter": { + "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", + "linterKey": "REPOSITORY_TRIVY", + "linterVersion": "0.43.1" + } + }, + "results": [], + "tool": { + "driver": { + "fullName": "Trivy Vulnerability Scanner", + "informationUri": "https://github.com/aquasecurity/trivy", + "name": "Trivy (MegaLinter REPOSITORY_TRIVY)", + "rules": [], + "version": "0.43.1" + } + } + } + ], + "version": "2.1.0" + } +} +``` + +### Complete Megalinter analysis + +This message is sent once by analysis, when a **MegaLinter analysis is completed**. + +CodeTotal stops listening to the requestId pubsub channel once this message is received, as no new message will be sent through this channel. + +Example of **megalinterComplete** messageType: + +```json +{ + "messageType": "megalinterComplete", + "megaLinterStatus": "completed", + "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004" +} +``` + +### MegaLinter server error + +In some cases, it is not possible for MegaLinter to start an analysis because there has been an error during initialization. + +In that case, CodeTotal stops listening to the pubsub channel, as no more messages will be sent. + +List of errors: + +- `missingAnalysisType`: Missing type (snippet, file or repository) +- `gitCloneError`: Unable to clone the repository (probably not existing or not reachable) +- `uploadedFileNotFound`: Unable to find file(s) that were supposed to be uploaded by a previous HTTP call to `/upload-file` +- `snippetGuessError`: Unable to automatically detect the language of a code snippet +- `snippetBuildError`: Unable to find a file extension for the guessed snipper language + +Example of **serverError** messageType + +```json +{ + "messageType": "serverError", + "message": "Unable to clone repository\nCmd('git') failed due to: exit code(128)\n cmdline: git clone -v -- https://github.com/nvuillam/node-sarif-builder2 /tmp/ct-megalinter-x0afpmcmb\n stderr: 'Cloning into '/tmp/ct-megalinter-x0afpmcmb'...\nfatal: could not read Username for 'https://github.com': No such device or address\n'", + "errorCode": "gitCloneError", + "errorDetails": { + "error": "Cmd('git') failed due to: exit code(128)\n cmdline: git clone -v -- https://github.com/nvuillam/node-sarif-builder2 /tmp/ct-megalinter-x0afpmcmb\n stderr: 'Cloning into '/tmp/ct-megalinter-x0afpmcmb'...\nfatal: could not read Username for 'https://github.com': No such device or address\n'" + }, + "requestId": "RQ_e630c962-1e7c-11ee-9258-0242ac120004" +} +``` diff --git a/README.md b/README.md index 631b9d3..eedc677 100644 --- a/README.md +++ b/README.md @@ -1,422 +1,5 @@ # CodeTotal -![Alt text](docs/screen.jpg "A screenshot from the app") +![CodeTotal Screenshot](docs/assets/images/screen.jpg "A screenshot from the app") -- [CodeTotal](#codetotal) - - [Development Mode](#development-mode) - - [Available Scripts](#available-scripts) - - [Config](#config) - - [Building For Production](#building-for-production) - - [Debugging in VSCode](#debugging-in-vscode) - - [Messages from MegaLinter server](#messages-from-megalinter-server) - - [Start Megalinter analysis](#start-megalinter-analysis) - - [Start Linter analysis](#start-linter-analysis) - - [Complete Linter analysis](#complete-linter-analysis) - - [Complete Megalinter analysis](#complete-megalinter-analysis) - - [MegaLinter server error](#megalinter-server-error) -## Development Mode - -- Clone this repo -- Run `npm i` to install dependencies -- Start megalinter server `npm run start:megalinter` -- Run `npm start` -- Open [`codetotal app`](http://localhost:3000) - -## Available Scripts - -- `npm start` start all projects in development mode -- `npm run lint` lint all projects -- `npm run build:be` build the backend (used by `launch.json` file for debugging) -- `npm run start:fe` start the FE in development mode -- `npm test` run all unit tests - -## Config - -Add a `.env` file in the root of the project. -Only variables starting with the `CODETOTAL_` prefix will be injected into the frontend bundle. - -``` -# MEGALINTER -MEGALINTER_ANALYSIS_URL=http://127.0.0.1:8000/analysis -MEGALINTER_UPLOAD_URL=http://127.0.0.1:8000/upload-file -MEGALINTER_REDIS_URL=redis://127.0.0.1:6379 -MEGALINTER_REDIS_CHANNEL=megalinter:pubsub: - -# BACKEND -CODETOTAL_HTTP_PORT=8081 -CODETOTAL_HTTP_HOST=127.0.0.1 -CODETOTAL_WS_PORT=8080 -CODETOTAL_WS_HOST=127.0.0.1 -DEBUG_MODULES=actions,megalinter,stores,transport - -# FRONTEND -CODETOTAL_UPLOAD_FILE_LIMIT_BYTES=10000000 -``` - -## Building For Production - -- Config files must be set before the build (see `Config` section) -- Run `npm run build` at the root folder -- This will create a `dist` folder with the backend code -- The frontend code will be under `dist/public` -- Run using `npm run production` (equivilant to `node dist/index.js`) - -## Debugging in VSCode - -Add a `launch.json` file under the `.vscode` folder with the following content: - -```typescript -{ - "version": "0.2.0", - "configurations": [ - { - "type": "node", - "request": "launch", - "name": "Build Project", - "program": "${workspaceFolder}/packages/backend/dist/index.js", - "preLaunchTask": "npm: build:be", - "sourceMaps": true, - "smartStep": true, - "internalConsoleOptions": "openOnSessionStart", - "outFiles": ["${workspaceFolder}/packages/backend/dist/**/*.js"] - } - ] -} -``` - -## Messages from MegaLinter server - -Event-based management of MegaLinter Server can send the following list of messages into Redis PUBSUB channel built the following way: **megalinter:pubsub:REQUEST_ID** - -Example: `megalinter:pubsub:RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004` - -### Start Megalinter analysis - -This message is sent once by analysis, when a **MegaLinter instance has identified the linters to run** and is about to start them. - -Example of **megalinterStart** messageType: - -```json -{ - "messageType": "megalinterStart", - "megaLinterStatus": "created", - "linters": [ - { - "descriptorId": "BASH", - "linterId": "bash-exec", - "linterKey": "BASH_EXEC", - "linterVersion": "5.2.15", - "linterCliLintMode": "file", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/bash_bash_exec", - "isFormatter": false, - "isSBOM": false, - "filesNumber": 1 - }, - { - "descriptorId": "BASH", - "linterId": "shellcheck", - "linterKey": "BASH_SHELLCHECK", - "linterVersion": "0.9.0", - "linterCliLintMode": "list_of_files", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/bash_shellcheck", - "isFormatter": false, - "isSBOM": false, - "filesNumber": 1 - }, - { - "descriptorId": "BASH", - "linterId": "shfmt", - "linterKey": "BASH_SHFMT", - "linterVersion": "ERROR", - "linterCliLintMode": "list_of_files", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/bash_shfmt", - "isFormatter": true, - "isSBOM": false, - "filesNumber": 1 - }, - { - "descriptorId": "COPYPASTE", - "linterId": "jscpd", - "linterKey": "COPYPASTE_JSCPD", - "linterVersion": "ERROR", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/copypaste_jscpd", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "checkov", - "linterKey": "REPOSITORY_CHECKOV", - "linterVersion": "3.11", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_checkov", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "devskim", - "linterKey": "REPOSITORY_DEVSKIM", - "linterVersion": "1.0.11", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_devskim", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "dustilock", - "linterKey": "REPOSITORY_DUSTILOCK", - "linterVersion": "1.2.0", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_dustilock", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "git_diff", - "linterKey": "REPOSITORY_GIT_DIFF", - "linterVersion": "2.38.5", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_git_diff", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "gitleaks", - "linterKey": "REPOSITORY_GITLEAKS", - "linterVersion": "8.17.0", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_gitleaks", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "kics", - "linterKey": "REPOSITORY_KICS", - "linterVersion": "1.7.3", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_kics", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "secretlint", - "linterKey": "REPOSITORY_SECRETLINT", - "linterVersion": "7.0.3", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_secretlint", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "semgrep", - "linterKey": "REPOSITORY_SEMGREP", - "linterVersion": "1.31.2", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_semgrep", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "REPOSITORY", - "linterId": "trivy", - "linterKey": "REPOSITORY_TRIVY", - "linterVersion": "0.43.1", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", - "isFormatter": false, - "isSBOM": false - }, - { - "descriptorId": "SPELL", - "linterId": "cspell", - "linterKey": "SPELL_CSPELL", - "linterVersion": "ERROR", - "linterCliLintMode": "list_of_files", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/spell_cspell", - "isFormatter": false, - "filesNumber": 1, - "isSBOM": false - } - ], - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004" -} -``` - -### Start Linter analysis - -This message is sent once by linter run, it indicates that **a single linter has started running**. - -Example of **linterStart** messageType with `linterCliLintMode=project`: - -```json -{ - "messageType": "linterStart", - "linterStatus": "started", - "descriptorId": "REPOSITORY", - "linterId": "trivy", - "linterKey": "REPOSITORY_TRIVY", - "linterVersion": "0.43.1", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", - "isFormatter": false, - "isSBOM": false -} -``` - -Example of **linterStart** messageType with `linterCliLintMode=list_of_files` (with **filesNumber** additional property): - -```json -{ - "messageType": "linterStart", - "linterStatus": "started", - "descriptorId": "BASH", - "linterId": "shellcheck", - "linterKey": "BASH_SHELLCHECK", - "linterVersion": "0.9.0", - "linterCliLintMode": "list_of_files", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/bash_shellcheck", - "isFormatter": false, - "isSBOM": false, - "filesNumber": 1 -} -``` - -### Complete Linter analysis - -This message is sent once by linter run, it indicates that **a single linter has been completed**. - -If SARIF is available, it will be located in `outputSarif` property, otherwise results can be found in `outputText` and or `outputJson`. - -Example of **linterComplete** messageType: - -```json -{ - "messageType": "linterComplete", - "linterStatus": "success", - "linterErrorNumber": 0, - "linterStatusMessage": "No errors were found in the linting process", - "linterElapsedTime": 11.16, - "linterCliCommand": [ - "trivy", - "fs", - "--scanners", - "vuln,config", - "--exit-code", - "1", - "--format", - "sarif", - "-o", - "/tmp/ct-megalinter-xmv82bvyv/megalinter-reports/sarif/REPOSITORY_TRIVY.sarif", - "." - ], - "descriptorId": "REPOSITORY", - "linterId": "trivy", - "linterKey": "REPOSITORY_TRIVY", - "linterVersion": "0.43.1", - "linterCliLintMode": "project", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004", - "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", - "isFormatter": false, - "isSBOM": false, - "outputSarif": { - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "runs": [ - { - "columnKind": "utf16CodeUnits", - "originalUriBaseIds": { - "ROOTPATH": { - "uri": "file:///" - } - }, - "properties": { - "megalinter": { - "docUrl": "https://megalinter.io/alpha/descriptors/repository_trivy", - "linterKey": "REPOSITORY_TRIVY", - "linterVersion": "0.43.1" - } - }, - "results": [], - "tool": { - "driver": { - "fullName": "Trivy Vulnerability Scanner", - "informationUri": "https://github.com/aquasecurity/trivy", - "name": "Trivy (MegaLinter REPOSITORY_TRIVY)", - "rules": [], - "version": "0.43.1" - } - } - } - ], - "version": "2.1.0" - } -} -``` - -### Complete Megalinter analysis - -This message is sent once by analysis, when a **MegaLinter analysis is completed**. - -CodeTotal stops listening to the requestId pubsub channel once this message is received, as no new message will be sent through this channel. - -Example of **megalinterComplete** messageType: - -```json -{ - "messageType": "megalinterComplete", - "megaLinterStatus": "completed", - "requestId": "RQ_cbdd1d82-1e7b-11ee-9258-0242ac120004" -} -``` - -### MegaLinter server error - -In some cases, it is not possible for MegaLinter to start an analysis because there has been an error during initialization. - -In that case, CodeTotal stops listening to the pubsub channel, as no more messages will be sent. - -List of errors: - -- `missingAnalysisType`: Missing type (snippet, file or repository) -- `gitCloneError`: Unable to clone the repository (probably not existing or not reachable) -- `uploadedFileNotFound`: Unable to find file(s) that were supposed to be uploaded by a previous HTTP call to `/upload-file` -- `snippetGuessError`: Unable to automatically detect the language of a code snippet -- `snippetBuildError`: Unable to find a file extension for the guessed snipper language - -Example of **serverError** messageType - -```json -{ - "messageType": "serverError", - "message": "Unable to clone repository\nCmd('git') failed due to: exit code(128)\n cmdline: git clone -v -- https://github.com/nvuillam/node-sarif-builder2 /tmp/ct-megalinter-x0afpmcmb\n stderr: 'Cloning into '/tmp/ct-megalinter-x0afpmcmb'...\nfatal: could not read Username for 'https://github.com': No such device or address\n'", - "errorCode": "gitCloneError", - "errorDetails": { - "error": "Cmd('git') failed due to: exit code(128)\n cmdline: git clone -v -- https://github.com/nvuillam/node-sarif-builder2 /tmp/ct-megalinter-x0afpmcmb\n stderr: 'Cloning into '/tmp/ct-megalinter-x0afpmcmb'...\nfatal: could not read Username for 'https://github.com': No such device or address\n'" - }, - "requestId": "RQ_e630c962-1e7c-11ee-9258-0242ac120004" -} -``` diff --git a/docs/assets/images/ox-icon.jpg b/docs/assets/images/ox-icon.jpg new file mode 100644 index 0000000000000000000000000000000000000000..bb2207a2f0df390253ee4b5a0425caf595a0abf7 GIT binary patch literal 3002 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 literal 0 HcmV?d00001 diff --git a/docs/screen.jpg b/docs/assets/images/screen.jpg similarity index 100% rename from docs/screen.jpg rename to docs/assets/images/screen.jpg diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/javascripts/gtag.js b/docs/javascripts/gtag.js new file mode 100644 index 0000000..2aa2817 --- /dev/null +++ b/docs/javascripts/gtag.js @@ -0,0 +1,20 @@ +var gtag_id = ""; //"G-9B8BSP0VV7"; replace by GTAG if you want stats + +if (gtag_id === "") { + return; +} + +var script = document.createElement("script"); +script.src = "https://www.googletagmanager.com/gtag/js?id=" + gtag_id; +document.head.appendChild(script); + +location$.subscribe(function (url) { + window.dataLayer = window.dataLayer || []; + + function gtag() { + dataLayer.push(arguments); + } + + gtag("js", new Date()); + gtag("config", gtag_id); +}); \ No newline at end of file diff --git a/docs/javascripts/quickfixes.js b/docs/javascripts/quickfixes.js new file mode 100644 index 0000000..ed49b1d --- /dev/null +++ b/docs/javascripts/quickfixes.js @@ -0,0 +1,17 @@ +function hideHomeTitle() { + // Hide h1 containing Home (to have a nicer home page) + var h1s = document.querySelectorAll("h1"); + for (var i = 0; i < h1s.length; i++) { + if (h1s[i].innerText === 'Home') { + h1s[i].style.display = 'none'; + } + } +} + +(window.onload = function () { + hideHomeTitle(); + // So ugly setInterval: TODO: make that clean + setInterval(function () { + hideHomeTitle() + }, 1000); +}) diff --git a/docs/javascripts/tables.js b/docs/javascripts/tables.js new file mode 100644 index 0000000..513f93e --- /dev/null +++ b/docs/javascripts/tables.js @@ -0,0 +1,6 @@ +document$.subscribe(function () { + var tables = document.querySelectorAll("article table") + tables.forEach(function (table) { + new Tablesort(table) + }) +}) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..e4fc121 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,76 @@ +/* stylelint-disable SelectorFormat, selector-class-pattern */ +.codetotal-banner { + height: 50px; + max-height: 150px; +} + +.codetotal-logo { + height: 70px; + max-height: 70px; +} + +.codetotal-icon { + max-height: 32px; + max-width: 32px; +} + +.md-typeset__table { + min-width: 100%; +} + +.md-typeset table:not([class]) { + display: table; +} + +/* light mode table header bgcolor */ +.md-typeset__table th { + background-color: #f2edfe; +} + +/* dark mode table header bgcolor */ +[data-md-color-scheme="slate"] .md-typeset__table th { + background-color: hsla(var(--md-hue),25%,25%,1) +} + +/* light mode alternating table bg colors */ +.md-typeset__table tr:nth-child(2n) { + background-color: #f8f8f8; +} + +/* dark mode alternating table bg colors */ +[data-md-color-scheme="slate"] .md-typeset__table tr:nth-child(2n) { + background-color: hsla(var(--md-hue),25%,25%,1) +} + +h1[content~=Home] { + display: none; +} + +:root>* { + --md-default-fg-color: #1E144D; + --md-default-fg-color--light: #6A2BFF; + --md-default-fg-color--lighter: #FD80CD ; + --md-default-fg-color--lightest: #dcc4d3; + --md-default-bg-color: #fff; + --md-default-bg-color--light: #fff; + --md-default-bg-color--lighter: #fff; + --md-default-bg-color--lightest: #fff; + + --md-primary-fg-color: #1E144D; + --md-primary-fg-color--light: #FD80CD; + --md-primary-fg-color--dark: #6A2BFF; + --md-primary-bg-color: #fff; + --md-primary-bg-color--light: #fff; + + + --md-accent-fg-color: #6A2BFF; + --md-accent-fg-color--transparent: #6A2BFF; + --md-accent-bg-color: #B95CE4; + --md-accent-bg-color--light: #FD80CD; + + --md-footer-bg-color: #B95CE4; + + --md-typeset-table-color--light: #fff5fb; + +} + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..557ae8d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,62 @@ +--- +site_name: CodeTotal by OX Security +site_url: https://codetotal.io +repo_url: https://github.com/oxsecurity/codetotal +edit_uri: tree/main/docs +site_author: Nicolas Vuillamy +# site_description-start +site_description: +# site_description-end +copyright: Copyright © 2022 OX Security +theme: + name: material + font: + text: Satoshi, sans-serif + custom_dir: docs/overrides + features: + - navigation.instant + - navigation.footer + logo: assets/images/ox-icon.jpg + favicon: assets/images/ox-icon.jpg + palette: + primary: white +plugins: + - glightbox + - search +markdown_extensions: + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.snippets: + base_path: docs + check_paths: true + - mdx_truly_sane_lists + - attr_list +extra_javascript: + - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js + - javascripts/tables.js +# - javascripts/gtag.js +# - javascripts/version-mike.js + - javascripts/quickfixes.js +extra_css: + - stylesheets/extra.css +extra: + social: + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/company/ox-security/ + - icon: fontawesome/regular/circle-question + link: https://github.com/oxsecurity/codetotal/issues + title: Need help ? Post an issue :) + - icon: fontawesome/brands/github + link: https://github.com/oxsecurity/codetotal + - icon: fontawesome/brands/docker + link: https://hub.docker.com/r/oxsecurity/codetotal + generator: false +nav: + - "Home": "index.md" + - "Quick Start": "quick-start.md" + - "Contribute": "contributing.md" + - "License": + - "AGPL V3 License": "license.md" + - "License explanations": "license-explanations.md" + - "Changelog": "CHANGELOG.md"