Separate-docs-for-each-tool (#2012)

* Remove links to local anchors. Point to GitHub instead

* Update to follow common doc format

* Added required permissions

* Fixes #2006

* Add example with URL

* Update CLI options details

* Fix doc on --languages options (not -l)

* remove docker doc left by mistake

* Link to common parameters in GH

* Update common parameters

* Removed remaining relative links

* Separate docker docs

* Remove duplicate section

Author: okorach

README.md

@@ -0,0 +1,41 @@
+# Using sonar-tools in Docker
+
+Starting from version 3.4 `sonar-tools` is available as a docker image. Here is how to use the docker version:
+
+## Installation
+
+  - Run: `docker pull olivierkorach/sonar-tools:latest` to install
+
+## Usage
+
+```
+docker pull olivierkorach/sonar-tools:latest
+# Run `docker run --rm olivierkorach/sonar-tools` followed by your usual sonar-tools command with its parameters, and example below for sonar-loc
+docker run --rm olivierkorach/sonar-tools sonar-loc -u <YOUR_SONAR_URL> -t <YOUR_SONAR_TOKEN> <parameters>
+
+# Alternatively you can pass the Sonar(Qube/Cloud) URL and token as environment variables
+docker run --rm -e SONAR_TOKEN=<YOUR_SONAR_TOKEN> -e SONAR_HOST_URL=<YOUR_SONAR_URL> olivierkorach/sonar-tools sonar-loc <parameters>
+
+# Trick if your SonarQube Server is on http://localhost, the URL to pass to docker is http://host.docker.internal, for instance:
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=http://host.docker.internal:9000  olivierkorach/sonar-tools
+
+# The docker image contains all the sonar-tools. Here are other invocation examples
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-measures-export -k <projectKey> -m _all
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-findings-export -h
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-housekeeper -P 90 --mode dry-run --threads 4
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-projects-export
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-config -e --what projects
+```
+
+Be aware that by default, files generated in the container are not available from the host. For files generated by sonar-tools you can either use stdout or volumes
+```
+# The below works, the file config.json is generated on the host
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-config -e > config.json
+
+# The below doesn't work, the file config.json is generated in the container and, by default, not accessible from the host
+docker run --rm -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-config -e -f config.json
+
+# If you want the 2nd form above to work you must use volumes, for instance:
+docker run --rm -w `pwd` -v `pwd`:`pwd` -e SONAR_TOKEN=$SONAR_TOKEN -e SONAR_HOST_URL=https://sonar.acme.com olivierkorach/sonar-tools sonar-config -e -f config.json
+# After the command the file config.json should be in the local (pwd) directory
+```

doc/docker.md

@@ -3,19 +3,21 @@
 Command line tool to audit a SonarQube instance and output warning logs whenever a suspicious or incorrect setting/situation is found.
 The detail of what is audited is listed at the bottom of this page
 
-## Requirements and Installation
+## Required Permissions
 
-`sonar-audit` is installed through the **sonar-tools** [general installation](../README.md#install)
+`sonar-audit` needs `Browse` and `Administer` permission on more or less everything that may be audited
+
+## Requirements and Installation
 
-:warning: **sonar-tools** 2.7 or higher is required for `sonar-audit` compatibility with SonarQube 10
+`sonar-audit` is installed through the **sonar-tools** [general installation](https://github.com/okorach/sonar-tools/blob/master/README.md#install)
 
 ## Common command line parameters
 
-`sonar-audit` accepts all the **sonar-tools** [common parameters](../README.md#common-params)
+`sonar-audit` accepts all the **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
 
 ## Usage
 
-`sonar-audit [-u <url>] [-t <token>] [--what <auditSelection>] [--sif <SIF>] [-f <file>] [--format [json|csv]] [-h] [-v <debugLevel>]`
+`sonar-audit [--what <auditSelection>] [--sif <SIF>] [-f <file>] [--format [json|csv]]`
 
 `--what` can be followed by a list of comma separated items to audit.
 When `--what` is not specified, everything is audited
@@ -37,11 +39,7 @@ When `--what` is not specified, everything is audited
 - `--format [json|csv]`: Generates output in JSON or CSV format (CSV is the default)
 - `--csvSeparator <separator>`: Allows to select the separator character for CSV, `,` is the default
 - `-h`: Displays help and exits
-- `-u`, `-t`, `-h`, `-v`, `--httpTimeout`, `--threads`: See **sonar-tools** [common parameters](../README.md#common-params)
-
-## Required Permissions
-
-To be able to audit everything, the token provided to `sonar-audit` should have the global `Administer System` permission and `Browse`and `Administer` permission on all projects.
+- `-h`, `-u`, `-t`, `-o`, `-v`, `-l`, `--httpTimeout`, `--threads`, `--clientCert`: See **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
 
 ## Configuration file
 

doc/sonar-audit.md

@@ -8,17 +8,21 @@ During import:
 - When the object already exists it is updated according to the config file
 - When an object exists in the target platform and is not defined in the config file, this object remains unmodified. As such the import of configuration is "additive" to the current config, it does not replace it.
 
+## Required Permissions
+
+`sonar-config` needs `Browse` and `Administer` permission on more or less everything that may be exported or imported
+
 ## Requirements and Installation
 
-`sonar-config` is installed through the **sonar-tools** [general installation](../README.md#install)
+`sonar-config` is installed through the **sonar-tools** [general installation](https://github.com/okorach/sonar-tools/blob/master/README.md#install)
 
 ## Common command line parameters
 
-`sonar-config` accepts all the **sonar-tools** [common parameters](../README.md#common-params)
+`sonar-config` accepts all the **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
 
 ## Usage
 
-`sonar-config [-u <url>] [-t <token>] [-e|--export] [-i|--import] [-w|--what <configSelection>] [-f <file>] [-h] [-v <debugLevel>] [-k "<key1>,<key2>,...,<keyn>"]`
+`sonar-config [-e|--export] [-i|--import] [-w|--what <configSelection>] [-f <file>] [-h] [-k "<key1>,<key2>,...,<keyn>"]`
 
 `--what` can be followed by a list of comma separated items to export or import
 When `--what` is not specified, everything is exported or 
@@ -36,7 +40,7 @@ When `--what` is not specified, everything is exported or
 - `-k "<key1>,<key2>,...,<keyn>"`: Limits the export or import operation to projects, apps or portfolios matching these keys
 - `--fullExport`: Will also export object properties that are not used for an import by may be of interest anyway
 - `-h`: Displays help and exits
-- `-u`, `-t`, `-h`, `-v`: See **sonar-tools** [common parameters](../README.md#common-params)
+- `-h`, `-u`, `-t`, `-o`, `-v`, `-l`, `--httpTimeout`, `--threads`, `--clientCert`: See **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
 
 ## Required Permissions
 

doc/sonar-config.md

@@ -0,0 +1,63 @@
+# sonar-findings-export
+(Also available as `sonar-issues-export` for backward compatibility, but **deprecated**)
+
+Exports a list of issues as CSV, JSON or SARIF format. The export is sent to standard output or into a file
+Plenty of issue filters can be specified from the command line, type `sonar-findings-export -h` for details.
+:warning: On large SonarQube Server or Cloud instances with a lot of issues, it can be stressful for the instance (many API calls) and very long to export all issues. It's recommended to define filters that will only export a subset of all issues (see examples below).
+
+Basic Usage: `sonar-findings-export [--format csv|json|sarif] [--sarifNoCustomProperties] [-k <keyList>] ...`
+
+- `--format csv|json|sarif`: Choose export format. Default is based on output file extension, and csv in last - `--sarifNoCustomProperties`: For SARIF export. By default all Sonar custom properties are exported which makes the SARIF export quite verbose. Use this option to not export the Sonar custom properties (only the SARIF standard ones)
+- `--statuses <statusList>`: Only export findings with given statuses, comma separated among OPEN,CONFIRMED,REOPENED,RESOLVED,CLOSED,TO_REVIEW,REVIEWED
+- `--resolutions <resolutionList>`: Only export findings with given resolution, comma separated among FALSE-POSITIVE,WONTFIX,FIXED,REMOVED,ACCEPTED,SAFE,ACKNOWLEDGED,FIXED
+- `--severities <severityList>`: Only export findings with given resolution, comma separated among BLOCKER,CRITICAL,MAJOR,MINOR,INFO
+- `--types <typeList>`: Only export findings with given type, comma separated among BUG,VULNERABILITY,CODE_SMELL,SECURITY_HOTSPOT
+- `--createdAfter <YYYY-MM-DD>`: Only export findings created after a given date
+- `--createdBefore <YYYY-MM-DD>`: Only export findings created before a given date
+- `--tags <tagList>`: Comma separated list of tags corresponding to issues
+- `--languages <languageList>`: Comma separated list of languages from whom findings should be exported
+- `--useFindings`: Use SonarQube Server `api/projects/export_findings` whenever possible, No effect with SonarQube Cloud
+- `-k <keyList>`: Comma separated list of keys of objects to export (all objects if not specified)
+- `-b <branchList>`: For projects and apps, comma separated list of branches to export (Use * for all branches)
+- `--datesWithoutTime`: Reports timestamps only with date, not time
+- `-h`, `-u`, `-t`, `-o`, `-v`, `-l`, `--httpTimeout`, `--threads`, `--clientCert`: See **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
+
+
+## Required Permissions
+
+`sonar-findings-export` needs `Browse` permission on all projects, applications or portfolios for which findings are exported
+
+## Requirements and Installation
+
+`sonar-findings-export` is installed through the **sonar-tools** [general installation](https://github.com/okorach/sonar-tools/blob/master/README.md#install)
+
+## Common command line parameters
+
+`sonar-config` accepts all the **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
+
+## Examples
+```
+export SONAR_HOST_URL=https://sonar.acme-corp.com
+export SONAR_TOKEN=squ_83356c9b2db891d45da2a119a29cdc4d03fe654e
+
+# Exports all issues (main branch). This can be very long and stressful for SonarQube APIs
+sonar-findings-export >all_issues.csv
+
+# Exports all issues of project myProjectKey
+sonar-findings-export -k myProjectKey -f project_issues.csv
+
+# Exports all false positive and won't fix issues across all projects
+sonar-findings-export -r FALSE-POSITIVE,WONTFIX -f fp_wf.json
+
+# Exports all issues created in 2020
+sonar-findings-export -a 2020-01-01 -b 2020-12-31 -f issues_created_in_2020.csv
+
+# Exports all vulnerabilities and bugs
+sonar-findings-export -types VULNERABILITY,BUG --format json >bugs_and_vulnerabilities.json
+
+# Exports all vulnerabilities and bugs in SARIF format
+sonar-findings-export -types VULNERABILITY,BUG --format sarif >bugs_and_vulnerabilities.sarif.json
+
+# Export all findings of project myProjectKey in SARIF format without the custom Sonar properties
+sonar-findings-export -k myProjectKey ----sarifNoCustomProperties -f myProjectKey.sarif
+```

doc/sonar-findings-export.md

@@ -7,11 +7,11 @@ When the source or target is a Community Edition/Build then only the main branch
 
 ## Requirements and Installation
 
-`sonar-findings-sync` is installed through the **sonar-tools** [general installation](../README.md#install)
+`sonar-findings-sync` is installed through the **sonar-tools** [general installation](https://github.com/okorach/sonar-tools/blob/master/README.md#install)
 
 ## Common command line parameters
 
-`sonar-findings-sync` accepts all the **sonar-tools** [common parameters](../README.md#common-params)
+`sonar-findings-sync` accepts all the **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
 
 ## Usage
 
@@ -30,7 +30,8 @@ When the source or target is a Community Edition/Build then only the main branch
 the target token.
 - `--nolink`: Do not add a HTTP link comment in the source and target findings (that point at each other)
 - `--tag`: Defines the tag applied to synchronized issues, default is `synchronized`. Use `--tag ''` to not tag the issues
-- `-u`, `-t`, `-h`, `-v`: See **sonar-tools** [common parameters](../README.md#common-params)
+- `-h`, `-u`, `-t`, `-o`, `-v`, `-l`, `--httpTimeout`, `--threads`, `--clientCert`: See **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
+
 
 :warning: Note about `-t` and `-T`: It is **strongly recommended** to run `sonar-findings-sync` with the credentials of a specific service account dedicated to issues synchronization on the target. This will allow to recognize automatic synchronization changes by the author of those changes. This token is either the one provided with `-t` when the synchronization is within the same SonarQube Server or Cloud (for instance 2 branches of a same project), or `-T` when synchronizing between 2 different SonarQube Server or Cloud instances (The `-T <token>` corresponding to a user on the **target** SonarQube Server or Cloud in that case)
 

doc/sonar-findings-sync.md

@@ -0,0 +1,48 @@
+# <a name="sonar-housekeeper">
+
+Deletes obsolete/outdated data from SonarQube:
+- Projects whose last analysis date (on any branch) is older than a given number of days.
+- User tokens older than a given number of days
+- Inactive branches (Branches not analyzed for a given number of days), excepted branches marked as "keep when inactive"
+- Inactive pull requests (PRs not analyzed for a given number of days)
+
+Usage: `sonar-housekeeper [-P <days>] [-B <days>] [-R <days>] [-T <days>] [--mode delete]`
+
+- `-P <days>`: Will search for projects not analyzed since more than `<days>` days.
+To avoid deleting too recent projects it is denied to specify less than 90 days
+- `-B <days>`: Will search for projects branches not analyzed since more than `<days>` days.
+Branches marked as "keep when inactive" are excluded from housekeeping
+- `-R <days>`: Will search for pull requests not analyzed since more than `<days>` days
+- `-T <days>`: Will search for tokens created since more than `<days>` days
+- `--mode delete`: If not specified, `sonar-housekeeper` will only perform a dry run and list projects
+branches, pull requests and tokens that would be deleted.
+If `--mode delete` is specified objects are actually deleted
+- `-h`, `-u`, `-t`, `-o`, `-v`, `-l`, `--httpTimeout`, `--threads`, `--clientCert`: See **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
+
+
+:warning: **sonar-tools** 2.7 or higher is required for `sonar-housekeeper` compatibility with SonarQube Server 10
+
+## Required Permissions
+
+To be able to delete anything, the token provided to `sonar-housekeeper` should have:
+- The global `Administer System` permission to delete tokens
+- Plus `Browse` and `Administer` permission on all projects to delete (or with branches or PR to delete)
+
+## Requirements and Installation
+
+`sonar-housekeeper` is installed through the **sonar-tools** [general installation](https://github.com/okorach/sonar-tools/blob/master/README.md#install)
+
+## Common command line parameters
+
+`sonar-housekeeper` accepts all the **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
+
+### :information_source: Limitations
+To avoid bad mistakes (mistakenly deleting too many projects), the tools will refuse to delete projects analyzed in the last 90 days.
+
+### :warning: Database backup
+**A database backup should always be taken before executing this script. There is no recovery.**
+
+### Example
+```
+sonar-housekeeper -u https://sonar.acme-corp.com -t 15ee09df11fb9b8234b7a1f1ac5fce2e4e93d75d
+```

doc/sonar-housekeeper.md

@@ -0,0 +1,30 @@
+# sonar-loc
+
+Exports all projects lines of code as they would be counted by the commercial licences.
+See `sonar-loc -h` for details
+
+Basic Usage: `sonar-loc [-f <file>] [--format csv|json] [-a] [-n] [--withTags] [--withURL] [--apps] [--portfolios] [--topLevelOnly]`
+- `-f`: Define file for output (default stdout). File extension is used to deduct expected format (json if file.json, csv otherwise)
+- `--format`: Choose export format between csv (default) and json
+- `--projects`: Output the LOC of projects (this is the default if nothing specified)
+- `--apps`: Output the LOC of applications (Developer and higher editions)
+- `--portfolios`: Output the LOC of portfolios (Enterprise and higher editions)
+- `--topLevelOnly`: For portfolios, only output LoCs for top level portfolios (Enterprise Edition only)
+- `-n | --withName`: Outputs the project or portfolio name in addition to the key
+- `-a | --withLastAnalysis`: Output the last analysis date (all branches and PR taken into account) in addition to the LOCs
+- `--withTags`: Outputs the tags of the project, app or portfolio
+- `--withURL`: Outputs the URL of the project, app or portfolio for each record
+- `-b`: Export LoCs for each branches of targeted objects (projects or applications)
+- `-h`, `-u`, `-t`, `-o`, `-v`, `-l`, `--httpTimeout`, `--threads`, `--clientCert`: See **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)
+
+## Required Permissions
+
+`sonar-loc` needs `Browse` permission on all projects of the Server or Cloud instance
+
+## Requirements and Installation
+
+`sonar-loc` is installed through the **sonar-tools** [general installation](https://github.com/okorach/sonar-tools/blob/master/README.md#install)
+
+## Common command line parameters
+
+`sonar-loc` accepts all the **sonar-tools** [common parameters](https://github.com/okorach/sonar-tools/blob/master/README.md)