Skip to content

Commit 80fd67d

Browse files
authored
Merge pull request #10 from CodeIntelligenceTesting/fix-readme
refactor: update README.md files for example projects
2 parents 4397ac1 + 17fd4d0 commit 80fd67d

File tree

15 files changed

+106
-125
lines changed

15 files changed

+106
-125
lines changed

example-projects/advanced-setup/bazel/README.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
## Project Description
22

3-
This is an extended example Bazel project with multiple packages and
4-
two fuzztests `main/tests:explore_me_fuzz_test` and `fuzztests:test_me_fuzz_test`.
3+
This is a Bazel project configured with **cifuzz** which includes:
54

6-
The `explore_me_fuzz_test` is defined in the same package as the source
7-
code and `test_me_fuzz_test` is located in a separated package.
5+
- multiple packages
6+
- two Fuzz Tests
7+
- `main/tests:explore_me_fuzz_test`, defined in the same package as the source
8+
code
9+
- `fuzztests:test_me_fuzz_test`, located in a separated package
810

911
## Run
1012

@@ -28,7 +30,8 @@ cifuzz run fuzztests:test_me_fuzz_test
2830
cifuzz bundle main/tests:explore_me_fuzz_test
2931
```
3032

31-
Should include one fuzz test with two targets to cover fuzzing and coverage builds.
33+
The bundle should include **1** Fuzz Test with **2** targets to cover fuzzing
34+
and coverage builds:
3235

3336
```
3437
...
@@ -45,7 +48,8 @@ path: replayer/coverage/main/tests/explore_me_fuzz_test/bin/explore_me_fuzz_test
4548
cifuzz bundle
4649
```
4750

48-
Should include one fuzz test with two targets to cover fuzzing and coverage builds.
51+
The bundle should include **1** Fuzz Test with **2** targets to cover fuzzing
52+
and coverage builds:
4953

5054
```
5155
...

example-projects/advanced-setup/cmake/README.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
## Project Description
22

3-
This is an extended example CMake project which includes two fuzz tests
4-
`test_me_fuzztest`and `explore_me_fuzztest` in a multiple package setup.
3+
This is a CMake project configured with **cifuzz* which includes:
4+
5+
- multiple packages
6+
- two Fuzz Tests
7+
- `test_me_fuzztest`
8+
- `explore_me_fuzztest`
59

610
## Run
711

@@ -23,8 +27,8 @@ cifuzz run test_me_fuzztest
2327
cifuzz bundle
2428
```
2529

26-
Should include both fuzz tests with four targets in total to cover
27-
fuzzing and coverage builds.
30+
The bundle should include **2** Fuzz Tests with **4** targets in total to cover
31+
fuzzing and coverage builds:
2832

2933
```
3034
...

example-projects/advanced-setup/gradle/README.md

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
## Project Description
22

3-
This is an extended example gradle project which covers custom project setups:
3+
This is a Gradle project configured with **cifuzz** which includes:
44

5-
- multiple fuzz tests in one class
6-
- mixed unit and fuzz tests in one class
5+
- class with multiple Fuzz Tests
6+
- class with mixed Unit and Fuzz Tests
77
- changed source directory for test source set
88
- multi-project layout
9-
- more than one fuzzable class (with different findings)
109

1110
## Run
1211

@@ -38,7 +37,7 @@ cifuzz run -C testsuite com.example.RCEFuzzTestCase::fuzzTestDontTrigger
3837
cifuzz -C app bundle
3938
```
4039

41-
Should include **1** fuzz test
40+
The bundle should include **1** Fuzz Test:
4241

4342
- `com.example.TestCases::remoteCodeFuzzTest`
4443

@@ -48,7 +47,7 @@ Should include **1** fuzz test
4847
cifuzz -C testsuite bundle
4948
```
5049

51-
Should include **3** fuzz tests
50+
The bundle should include **3** Fuzz Tests:
5251

5352
- `com.example.OutOfBoundsTestCase::fuzzTest`
5453
- `com.example.RCEFuzzTestCase::fuzzTestTrigger`

example-projects/advanced-setup/maven/README.md

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,16 @@
11
## Project Description
22

3-
This is an extended example maven project which covers custom project setups:
3+
This is an Maven project configured with **cifuzz** which includes:
44

5-
- multiple fuzz tests in one class
6-
- mixed unit and fuzz tests in one class
5+
- class with multiple Fuzz Tests
6+
- class with mixed Unit and Fuzz Tests
77
- changed source directory for test source set
88
- multi-project layout
9-
- more than one fuzzable class (with different findings)
10-
11-
Right now we do not support a multi module project setup with maven so this project has two `cifuzz.yaml`,
12-
one in the module `tests` and one in `util`.
139

1410
## Setup
1511

16-
To run the fuzz tests, the Maven `install` command needs to be run to be able to resolve all dependencies.
12+
To run the fuzz tests, the Maven `install` command needs to be called to be able
13+
to resolve all dependencies.
1714

