Post Release Documentation Changes

leeN · tmbrbr · commit 10b651165017 · 2024-02-20T13:03:15.000+01:00
Some fixes to the documentation for the public version of Fontus,
including:

- Spelling &amp; Grammar
- Changed internal URLs to GitHub ones
diff --git a/README.md b/README.md
@@ -10,32 +10,23 @@ Dynamic tainting framework for Java applications leveraging on-the-fly bytecode
 This framework was developed as part of a research project to test and prevent security and privacy issues in web applications.
 
 ### Cite Us!
-The study was published at [ACM CCS 2023](https://www.sigsac.org/ccs/CCS2023/program.html), and the paper can be found [here](https://loxo.ias.cs.tu-bs.de/papers/2023_CCS_GDPR_tainting.pdf).
+The study was published at [ACM CCS 2023](https://www.sigsac.org/ccs/CCS2023/), and the paper can be found [here](https://www.ias.cs.tu-bs.de/publications/gdpr_tainting.pdf).
 You can cite our paper using the following bibtex entry:
 
 ```
-@inproceedings{10.1145/3576915.3616604,
-author = {Klein, David and Rolle, Benny and Barber, Thomas and Karl, Manuel and Johns, Martin},
-title = {General Data Protection Runtime: Enforcing Transparent GDPR Compliance for Existing Applications},
-year = {2023},
-isbn = {9798400700507},
-publisher = {Association for Computing Machinery},
-address = {New York, NY, USA},
-url = {https://doi.org/10.1145/3576915.3616604},
-doi = {10.1145/3576915.3616604},
-booktitle = {Proceedings of the 2023 ACM SIGSAC Conference on Computer and Communications Security},
-pages = {3343–3357},
-numpages = {15},
-keywords = {data protection, gdpr enforcement, privacy, taint-tracking},
-location = {, Copenhagen, Denmark, },
-series = {CCS '23}
+@inproceedings{KleRolBarKar+23,
+  title = {{General Data Protection Runtime: Enforcing Transparent GDPR Compliance for Existing Applications}},
+  author = {David Klein AND Benny Rolle AND Thomas Barber AND Manuel Karl AND Martin Johns},
+  booktitle = {Proc. of the ACM Conference on Computer and Communications Security (CCS)},
+  year = {2023},
+  doi = {10.1145/3576915.3616604},
 }
 ```
 
 
 ## Requirements and Setup
 
-For building the framework execute the gradle task ``shadowJar`` or ``publishToMavenLocal``. Afterwards you will find the Framework JAR in ``./fontus/build/libs``
+For building the framework execute the gradle task ``shadowJar`` or ``publishToMavenLocal``. Afterwards, you will find the Framework JAR in ``./fontus/build/libs``
 
 ## Building additional tools
 
@@ -85,14 +76,14 @@ It is also possible to pass multiple parameters to the agent
 - **config**: Specifies a path for a config file
 - **blacklisted_main_classes**: Specifies a filepath to a file which contains blacklisted main classes
 - **abort**: Specifies what happens if a tainted string reaches a sink. For all options see [Abort types](#Abort types). The default is *stderr_logging*
-- **taintloss_handler**: Specifies what happens if a method is called which potentially causes taintloss (e.g. String.toCharArray()). For all options see [Taintloss handler types](#Taintloss handler types). By default no taintloss handler is used 
+- **taintloss_handler**: Specifies what happens if a method is called which potentially causes taintloss (e.g. String.toCharArray()). For all options see [Taintloss handler types](#Taintloss handler types). By default, no taintloss handler is used 
 
-The arguments are appended to the agent path like this: ``-javaagent:jarpath[=options]``. Therefore options are defined as ``key=value`` pair and ``,`` is used as delimiter between key-value-pairs.
+The arguments are appended to the agent path like this: ``-javaagent:jarpath[=options]``. Therefore, options are defined as ``key=value`` pair and ``,`` is used as delimiter between key-value-pairs.
 
 An example for parameters passed to the agent ``-javaagent:"fontus-0.0.1-SNAPSHOT.jar=taintmethod=range,use_caching=false,verbose"``.
 
 ## Available Tainting Methods
-Currently there are 5 different tainting mechanisms available:
+Currently, there are 5 different tainting mechanisms available:
 - **boolean**: Only tainting per string. Differentiation which character is tainted is *not* possible. Very fast, little memory overhead, but more false positives
 - **array**: Naive tainting per character. Differentiation which character is tainted *is* possible. Linear overhead regarding length for CPU and memory (slow and expensive), nearly no false positives.
 - **range**: Optimized tainting per character. Differentiation which character is tainted *is* possible. Linear overhead regarding count of taints per string for CPU and memory (most times a lot more efficient than *array*). As precise as *array*.
@@ -101,16 +92,16 @@ Currently there are 5 different tainting mechanisms available:
 - **untainted**: An wrapper class is used to redirect all calls to the original classes. No taint calculation is performed! The taint is always "false"
 
 ## Abort types
-Currently there are four possibilities what can happen, if a tainted string reaches a sink:
+Currently, there are four possibilities what can happen, if a tainted string reaches a sink:
 
 - **exit**: Exits the application through System.exit(int). Beforehand the string is printed to stderr
 - **nothing**: Nothing happens if a tainted string reaches a sink
-- **stderr_logging**: Logs the tainted string to stderr as well as an stacktrace
+- **stderr_logging**: Logs the tainted string to stderr as well as a stacktrace
 - **json_logging**: Logs the tainted string to a JSON file in ``./fontus-results.json``
 
 ## Taintloss handler types
 - **stderr_logging**: Logs to stderr if a potentially taintlossy method is called
-- **file_logging**: Logs to file``./taintloss.log`` formatted in the same way we stderr_logging
+- **file_logging**: Logs to file``./taintloss.log`` formatted in the same way as stderr_logging
 - **statistics_logging**: Logs to the statistics MXBean in the format "Caller.method -> Taintloss.method: Hits"
 
 ## Inspect Bytecode of a class
@@ -119,7 +110,7 @@ To see the Bytecode for a class file, run ``javap -l -v -p -s TestString.class``
 
 ## Troubleshoot
 
-Have a look in the [docs folder](./docs)!
+Have a look in the [docs](./docs) folder, if anything is still unclear please open an issue.
 
 ## Support, Feedback, Contributing
 
diff --git a/docs/Getting_Started.md b/docs/Getting_Started.md
@@ -2,7 +2,7 @@
 
 ## General Remarks
 
-If you have an issue with the documentation or there is a mistake, feel free to fix it or open [an issue](https://git.ias.cs.tu-bs.de/GDPR_Tainting/Fontus/issues) (tagged with documentation please)!
+If you have an issue with the documentation or there is a mistake, feel free to fix it or open [an issue](https://github.com/SAP/project-fontus/issues) (tagged with documentation please)!
 
 ## Preliminary Steps
 
@@ -17,7 +17,7 @@ We publish to Maven local as it simplifies the following steps.
 
 0. Ensure the application runs regularly.
 
-If there are issues in the first place, Fontus will be of little help to fix them ;) It will only get more annoying..
+If there are issues in the first place, Fontus will be of little help to fix them ;) It will only get more annoying...
 
 1. Prepare your configuration
 
@@ -39,15 +39,15 @@ I use the following shell script:
 #!/bin/bash
 
 APPNAME="$(pwd)/target/app.jar"
-FONTUS_PATH="$HOME/.m2/repository/com/sap/fontus/fontus/0.0.1-SNAPSHOT/fontus-0.0.1-SNAPSHOT.jar"
+FONTUS_PATH="$HOME/.m2/repository/com/sap/fontus/fontus/0.0.1-SNAPSHOT/fontus-1.0.0-SNAPSHOT.jar"
 CONFIG_PATH="$(pwd)/configuration.xml"
 
 ./mvnw clean package  -DskipTests
 java -jar --add-opens java.base/jdk.internal.misc=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/jdk.internal.vm.annotation=ALL-UNNAMED \
   -javaagent:"${FONTUS_PATH}=config=${CONFIG_PATH},abort=stderr_logging" "${APPNAME}"
 ```
 
-If you are really lucky, it just works..
+If you are really lucky, it just works...
 
 To add taint persistence, proceed to the [taint persistence](Taint_persistence.md) documentation.
 
@@ -77,18 +77,18 @@ I have aliased `javapp` to `javap -l -v -p -s` as that's (in my opinion, YMMV!)
 To attach a debugger add the following to the run script:
 
 ```sh
--agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 \
+-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005
 ```
 
 The JVM will now suspend execution and wait for a remote debugger to be attached on port 5005 before running the application.
 
-Please be aware that your favorite IDE will probably show you the application's source code, which is not what the JVM executes! Fontus adds/changes methods so you have to be aware on how the instrumentation actually changes the code underneath.
+Please be aware that your favorite IDE will probably show you the application's source code, which is not what the JVM executes! Fontus adds/changes methods, so you have to be aware on how the instrumentation actually changes the code underneath.
 
-Example: IntelliJ allows for conditional break points and to evaluate expressions in the debugger. Assume you want to conditionally trigger a breakpoint if a string variable's (called `v`) value is equal to say `"java.lang.String"`. The straightforward approach (`v.equals("java.lang.String")` will always be false. Fontus has changed `v`to be of the type `IASString` and thus it can't be equal to a regular String literal. Instead you have to look for a method taking a `CharSequence` for the comparison to work. So the condition `v.conentEquals("java.lang.String")` should work.
+Example: IntelliJ allows for conditional break points and to evaluate expressions in the debugger. Assume you want to conditionally trigger a breakpoint if a string variable's (called `v`) value is equal to say `"java.lang.String"`. The straightforward approach (`v.equals("java.lang.String")` will always be false. Fontus has changed `v`to be of the type `IASString` and thus it can't be equal to a regular String literal. Instead, you have to look for a method taking a `CharSequence` for the comparison to work. So the condition `v.conentEquals("java.lang.String")` should work.
 
 7. I'm still stuck!
 
-Open a [Git Issue](https://git.ias.cs.tu-bs.de/GDPR_Tainting/Fontus/issues). The more detailed the input, the more likely we can help you. Important is a workable way to reproduce the bug on one of our machines!
+Open a [Git Issue](https://github.com/SAP/project-fontus/issues). The more detailed the input, the more likely we can help you. Important is a workable way to reproduce the bug on one of our machines!
 
 ## Debugging Tips
 
diff --git a/docs/Taint_persistence.md b/docs/Taint_persistence.md
@@ -8,7 +8,7 @@ Adjust the configuration accordingly! In theory other DBMS are also supported, b
 
 2. Dump the Database
 
-With something like `mysqldump -u $USER -p "$DBNAME" >> "$DBNAME.sql"` you can dump the database to a SQL file. Before continuing ensure the dump contains both the creation of the schema (all DDL required to setup the tables) as well as the data (a bunch of insert statements).
+With something like `mysqldump -u $USER -p "$DBNAME" >> "$DBNAME.sql"` you can dump the database to a SQL file. Before continuing: Ensure the dump contains both the schema (all DDL required to set up the tables), as well as the data (a bunch of insert statements).
 
 To do this with a running docker container, you can run:
 ```
@@ -23,23 +23,23 @@ If this worked without errors (haha), go to step 5.
 
 4. There were a bunch of errors...
 
-Sadly this is somewhat expected too. The used parser does not understand every bit of weird SQL Syntax and does not support some normal statements either.. So try fixing up the `dump.sql` file before running the tainter again.
+Sadly this is somewhat expected too. The used parser does not understand every bit of weird SQL Syntax and does not support some normal statements either. So try fixing up the `dump.sql` file before running the tainter again.
 
 Some things I noticed:
 
 - `LOCK <FOO>` and `UNLOCK <FOO>` cause the tainter to crash. As you surely are not importing the dump while using the DB, just remove those statements.
 - Some DB specific index syntax. Remove and add back manually.
 
-Those are all crashes in the frontend (the SQL Parser). Sadly we can't do much here without rewriting it to work with a different/better parser. If you have suggestions on a better library or how to fix JSQLParser (The grammar is insane) this, please get in touch!
+Those are all crashes in the frontend (the SQL Parser). Sadly we can't do much here without rewriting it to work with a different/better parser. If you have suggestions on a better library or how to fix JSQLParser (The grammar is insane), please get in touch!
 
 5. Reimport the tainted SQL
 
 Restore the dump via something like ``mysql -u $USER -p "$DBNAME" < "tainted_$DBNAME.sql"``
 
 If this fails, there are two options:
 
-- You missed something in step 4 and thus there are missing statements, e.g., you try to insert something into a table where the create statement is missing. Go directly back to to Step 4. Do not pass GO, do not collect 200 bucks.
-- The Tainter mangled something badly, please open [an issue](https://git.ias.cs.tu-bs.de/GDPR_Tainting/Fontus/issues?labels=123)
+- You missed something in step 4 and thus there are missing statements, e.g., you try to insert something into a table which does not exist (i.e., missing `CREATE` statement). Go back to Step 4 and repeat.
+- The Tainter mangled something badly, please check the open [issues](https://github.com/SAP/project-fontus/issues) and if this case is new: Please open an issue, we will look into it.
 
 6. Adjust the application to use taint persistence
 
@@ -98,7 +98,7 @@ Example for fixing a spring boot application using spring data-jpa:
 </dependency>
 ```
 
-Additionally please add the following to your `application.properties`:
+Additionally, please add the following to your `application.properties`:
 ```ini
 spring.datasource.tomcat.use-statement-facade=false
 ```
@@ -114,5 +114,5 @@ The taint driver has a weird issue with empty taint fields. I actually have no i
 
 9. It works but there are exceptions inside the taint driver
 
-Please check that the columns don't have empty values (see Step 8.). If that is not the case, please open [an issue](https://git.ias.cs.tu-bs.de/GDPR_Tainting/Fontus/issues?labels=123) with a minimal working example for us to reproduce. Just based on a stack trace it is impossible to fix.
+Please check that the columns don't have empty values (see Step 8.). If that is not the case, please open [an issue](https://github.com/SAP/project-fontus/issues) with a minimal working example for us to reproduce. Just based on a stack trace it is impossible to fix.
 
diff --git a/docs/integrating.md b/docs/integrating.md
@@ -31,8 +31,7 @@ RUN wget https://repo1.maven.org/maven2/org/jacoco/jacoco/0.8.8/jacoco-0.8.8.zip
 RUN unzip jacoco-0.8.8.zip
 
 ```
-Ensure to 'reset' the working directory to not change where fontus logs
-classfiles.
+Ensure to 'reset' the working directory to not change where fontus logs class files.
 
 2. Add JaCoCo agent to your JVM invocation.
 
@@ -50,7 +49,7 @@ ports:
 ```
 
 Ensure to start Fontus with the `verbose` option and make the resulting
-classfiles accessible for the report later on.
+class files accessible for the report later on.
 
 #### Getting Coverage Statistics
 
@@ -68,9 +67,9 @@ java -jar jacococli.jar dump --destfile=jacoco.exec
 ```
 3. Generate the report
 
-To generate the report JaCoCo needs read access to the classfiles, so adjust their permissions accordingly.
+To generate the report JaCoCo needs read access to the class files, so adjust their permissions accordingly.
 
-Assume the classfiles are located in `temp/agent`, you can generate an HTML report in the folder `cov_report` as follows:
+Assume the class files are located in `temp/agent`, you can generate an HTML report in the folder `cov_report` as follows:
 ```bash
 java -jar jacococli.jar report jacoco.exec --classfiles temp/agent/ --html cov_report
 ```
