From 5dbdf764fe781b1db3b1609e6063a9ac9213ccca Mon Sep 17 00:00:00 2001 From: HAHWUL Date: Sun, 19 Jan 2025 16:46:12 +0900 Subject: [PATCH] docs: Enhance documentation with new sections and improved structure Signed-off-by: HAHWUL --- docs/_advanced/configuration.md | 6 + docs/_advanced/deliver.md | 4 +- docs/_advanced/diff.md | 6 + docs/_advanced/passive_scan.md | 6 + .../_advanced/passive_scan/community_rules.md | 2 + docs/_advanced/passive_scan/default_rules.md | 2 + docs/_advanced/passive_scan/rule.md | 2 + docs/_advanced/tagger.md | 6 +- docs/_advanced/tips/community-articles.md | 2 + docs/_get_started/basic.md | 2 + docs/_get_started/installation/docker.md | 2 + docs/_get_started/installation/homebrew.md | 2 + docs/_get_started/installation/snapcraft.md | 2 + docs/_get_started/installation/source.md | 7 +- docs/_get_started/output/curl.md | 2 +- docs/_get_started/output/more.md | 77 ++++++++++-- docs/_get_started/output/openapi.md | 113 ++++++++++++++++++ docs/_get_started/output/yaml.md | 2 + .../supported/language_and_frameworks.md | 2 + docs/_get_started/supported/specification.md | 2 + docs/_get_started/supported/tech-commands.md | 2 + 21 files changed, 229 insertions(+), 22 deletions(-) create mode 100644 docs/_get_started/output/openapi.md diff --git a/docs/_advanced/configuration.md b/docs/_advanced/configuration.md index 0ad5c4cd..e64616e2 100644 --- a/docs/_advanced/configuration.md +++ b/docs/_advanced/configuration.md @@ -6,6 +6,12 @@ permalink: /configuration layout: page --- +## Configuration +{: .d-inline-block } + +Since (v0.16.0) +{: .label .label-green } + {% include toc.md %} ## Config Home Path diff --git a/docs/_advanced/deliver.md b/docs/_advanced/deliver.md index a6a7197e..f9260598 100644 --- a/docs/_advanced/deliver.md +++ b/docs/_advanced/deliver.md @@ -5,9 +5,7 @@ nav_order: 2 layout: page --- -{% include toc.md %} - -## Introduction to Deliver +## Deliver Devlier is a feature designed to transmit Endpoints discovered by Noir to other tools. Unlike Pipelines that use Output, it can forward information to proxy tools such as Caido, ZAP, and Burp, as well as to ElasticSearch. This functionality allows for easier security testing and simplifies finding and utilizing service Endpoints in a DevOps Pipeline. diff --git a/docs/_advanced/diff.md b/docs/_advanced/diff.md index 5b311a71..43c75cda 100644 --- a/docs/_advanced/diff.md +++ b/docs/_advanced/diff.md @@ -5,6 +5,12 @@ nav_order: 6 layout: page --- +## Diff Mode +{: .d-inline-block } + +Since (v0.16.0) +{: .label .label-green } + Diff mode is a feature that analyzes and compares two source code paths using noir, enabling you to identify newly added, modified, or removed APIs. The base path specified with the `-b` flag serves as the reference point, while the source input provided with the `--diff-path` flag is used for comparison. ```bash diff --git a/docs/_advanced/passive_scan.md b/docs/_advanced/passive_scan.md index 8eaceaf5..bb7c9ad0 100644 --- a/docs/_advanced/passive_scan.md +++ b/docs/_advanced/passive_scan.md @@ -5,6 +5,12 @@ nav_order: 4 layout: page --- +## Passive Scan +{: .d-inline-block } + +Since (v0.18.0) +{: .label .label-green } + A Passive Scan is a feature where additional actions are performed by the Detector to identify security issues according to scan rules. This functionality typically includes: * Regular Expression Matching: It uses regular expressions to match patterns that could indicate security vulnerabilities. diff --git a/docs/_advanced/passive_scan/community_rules.md b/docs/_advanced/passive_scan/community_rules.md index 1dc77270..8bd592bd 100644 --- a/docs/_advanced/passive_scan/community_rules.md +++ b/docs/_advanced/passive_scan/community_rules.md @@ -6,6 +6,8 @@ nav_order: 3 layout: page --- +## Community Rules + Community rules are managed in several repositories below. You can clone these repositories to the default rule path for use. To clone the `noir-passive-rules` repository to the default rule path, use the following command: diff --git a/docs/_advanced/passive_scan/default_rules.md b/docs/_advanced/passive_scan/default_rules.md index 8620bf4c..4107b516 100644 --- a/docs/_advanced/passive_scan/default_rules.md +++ b/docs/_advanced/passive_scan/default_rules.md @@ -6,6 +6,8 @@ nav_order: 2 layout: page --- +## Default Rules + The default rules are stored in the following paths based on your operating system: | OS | Path | diff --git a/docs/_advanced/passive_scan/rule.md b/docs/_advanced/passive_scan/rule.md index b7a06d5d..dd5be372 100644 --- a/docs/_advanced/passive_scan/rule.md +++ b/docs/_advanced/passive_scan/rule.md @@ -6,6 +6,8 @@ nav_order: 1 layout: page --- +## Passive Scan Rule + ```yaml id: rule-id info: diff --git a/docs/_advanced/tagger.md b/docs/_advanced/tagger.md index 60b0dbfd..e6afd0a7 100644 --- a/docs/_advanced/tagger.md +++ b/docs/_advanced/tagger.md @@ -5,9 +5,11 @@ nav_order: 3 layout: page --- -{% include toc.md %} +## Tagger +{: .d-inline-block } -## Introduction to Tagger +Since (v0.14.0) +{: .label .label-green } The Tagger is a feature that adds tags to Endpoints, Params, etc., based on given conditions or logic when Noir analyzes source code. By using this feature, you can attach tag information that matches the characteristics of the Endpoints and Params. This helps analysts easily understand Endpoints or gain hints for the next security testing. diff --git a/docs/_advanced/tips/community-articles.md b/docs/_advanced/tips/community-articles.md index ae7dbd80..0f9c8ae5 100644 --- a/docs/_advanced/tips/community-articles.md +++ b/docs/_advanced/tips/community-articles.md @@ -6,6 +6,8 @@ nav_order: 1 layout: page --- +## Community Articles + * [Hello Noir 👋🏼 by HAHWUL](https://www.hahwul.com/2023/08/03/hello-noir/) * [API Attack Surface Detection using Noir by DANA EPP](https://danaepp.com/api-attack-surface-detection-using-noir) * [Exploring OWASP Noir's PassiveScan by HAHWUL](https://www.hahwul.com/2024/11/03/passivescan-in-owasp-noir/) diff --git a/docs/_get_started/basic.md b/docs/_get_started/basic.md index bc5eaca3..aba0b24c 100644 --- a/docs/_get_started/basic.md +++ b/docs/_get_started/basic.md @@ -5,6 +5,8 @@ nav_order: 2 layout: page --- +## Basic Usage + With noir, you can view the help documentation using the `-h` or `--help` flags. ```bash diff --git a/docs/_get_started/installation/docker.md b/docs/_get_started/installation/docker.md index 31d24dbf..b7110a27 100644 --- a/docs/_get_started/installation/docker.md +++ b/docs/_get_started/installation/docker.md @@ -7,6 +7,8 @@ toc: true layout: page --- +## Docker (GHCR) + Docker is a popular containerization platform that simplifies the deployment and management of applications by packaging them into containers. The GitHub Container Registry (GHCR) allows you to store and manage Docker container images within GitHub. ```bash diff --git a/docs/_get_started/installation/homebrew.md b/docs/_get_started/installation/homebrew.md index a0474fc7..6549dc7a 100644 --- a/docs/_get_started/installation/homebrew.md +++ b/docs/_get_started/installation/homebrew.md @@ -7,6 +7,8 @@ toc: true layout: page --- +## Homebrew + Homebrew is the package manager for MacOS(or linux). On devices using homebrew, you can easily install/update using the brew command. ```shell diff --git a/docs/_get_started/installation/snapcraft.md b/docs/_get_started/installation/snapcraft.md index 31cf7461..09f0d129 100644 --- a/docs/_get_started/installation/snapcraft.md +++ b/docs/_get_started/installation/snapcraft.md @@ -7,6 +7,8 @@ toc: true layout: page --- +## Snapcraft + Snapcraft is a powerful package manager for Linux that enables you to easily install and manage applications. It supports a wide range of distributions, making software installation simple and consistent. Ensure you have Snap installed on your system. You can install Snap using your distribution's package manager. For example, on Ubuntu, you can run: diff --git a/docs/_get_started/installation/source.md b/docs/_get_started/installation/source.md index 2a6473c0..828359d2 100644 --- a/docs/_get_started/installation/source.md +++ b/docs/_get_started/installation/source.md @@ -7,17 +7,18 @@ toc: true layout: page --- -## Install Crystal-lang +## Build Noir +### Install Crystal-lang > [https://crystal-lang.org/install/](https://crystal-lang.org/install/) -## Clone this repo +### Clone this repo ```bash git clone https://github.com/owasp-noir/noir cd noir ``` -## Build +### Build ```bash # Install Dependencies shards install diff --git a/docs/_get_started/output/curl.md b/docs/_get_started/output/curl.md index 4a38e111..92fcafd5 100644 --- a/docs/_get_started/output/curl.md +++ b/docs/_get_started/output/curl.md @@ -2,7 +2,7 @@ title: Curl and HTTPie parent: Output Formatting has_children: false -nav_order: 3 +nav_order: 4 layout: page --- diff --git a/docs/_get_started/output/more.md b/docs/_get_started/output/more.md index 8a2ae878..a20a5bb8 100644 --- a/docs/_get_started/output/more.md +++ b/docs/_get_started/output/more.md @@ -6,18 +6,8 @@ nav_order: 4 layout: page --- -## Open API Spec - -```bash -# noir -b . -f oas3 -# noir -b . -f oas2 -``` - -```json -{"openapi":"3.0.0","info":{"title":"Generated by Noir","version":""},"paths":{"/":{"get":{"responses":{"200":{"description":"Successful response"}},"parameters":[{"name":"x-api-key","in":"header"}]}},"/query":{"post":{"responses":{"200":{"description":"Successful response"}},"parameters":[{"name":"my_auth","in":"query"},{"name":"query","in":"formData"}]}},"/token":{"get":{"responses":{"200":{"description":"Successful response"}},"parameters":[{"name":"client_id","in":"formData"},{"name":"redirect_url","in":"formData"},{"name":"grant_type","in":"formData"}]}},"/socket":{"get":{"responses":{"200":{"description":"Successful response"}},"parameters":[]}},"/1.html":{"get":{"responses":{"200":{"description":"Successful response"}},"parameters":[]}},"/2.html":{"get":{"responses":{"200":{"description":"Successful response"}},"parameters":[]}}}} -``` - -## Only-x +## Only X +### URL ```bash noir -b . -f only-url # ... @@ -27,4 +17,65 @@ noir -b . -f only-url # /socket # /1.html # /2.html -``` \ No newline at end of file +``` + +### Param +```bash +noir -b . -f only-param +# ... +# query +# client_id +# redirect_url +# grant_type +``` + +### Header +```bash +noir -b . -f only-header +# ... +# x-api-key +# Cookie +``` + +### Cookie +```bash +noir -b . -f only-cookie +# ... +# my_auth +``` + +### Tag + +```bash +noir -b . -f only-tag -T +# ... +# sqli +# oauth +# websocket +``` + +## Markdown + +```bash +noir -b . -f markdown-table +``` + +```markdown +| Endpoint | Protocol | Params | +| -------- | -------- | ------ | +| GET / | http | `x-api-key (header)` | +| POST /query | http | `my_auth (cookie)` `query (form)` | +| GET /token | http | `client_id (form)` `redirect_url (form)` `grant_type (form)` | +| GET /socket | ws | | +| GET /1.html | http | | +| GET /2.html | http | | +``` + +| Endpoint | Protocol | Params | +| -------- | -------- | ------ | +| GET / | http | `x-api-key (header)` | +| POST /query | http | `my_auth (cookie)` `query (form)` | +| GET /token | http | `client_id (form)` `redirect_url (form)` `grant_type (form)` | +| GET /socket | ws | | +| GET /1.html | http | | +| GET /2.html | http | | \ No newline at end of file diff --git a/docs/_get_started/output/openapi.md b/docs/_get_started/output/openapi.md new file mode 100644 index 00000000..0731460c --- /dev/null +++ b/docs/_get_started/output/openapi.md @@ -0,0 +1,113 @@ +--- +title: Open API Spec +parent: Output Formatting +has_children: false +nav_order: 3 +layout: page +--- + +## Open API Spec (OAS) + +```bash +# noir -b . -f oas3 +# noir -b . -f oas2 +``` + +```json +{ + "openapi": "3.0.0", + "info": { + "title": "Generated by Noir", + "version": "" + }, + "paths": { + "/": { + "get": { + "responses": { + "200": { + "description": "Successful response" + } + }, + "parameters": [ + { + "name": "x-api-key", + "in": "header" + } + ] + } + }, + "/query": { + "post": { + "responses": { + "200": { + "description": "Successful response" + } + }, + "parameters": [ + { + "name": "my_auth", + "in": "query" + }, + { + "name": "query", + "in": "formData" + } + ] + } + }, + "/token": { + "get": { + "responses": { + "200": { + "description": "Successful response" + } + }, + "parameters": [ + { + "name": "client_id", + "in": "formData" + }, + { + "name": "redirect_url", + "in": "formData" + }, + { + "name": "grant_type", + "in": "formData" + } + ] + } + }, + "/socket": { + "get": { + "responses": { + "200": { + "description": "Successful response" + } + }, + "parameters": [] + } + }, + "/1.html": { + "get": { + "responses": { + "200": { + "description": "Successful response" + } + }, + "parameters": [] + } + }, + "/2.html": { + "get": { + "responses": { + "200": { + "description": "Successful response" + } + }, + "parameters": [] + } + } + } +} +``` \ No newline at end of file diff --git a/docs/_get_started/output/yaml.md b/docs/_get_started/output/yaml.md index 0b9ee3e2..77e52504 100644 --- a/docs/_get_started/output/yaml.md +++ b/docs/_get_started/output/yaml.md @@ -6,6 +6,8 @@ nav_order: 2 layout: page --- +## YAML + ```bash noir -b . -f yaml --no-log ``` diff --git a/docs/_get_started/supported/language_and_frameworks.md b/docs/_get_started/supported/language_and_frameworks.md index 5ed6b8c1..50e52ceb 100644 --- a/docs/_get_started/supported/language_and_frameworks.md +++ b/docs/_get_started/supported/language_and_frameworks.md @@ -6,6 +6,8 @@ parent: Supported layout: page --- +## Language and Frameworks + {% include toc.md %} ## Crystal diff --git a/docs/_get_started/supported/specification.md b/docs/_get_started/supported/specification.md index bbafd346..b1454049 100644 --- a/docs/_get_started/supported/specification.md +++ b/docs/_get_started/supported/specification.md @@ -6,6 +6,8 @@ parent: Supported layout: page --- +## Specification + | Specification | Format | URL | Method | Param | Header | WS | |------------------------|---------|-----|--------|-------|--------|----| | OAS 2.0 (Swagger 2.0) | JSON | ✅ | ✅ | ✅ | ✅ | X | diff --git a/docs/_get_started/supported/tech-commands.md b/docs/_get_started/supported/tech-commands.md index 3ac7ae73..87ec8c50 100644 --- a/docs/_get_started/supported/tech-commands.md +++ b/docs/_get_started/supported/tech-commands.md @@ -6,6 +6,8 @@ nav_order: 4 layout: page --- +## Tech Commands + ```bash # Force scanning to techs noir -t rails