1815
```
1916
mvn -Dmaven.test.skip=true install
@@ -44,7 +41,7 @@ cifuzz -C tests run NegativeArraySizeFuzzTest::fuzzTest
4441
cifuzz -C tests bundle
4542
```
4643

47-
Should include **2** fuzz tests
44+
The bundle should include **2** Fuzz Tests:
4845

4946
- `NegativeArraySizeFuzzTest::fuzzTest`
5047
- `UtilFuzzTest::fuzzTest`
@@ -55,6 +52,6 @@ Should include **2** fuzz tests
5552
cifuzz -C util bundle
5653
```
5754

58-
Should include **1** fuzz test
55+
The bundle should include **1** Fuzz Test:
5956

6057
- `util.UtilTest::joinFuzzTest`

example-projects/advanced-setup/other/README.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
## Project Description
22

3-
This is an extended example project categorized under build system "other".
4-
It includes two fuzz tests
5-
`main/tests/explore_me_fuzztest` and `fuzztests/test_me_fuzztest` in a multiple package
6-
setup and one corresponding Makefile.
3+
This is a C++ Make project configured with **cifuzz**, which includes:
4+
5+
- multiple packages
6+
- one Makefile
7+
- two Fuzz Tests
8+
- `main/tests/explore_me_fuzztest`
9+
- `fuzztests/test_me_fuzztest`
710

811
## Run
912

@@ -27,7 +30,8 @@ cifuzz run fuzztests/test_me_fuzztest
2730
cifuzz bundle main/tests/explore_me_fuzztest
2831
```
2932

30-
Should include the fuzz test with two targets to cover fuzzing and coverage builds.
33+
The bundle hould include **1** Fuzz Test with **2** targets to cover fuzzing and
34+
coverage builds:
3135

3236
```
3337
...

example-projects/simple-setup/bazel/README.md

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
1-
# cifuzz bazel example
1+
## Project Description
22

3-
This is a simple bazel based project, already configured with
4-
**cifuzz**. It should quickly produce a finding, but slow enough to
5-
see the progress of the fuzzer.
3+
This is a simple Bazel project configured with **cifuzz** and has
4+
one Fuzz Test.
65

7-
You can start the fuzzing with
6+
## Run
87

98
```bash
10-
cifuzz run //src:explore_me_fuzz_test
9+
cifuzz run src:explore_me_fuzz_test
1110
```
1211

12+
The Fuzz Test should trigger a Heap Buffer Overflow.
13+
1314
## Create regression test
1415

15-
After you have discovered a finding, you may want to include this as
16+
After you have discovered a Finding, you may want to include this as
1617
part of a regression test. To replay findings from the
1718
`src/explore_me_fuzz_test_inputs` directory:
1819

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,21 @@
1-
# cifuzz CMake example
1+
## Project Description
22

3-
This is a simple CMake based project, already configured with
4-
**cifuzz**. It should quickly produce a finding, but slow enough to
5-
see the progress of the fuzzer.
3+
This is a simple CMake project configured with **cifuzz** and hasone
4+
Fuzz Test.
65

7-
You can start the fuzzing with
6+
## Run
87

98
```bash
109
cifuzz run my_fuzz_test
1110
```
1211

12+
The Fuzz Test should trigger a Heap Buffer Overflow.
13+
1314
## Create regression test
1415

1516
After you have discovered a finding, you may want to include this as
16-
part of a regression test. This can be done by building the fuzz test
17-
(my_fuzz_test) as a replayer binary. It is recommended to use the
17+
part of a regression test. This can be done by building the Fuzz Test
18+
(`my_fuzz_test`) as a replayer binary. It is recommended to use the
1819
provided CMake user presets, which can be generated with `cifuzz integrate cmake`.
1920

2021
```bash
@@ -24,4 +25,4 @@ cmake --build --preset="cifuzz (Regression Test)"
2425

2526
To execute the replayer binary, run `./.cifuzz-build/replayer/address+undefined/my_fuzz_test`.
2627
When you run the replayer binary, it will use any findings located in
27-
the my_fuzz_test_inputs directory as input.
28+
the `my_fuzz_test_inputs` directory as input.
Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# cifuzz Gradle example
1+
## Project Description
22

3-
This is a simple Gradle based project with both JUnit 4 and JUnit 5 unit tests
4-
and a fuzz test.
5-
It should quickly produce a finding, but slow enough to
6-
see the progress of the fuzzer.
3+
This is a simple Gradle Java project configured with **cifuzz** and includes
4+
one Fuzz Test and one JUnit 4 as well as one JUnit 5 Unit Test, demonstrating
5+
the use of the `junit-vintage-engine`.
76

8-
You can start fuzzing with
7+
## Run
98

109
```bash
1110
cifuzz run com.example.ExploreFuzzTest::myFuzzTest
1211
```
12+
The Fuzz Test should trigger a Remote Code Execution.
13+

example-projects/simple-setup/gradle-kotlin/README.md

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,17 @@
1-
# cifuzz Gradle example
1+
## Project Description
22

