Merge branch 'main' of https://github.com/Contrast-Security-OSS/safelog4j

Author: planetlevel

README.md

@@ -1,11 +1,17 @@
 # safelog4j
 
-If you're wrestling with log4shell [CVE-2021-45046](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-45046), the best thing to do is to upgrade your log4j to the latest secure version.
-
-But if you can't do that for whatever reason, you probably want to be *really* sure that you have a problem and an easy way to fix it.
-
-Safelog4j is an instrumentation-based tool to help you discover, verify, and solve log4shell without scanning or upgrading.
-
+<p align="center"><b>
+<br>
+<br>
+Safelog4j is an instrumentation-based security tool to help teams<br>
+discover, verify, and solve log4shell without scanning or upgrading
+<br>
+<br>
+</b></p>
+
+If you're wrestling with log4shell [CVE-2021-45046](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-45046), the best thing to do is to upgrade your log4j to the latest secure version.  But if you can't do that for whatever reason, you probably want to be *really* sure that you have a problem and an easy way to fix it.
+
+Safelog4j:
 * accurately discovers the use of log4j
 * verifies that the log4shell vulnerability is actually present and exploitable
 * prevents the log4shell vulnerability from being exploited
@@ -15,15 +21,21 @@ Safelog4j doesn't rely on version numbers or filenames. Instead, it instruments
 ![safelog4j-screenshot](https://github.com/Contrast-Security-OSS/safelog4j/blob/main/resources/safelog4j-screenshot.png?raw=true)
 
 
-## Why should you use this
+## Why should you use an instrumentation-based approach to log4shell (and other security challenges)
+
+Instrumentation has been around for decades, is widely used in performance tools, debugging and profiling, and app frameworks. Many security tools scan from the 'outside-in' and don't have the full context of the running application.  This leads to false-positives, false-negatives, and long scan times.
+
+Instrumentation allows us to do security analysis from within the running application - by watching the code run.  Directly measuring security has speed, coverage, and accuracy benefits.  Using instrumentation to analyze for vulnerabilities is often called IAST (Interactive Application Security Testing). Using instrumentation to identify attacks and prevent exploit is often called RASP (Runtime Application Self-Protection).
 
-Unfortunately, log4j is deployed in a huge variety of ways that make traditional detection very difficult. Scanning file systems, code repos, or containers is very likely to fail to detect log4j accurately. Determining exploitability by attempting to test, scan, or fuzz for log4shell is even more inaccurate, requiring exactly right input with the exactly right syntax.
+Safelog4j provides both IAST and RASP capabilities focused on a single vulnerability: log4shell. IAST verifies that the vulnerability is present and actually exploitable.  RASP prevents it from being exploited.  IAST and RASP can be used for a broad range of vulnerabilities and attacks.  Please reach out if you're interested in applying these techniques to new security chaallenges.
+
+Remember, you may be getting false results from other approaches. Scanning file systems, code repos, or containers could easily fail to detect log4j accurately. Determining exploitability by attempting to test, scan, or fuzz for log4shell is even more inaccurate, requiring exactly right input with the exactly right syntax.
 
 * log4j could be buried in a fat jar, war, or ear
 * log4j could be shaded in another jar
 * log4j could be included in the appserver, not the code repo
 * log4j could be part of dynamically loaded code or plugin
-* log4j could have multiple different versions with different classloaders, some vulnerable some not
+* log4j could be many different versions with different classloaders in a single app
 * log4j could be masked by use of slf4j or other layers
 * log4j could be renamed, recompiled, or otherwise changed
 
@@ -32,7 +44,7 @@ Unfortunately, log4j is deployed in a huge variety of ways that make traditional
 
 You can use safelog4j in just about any environment using Java.
 
-1. Download the latest [safelog4j-1.0.3.jar](https://github.com/Contrast-Security-OSS/safelog4j/releases/download/v1.0.1/safelog4j-1.0.1.jar)
+1. Download the latest [safelog4j-1.0.3.jar](https://github.com/Contrast-Security-OSS/safelog4j/releases/download/v1.0.1/safelog4j-1.0.3.jar)
 
 You can run it wherever you launch a JVM...
 
@@ -57,13 +69,24 @@ Or you can attach to a JVM that is already running...
 
 ## Safelog4j Options
 
-* CHECK means that safelog4j will actually test every log4j instance for log4shell. This is done by generating a synthetic log message and a sensor to detect it in the vulnerable clsas. This is iron clad evidence the application is vulnerable -- provided unttrusted data reaches that logger.
+* **CHECK** means that safelog4j will actually test every log4j instance for log4shell. This is done by generating a synthetic log message and a sensor to detect it in the vulnerable clsas. This is iron clad evidence the application is vulnerable -- provided unttrusted data reaches that logger.
+
+* **BLOCK** means that safelog4j will stub out all the methods in the JNDI lookup class.  This is the recommended approach to ensure that log4j can't be exploited. It is harmless, except for the total prevention of this attack.
+
+* **BOTH** simply means that both CHECK and BLOCK will occur.
+
+* **NONE** disables both CHECK and BLOCK, allowing you to keep the agent in place but completely disabled.
+
 
-* BLOCK means that safelog4j will stub out all the methods in the JNDI lookup class.  This is the recommended approach to ensure that log4j can't be exploited. It is harmless, except for the total prevention of this attack.
+## Building and Contributing
 
-* BOTH simply means that both CHECK and BLOCK will occur.
+We welcome pull requests and issues. Thanks!
 
-* NONE disables both CHECK and BLOCK, allowing you to keep the agent in place but disabled.
+>
+> $ git clone 
+> $ mvn clean install
+> $ java -jar target/safelog4j-x.x.x.jar
+> 
 
 
 ## License