Skip to content

Commit d0e531a

Browse files
authored
Minor changes to README (#11)
1 parent 1d0d69e commit d0e531a

File tree

2 files changed

+35
-29
lines changed

2 files changed

+35
-29
lines changed

README.md

Lines changed: 34 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ We shall continue to add more features and would be happy to accept contribution
1515

1616
### TL;DR
1717

18-
Analyze a python project django located in the folder ```/tmp/django``` by running the security and quality QL pack on it:
18+
Analyze the python project django located in the folder ```/tmp/django``` by running the security and quality QL pack on it:
1919

2020
```
2121
/scripts/unix/analyze_security.sh /tmp/django/src /tmp/django/results python
@@ -30,25 +30,37 @@ scripts/unix/run_qlpack.sh /tmp/express/src /tmp/express/results javascript secu
3030

3131
The results will be stored in /tmp/express/results/issues.sarif
3232

33-
To find a list of installed QL packs in the container:
33+
To find a list of QL packs installed in the container:
3434

3535
```
3636
docker run --rm --name codeql-container -e CODEQL_CLI_ARGS="resolve qlpacks" mcr.microsoft.com/cstsectools/codeql-container
3737
```
3838

39-
### Basic Usage
40-
41-
#### Downloading a pre-built container
39+
### Downloading a pre-built container
4240

43-
We keep updating the docker image periodically and uploading it to the Microsoft Container Registry at: mcr.microsoft.com/codeql/codeql-container.
41+
We keep updating the docker image periodically and uploading it to the Microsoft Container Registry at: ```mcr.microsoft.com/codeql/codeql-container```.
4442

4543
You can pull the image by running the command:
4644
```
4745
$ docker pull mcr.microsoft.com/cstsectools/codeql-container
4846
```
49-
The codeQL container executes one codeQL command per invocation. We kept this design decision because it makes it easy for the user to run any codeQL command, and not be bound by the automation scripts inside the container.
5047

51-
So, if you want to analyze a particular source directory with the container, you start by running the container as:
48+
49+
### Building the container from Dockerfile
50+
51+
Building the container should be pretty straightforward.
52+
53+
```
54+
git clone https://github.com/microsoft/codeql-container
55+
cd codeql-container
56+
docker build . -f Dockerfile -t codeql-container
57+
```
58+
59+
### Basic Usage
60+
61+
The codeQL container executes one codeQL command per invocation. We designed it this way because it makes it easy for the user to run any codeQL command, and not be bound by the automation scripts inside the container.
62+
63+
The basic example format of the container invocation is as follows:
5264

5365
```
5466
$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS=<query run...> mcr.microsoft.com/cstsectools/codeql-container
@@ -59,15 +71,15 @@ needs to be stored, and you can specify CODEQL_CLI_ARGS environment variable for
5971

6072
For more information on CodeQL and QL packs, please visit https://www.github.com/github/codeql.
6173

62-
`CODEQL_CLI_ARGS` are the arguments that will be directly passed on to the codeql-cli. For example:
74+
`CODEQL_CLI_ARGS` are the arguments that will be directly passed on to the codeql-cli. For example, in this case, if we supply:
6375

6476
```
6577
CODEQL_CLI_ARGS="database create /opt/results/source_db -s /opt/src"
6678
```
6779

68-
This argument will create a codeQL db of your project (that you have mapped to the /opt/src folder above) in the /opt/results folder, which maps to /dir/for/results above on your local computer.
80+
it will create a codeQL db of your project (in ```/dir/to/analyze``` ) in the ```/dir/for/results``` folder.
6981

70-
> **Note:** If you map your source volume to some other mountpoint other than /opt/src, you will have to make the corresponding changes
82+
> **Note:** If you map your source volume to some other mount point other than /opt/src, you will have to make the corresponding changes
7183
> in the `CODEQL_CLI_ARGS`.
7284
7385
There are some additional docker environment flags that you can set/unset to control the execution of the container:
@@ -85,29 +97,23 @@ For example, if you want to analyze a python project source code placed in `/dir
8597
to analyze and get a SARIF result file, you will have to run:
8698

8799
```
100+
# create the codeql db
88101
$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS="database create --language=python /opt/results/source_db -s /opt/src" mcr.microsoft.com/cstsectools/codeql-container
102+
103+
# upgrade the db if necessary
89104
$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS=" database upgrade /opt/results/source_db" mcr.microsoft.com/cstsectools/codeql-container
90-
$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS="database analyze --format=sarifv2 --output=/opt/results/issues.sarif /opt/results/source_db" mcr.microsoft.com/cstsectools/codeql-container
105+
106+
# run the queries in the qlpack
107+
$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS="database analyze --format=sarifv2 --output=/opt/results/issues.sarif /opt/results/source_db qlpack.qps" mcr.microsoft.com/cstsectools/codeql-container
91108
```
92109

93110
For more information on CodeQL and QL packs, please visit https://www.github.com/github/codeql.
94111

95-
#### Building the container
96-
97-
Building the container should be pretty straightforward.
98-
99-
```
100-
git clone https://github.com/microsoft/codeql-container
101-
cd codeql-container
102-
docker build . -f Dockerfile -t codeql-container
103-
```
104-
105-
# Convenience Scripts
112+
### Convenience Scripts
106113
Analyzing a source directory takes multiple invocations of the container, as mentioned above. To help with that, we've built some scripts for convenience, which does these invocations for you.
107114
These scripts are in the ```scripts``` folder, under their respective platforms (unix or windows).
108115

109-
110-
##### analyze_security.sh
116+
#### analyze_security.sh
111117
scripts/unix/analyze_security.sh (or scripts/windows/analyze_security.bat for windows) runs the Security and Quality QL pack suite on your project. This is how you would run it:
112118

113119
```
@@ -125,8 +131,8 @@ for JavaScript:
125131
/scripts/unix/analyze_security.sh /tmp/express/src /tmp/express/output javascript
126132
```
127133

128-
##### run_qlpack.sh
129-
If you know which QL suite you would like to run on the code to be analyzed, use scripts/unix/run_qlpack.sh (or scripts/windows/run_qlpack.bat for windows).
134+
#### run_qlpack.sh
135+
If you know which QL suite you would like to run on the code, use scripts/unix/run_qlpack.sh (or scripts/windows/run_qlpack.bat for windows).
130136

131137
```
132138
scripts/unix/run_qlpack.sh /path/to/analyze /path/to/results language qlpack
@@ -138,7 +144,7 @@ For example, on windows:
138144
scripts\windows\run_ql_suite.bat e:\temp\express\src e:\temp\express\results javascript code-scanning
139145
```
140146

141-
# Contributing
147+
### Contributing
142148

143149
This project welcomes contributions and suggestions. Most contributions require you to agree to a
144150
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us

scripts/windows/run_ql_suite.bat

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ if %errorlevel% GTR 0 (
4646
)
4747

4848
if %errorlevel% EQU 0 (
49-
call :print_yellow "The results file are saved at at %2\issues.sarif"
49+
call :print_yellow "The results file are saved at %2\issues.sarif"
5050
)
5151

5252
:print_yellow

0 commit comments

Comments
 (0)