3-
This is a simple Gradle based Kotlin project, already configured with
4-
**cifuzz**. It should quickly produce a finding, but slow enough to
5-
see the progress of the fuzzer.
3+
This is a simple Gradle Kotlin project configured with **cifuzz** and includes
4+
one Fuzz Test.
65

7-
You can start fuzzing with
6+
## Run
87

98
```bash
109
cifuzz run com.example.FuzzTestCase::myFuzzTest
1110
```
1211

13-
## Coverage
14-
15-
cifuzz can generate Java coverage reports using
16-
[jacoco](https://www.jacoco.org). This example is configured to use both HTML
17-
and XML (e.g. for IDE support) as output formats.
12+
The Fuzz Test should trigger a Remote Code Execution.
1813

19-
Run the coverage command after your cifuzz run:
14+
## Coverage
2015

2116
```bash
2217
cifuzz coverage com.example.FuzzTestCase::myFuzzTest

example-projects/simple-setup/gradle/README.md

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,17 @@
1-
# cifuzz Gradle example
1+
## Project Description
22

3-
This is a simple Gradle based Java project, already configured with
4-
**cifuzz**. It should quickly produce a finding, but slow enough to
5-
see the progress of the fuzzer.
3+
This is a simple Gradle Java project configured with **cifuzz** and has
4+
one Fuzz Test.
65

7-
You can start fuzzing with
6+
## Run
87

98
```bash
109
cifuzz run com.example.FuzzTestCase::myFuzzTest
1110
```
1211

13-
## Coverage
14-
15-
cifuzz can generate Java coverage reports using
16-
[jacoco](https://www.jacoco.org). This example is configured to use both HTML
17-
and XML (e.g. for IDE support) as output formats.
12+
The Fuzz Test should trigger a Remote Code Execution.
1813

19-
Run the coverage command after your cifuzz run:
14+
## Coverage
2015

2116
```bash
2217
cifuzz coverage com.example.FuzzTestCase::myFuzzTest
Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# cifuzz Gradle example
1+
## Project Description
22

3-
This is a simple Maven based project with both JUnit 4 and JUnit 5 unit tests
4-
and a fuzz test.
5-
It should quickly produce a finding, but slow enough to
6-
see the progress of the fuzzer.
3+
This is a simple Maven Java project configured with **cifuzz** and includes
4+
one Fuzz Test and one JUnit 4 as well as one JUnit 5 Unit Test, demonstrating
5+
the use of the `junit-vintage-engine`.
76

8-
You can start fuzzing with
7+
## Run
98

109
```bash
1110
cifuzz run com.example.ExploreFuzzTest::myFuzzTest
1211
```
12+
13+
The Fuzz Test should trigger a Remote Code Execution.
Lines changed: 4 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,16 @@
1-
# cifuzz Maven example
1+
## Project Description
22

3-
This is a simple Maven based project, already configured with
4-
**cifuzz**. It should quickly produce a finding, but slow enough to
5-
see the progress of the fuzzer.
3+
This is a simple Maven Java project configured with **cifuzz** which includes
4+
one Fuzz Test.
65

7-
To start make sure you installed **cifuzz** according to the
8-
main [README](../../../README.md) and added your CI repository credentials
9-
to Maven in `~/.m2/settings.xml`.
10-
11-
You can start fuzzing with
6+
## Run
127

138
```bash
149
cifuzz run com.example.FuzzTestCase::myFuzzTest
1510
```
1611

1712
## Coverage
1813

19-
cifuzz can generate Java coverage reports using
20-
[jacoco](https://www.jacoco.org). This example is configured to use both HTML
21-
and XML (e.g. for IDE support) as output formats.
22-
23-
Run the coverage command after your cifuzz run:
24-
2514
```bash
2615
cifuzz coverage com.example.FuzzTestCase::myFuzzTest
2716
```

example-projects/simple-setup/nodejs-typescript/README.md

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,23 @@
1-
# cifuzz nodejs typescript example
1+
## Project Description
22

3-
This is a simple nodejs/npm based typescript project, already configured with
4-
**cifuzz**. It should quickly produce a finding, but slow enough to
5-
see the progress of the fuzzer.
3+
This is a simple NodeJS Typescript project configured with **cifuzz** and
4+
includes one Fuzz Test.
65

7-
To start make sure you installed **cifuzz** according to the
8-
main [README](../../../README.md) and added your CI repository credentials
9-
to NPM, e.g. in ~/.npmrc.
6+
## Setup
107

118
```
12-
//gitlab.code-intelligence.com/api/v4/projects/89/packages/npm/:_authToken="<YOUR_TOKEN>"
9+
npm install
1310
```
1411

15-
After you ran `npm install`, you can start fuzzing with
12+
## Run
1613

1714
```bash
1815
cifuzz run FuzzTestCase
1916
```
2017

21-
## Coverage
18+
The Fuzz Test should trigger a Crash.
2219

23-
cifuzz can generate HTML coverage reports by running:
20+
## Coverage
2421

2522
```bash
2623
cifuzz coverage FuzzTestCase

0 commit comments

Comments
 (0)