Skip to content

CryptoGuardOSS/cryptoguard

Repository files navigation

layout
default

CryptoGuard $CVER 04.05.03$

badge Docker Badge Version Badge GitHub Release Downloads

Java Vulnerabilities (by Snyk.io): CryptoGuard Vulnerabilities Python3 Vulnerabilities (by Snyk.io): Python Vulnerabilities

A program analysis tool to find cryptographic misuse in Java and Android.

CryptoSouple.py

This python file is the wrapper created to assist with various portions of the project. You should use it for various commands including:

  • setting the environment
  • clean the project
  • building the project
  • running tests
  • building a simple command

This is a website hosting a Docker image that actively runs either Java or Python3 samples. The Java Notebook is only possible by utilitzing IJava. This is still under progress as the following are not active yet:

  • Android SDK tests
  • Sample Java Tests

Please run the following command to get more information on how to use it ./cryptosouple.py.

IMPORTANT NOTICE

  • Due to 'leaky tests' from the environment and persistent variables, a python test runner was made
  • Please run make tests
    • this ensures isolated environments via gradle calls

Building From Source

  • Run make, this will build CryptoGuard and move the jar to the current directory
  • Run scans to scan all of the tests included in the source
    • There is currently a sample project for each scan type within src/test
  • Run clean to clean the entire project

Prerequisites (Environment Variables)

  1. JAVA_HOME: Point to a valid Java 8 JDK Installation

    • Needed for all of the scans
  2. JAVA7_HOME: Point to a valid Java 7 JDK Installation

    • Needed for project scans and java file scans
  3. ANDROID_SDK_HOME: Point to a valid Android JDK Installation

    • Needed for Android

Note

  • Run make env to verify (and set) all of these variables by following the instructions.

Different Scanning Options

Source (Maven or Gradle Project Directory only)

  • raw command (without dependencies) java -jar cryptoguard.jar -in source -s /rootPath
  • raw command (with dependencies) java -jar cryptoguard.jar -in source -s /rootPath -d /dependencies
Note

If the project have external dependencies then first gather the dependencies under a folder that is relative to the project root (e.g., "build/dependencies").

If you have multiple subprojects with external dependencies, then you have to gather all the corresponding subproject dependencies under a path that is relative to each of the subprojects.

JAR Files

  • raw command java -jar cryptoguard.jar -in jar -s /path/to/jar/my-jar.jar

APK Files

  • raw command java -jar cryptoguard.jar -in apk -s /path/to/apk/my-apk.apk

Java Files (Currently Unstable, currently limited to Java JDK 8 by library constraint)

  • raw command java -jar cryptoguard.jar -in java -s /path/to/java/file.java
  • raw command (for files) java -jar cryptoguard.jar -in java -s /path/to/java/file1.java /path/to/java/file2.java

Java Class Files (Currently limited to Java JDK 8)

  • raw command java -jar cryptoguard.jar -in class -s /path/to/java/file.class
  • raw command (for files) java -jar cryptoguard.jar -in java -s /path/to/java/file1.class /path/to/java/file2.class

Different Scanning Options

Source/Dependencies options

  • By default, both source and dependencies are expecting a list of files
    • or for source the .in file
  • The source and dependencies can also handle a class path based string
    • ex: -s ~/tester/PBEUsage.class:~/tester/UrlFrameWorks.class:~/tester/NewTestCase1.class:~/tester/NewTestCase2.class

Output options

  • using the argument -m, you can add the identifier of the other output formats
Default
  • Argument -m D

    • example command java -jar cryptoguard.jar -in jar -s /path/to/jar/my-jar.jar -m D
  • This is a json file that represents a more simplified output

    • This will be iterated over time as more functionality is available
Legacy
  • Argument -m L
    • example command java -jar cryptoguard.jar -in jar -s /path/to/jar/my-jar.jar -m L
  • This will output a txt file used within early CryptoGuard versions
Scarf XML
  • Argument -m SX

    • example command java -jar cryptoguard.jar -in jar -s /path/to/jar/my-jar.jar -m SX
  • This will ouput an xml file using the scarf_v1.2.xsd used by SWAMP.

  • By using the argument -Sconfig properties.file, this will load the properties from within the file

    • example command java -jar cryptoguard.jar -in jar -s /path/to/jar/my-jar.jar -m SX -Sconfig properties.file

Input a single file (list of files)

  • Argument -s *.in
  • By using this argument (and you have to use the .in extension) input a single file containing all of the source input files
  • example
    • command to generate a file like this find -type f -name \*.java \>\> input.in
      • generated input.in file
./samples/testable-jar/src/main/java/tester/UrlFrameWorks.java
./samples/testable-jar/src/main/java/tester/PasswordUtils.java
./samples/testable-jar/src/main/java/tester/Crypto.java
./samples/testable-jar/src/main/java/tester/PBEUsage.java
./samples/testable-jar/src/main/java/tester/NewTestCase2.java
./samples/testable-jar/src/main/java/tester/VeryBusyClass.java
./samples/testable-jar/src/main/java/tester/SymCrypto.java
./samples/testable-jar/src/main/java/tester/NewTestCase1.java
./samples/testable-jar/src/main/java/tester/LiveVarsClass.java
./samples/testable-jar/src/main/java/tester/PassEncryptor.java}
  • command to be used with cryptoguard java -jar -s input.in

    • this is similar to java -jar -s ./samples/testable-jar/src/main/java/tester/UrlFrameWorks.java ... ./samples/testable-jar/src/main/java/tester/PassEncryptor.java
  • NOTE: This can be used with any type of input/output marshalling

Help

  • If you have any questions or suggestions, please email to sazzad114@gmail.com.
  • Please also run make help or java -jar cryptoguard.jar -h for argument help.
  • You can also look at the auto-generated USAGE.md file.

FAQ

  • There may be silent failures if any of the environment variables below are not set.
    • This can be checked by running make env

Website

  • The generated website uses a slightly modified Jekyll Hyde template under the MIT License.
  • Technology Reports
    • Gradle Junit Test Reports are generated from Gradle
    • Cobertura Test Coverage Reports are generated from Cobertura
    • Java Documentation are generated from Java

Disclaimer

CryptoGuard is a research prototype under GNU General Public License 3.0

Copyright © 2020 CryptoGuard

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 3.0 for more details.

You should have received a copy of the GNU General Public License 3.0 along with this program. If not, see https://www.gnu.org/licenses/gpl-3.0.html.

Reference

If you find this project useful, please cite our CCS'19 CryptoGuard paper and the thesis supporting the latest enhancements from within this fork.

@phdthesis{frantz2020enhancing,
	title={Enhancing CryptoGuard's Deployability for Continuous Software Security Scanning},
	author={Frantz, Miles},
	year={2020},
	school={Virginia Tech}
}