Avis de dépréciation : Hawkeye a atteint sa fin de vie.

Il existe des options plus modernes pour vous et votre projet. Si vous souhaitez reprendre la maintenance du projet, n'hésitez pas à me contacter. Vous trouverez les moyens de me joindre sur ma page personnelle.

.

.

.

.

.

.

Le scanner-cli Hawkeye est un outil de mise en évidence des risques de sécurité, de vulnérabilité et de risques généraux d’un projet. Il est destiné à être intégré dans vos hooks pre-commit et vos pipelines.

Exécution et configuration du scanner

Le scanner-cli Hawkeye suppose que la structure de votre répertoire est telle que les fichiers de la chaîne d'outils se trouvent au niveau supérieur. En gros, voici ce à quoi cela se résume :

• Les projets Node.js ont un package.json au niveau supérieur
• Les projets Ruby auront un Gemfile au niveau supérieur
• Les projets Python auront un requirements.txt au niveau supérieur
• Les projets PHP auront un composer.lock au niveau supérieur
• Les projets Java auront un dossier build (gradle) ou target (maven), et incluront des fichiers .java et .jar
• Les projets Kotlin auront un dossier build (gradle) ou target (maven), et incluront des fichiers .kt et .jar
• Les projets Scala auront un dossier target (sbt avec les plugins sbt-native-packager ou sbt-assembly), et incluront des fichiers .scala et .jar. Consultez ce dépôt pour une démo fonctionnelle.
• Les projets Rust auront un Cargo.toml au niveau supérieur

Cette liste n'est pas exhaustive car parfois les outils nécessitent d'autres fichiers. Pour comprendre comment les modules décident s'ils peuvent traiter un projet, veuillez consulter la section Comment ça marche et le dossier modules.

Docker (recommandé)

L'image Docker est de loin le moyen le plus simple d'utiliser le scanner. Veuillez noter que votre racine de projet (par exemple $PWD) doit être montée dans /target.

docker run --rm -v $PWD:/target hawkeyesec/scanner-cli:latest

Si vous utilisez le scanner pour écrire un JSON (via les drapeaux CLI -j et --json et le paramètre json dans .hawkeyerc), assurez-vous d'utiliser les UID et GID corrects via docker run -u $(id -u):$(id -g). Sinon, cela pourrait vous laisser avec des fichiers impossibles à supprimer, par exemple lors de l'exécution dans Jenkins.

La construction Docker est également le moyen recommandé d'exécuter le scanner dans vos pipelines CI. Voici un exemple d'exécution de Hawkeye sur l'un de vos projets dans GoCD :

<pipeline name="security-scan">
  <stage name="Hawkeye" cleanWorkingDir="true">
    <jobs>
      <job name="scan">
        <tasks>
          <exec command="docker">
            <arg>pull</arg>
            <arg>hawkeyesec/scanner-cli</arg>
            <runif status="passed" />
          </exec>
          <exec command="bash">
            <arg>-c</arg>
            <arg>docker run --rm -v $PWD:/target hawkeyesec/scanner-cli:latest</arg>
            <runif status="passed" />
          </exec>
        </tasks>
      </job>
    </jobs>
  </stage>
</pipeline>

npm

Vous pouvez installer et exécuter hawkeye dans un projet Node.js via

npm install --save-dev @hawkeyesec/scanner-cli
npx hawkeye scan

Cette méthode est recommandée dans un projet Node.js, lorsque les autres chaînes d'outils (par exemple python, ruby) ne sont pas nécessaires.

Avec cette méthode, il est également recommandé d'invoquer le scanner dans un hook pre-commit git (par exemple via le package pre-commit) pour faire échouer le commit si des problèmes sont trouvés.

Fichiers de configuration (recommandé)

Vous pouvez configurer le scanner via les fichiers .hawkeyerc et .hawkeyeignore à la racine de votre projet.

Le fichier .hawkeyerc est un fichier JSON qui vous permet de configurer ...

• les modules à exécuter,
• les rédacteurs (writers) à utiliser, et
• le seuil d'échec

{
    "all": true|false,
    "staged": true|false,
    "modules": ["files-ccnumber", "java-owasp", "java-find-secbugs"],
    "sumo": "http://your.sumologic.foobar/collector",
    "http": "http://your.logger.foobar/collector",
    "json": "log/results.json",
    "failOn": "low"|"medium"|"high"|"critical",
    "showCode": true|false
}

Le fichier .hawkeyeignore est une collection d'expressions régulières correspondant à des chemins et des codes d'erreur de module à exclure de l'analyse, et équivaut à utiliser le drapeau --exclude. Les lignes commençant par # sont considérées comme des commentaires.

Veuillez noter que tous les caractères spéciaux réservés dans les expressions régulières (-[]{}()*+?.,^$|#\s) doivent être échappés lorsqu'ils sont utilisés comme littéraux !

Veuillez également noter que les codes d'erreur des modules ne sont généralement pas affichés, car ils ne sont pas principalement pertinents pour l'utilisateur. Si vous souhaitez exclure un certain faux positif, vous pouvez afficher les codes d'erreur des modules avec le drapeau --show-code ou la propriété showCode dans .hawkeyerc.

^test/

# ceci est un commentaire

^README.md

L'interface en ligne de commande (CLI)

Utilisez hawkeye modules pour lister les modules disponibles et leur état.

> npx hawkeye modules
[info] Version: v1.4.0
[info] Module Status
[info] Enabled:   files-ccnumber
[info]            Scans for suspicious file contents that are likely to contain credit card numbers
[info] Enabled:   files-contents
[info]            Scans for suspicious file contents that are likely to contain secrets
[info] Disabled:  files-entropy
[info]            Scans files for strings with high entropy that are likely to contain passwords
[info] Enabled:   files-secrets
[info]            Scans for suspicious filenames that are likely to contain secrets
[info] Enabled:   java-find-secbugs
[info]            Finds common security issues in Java code with findsecbugs
[info] Enabled:   java-owasp
[info]            Scans Java projects for gradle/maven dependencies with known vulnerabilities with the OWASP dependency checker
[info] Enabled:   node-npmaudit
[info]            Checks node projects for dependencies with known vulnerabilities
[info] Enabled:   node-npmoutdated
[info]            Checks node projects for outdated npm modules
[info] Enabled:   node-yarnaudit
[info]            Checks yarn projects for dependencies with known vulnerabilities
[info] Enabled:   node-yarnoutdated
[info]            Checks node projects for outdated yarn modules
[info] Enabled:   php-security-checker
[info]            Checks whether the composer.lock contains dependencies with known vulnerabilities using security-checker
[info] Enabled:   python-bandit
[info]            Scans for common security issues in Python code with bandit.
[info] Enabled:   python-piprot
[info]            Scans python dependencies for out of date packages
[info] Enabled:   python-safety
[info]            Checks python dependencies for known security vulnerabilities with the safety tool.
[info] Enabled:   ruby-brakeman
[info]            Statically analyzes Rails code for security issues with Brakeman.
[info] Enabled:   ruby-bundler-scan
[info]            Scan for Ruby gems with known vulnerabilities using bundler

Utilisez hawkeye scan pour lancer une analyse :

> npx hawkeye scan --help
[info] Version: v1.3.0
Usage: hawkeye-scan [options]

Options:
  -a, --all                                       Scan all files, regardless if a git repo is found. Defaults to tracked files in git repositories.
  -t, --target [/path/to/project]                 The location to scan. Defaults to $PWD.
  -f, --fail-on [low|medium|high|critical]        Set the level at which hawkeye returns non-zero status codes. Defaults to low.
  -m, --module [module name]                      Run specific module. Defaults to all applicable modules.
  -e, --exclude [pattern]                         Specify one or more exclusion patterns (eg. test/*). Can be specified multiple times.
  -j, --json [/path/to/file.json]                 Write findings to file.
  -s, --sumo [https://sumologic-http-connector]   Write findings to SumoLogic.
  -H, --http [https://your-site.com/api/results]  Write findings to a given url.
  --show-code                                     Shows the code the module uses for reporting, useful for ignoring certain false positives
  -g, --staged                                    Scan only git-staged files.
  -h, --help                                      output usage information

Résultats

Codes de sortie

Le scanner-cli répond avec les codes de sortie suivants :

• Le code de sortie 0 indique qu'aucun résultat n'a été trouvé au-dessus ou égal au seuil minimum.
• Le code de sortie 1 indique que des problèmes ont été trouvés au-dessus ou égal au seuil minimum.
• Le code de sortie 42 indique qu'une erreur inattendue s'est produite quelque part dans le programme. Il s'agit probablement d'un bogue et cela ne devrait pas arriver. Veuillez vérifier la sortie du journal et signaler un bogue.

Redirection de la sortie console

Si vous souhaitez rediriger la sortie du journal de la console, la méthode recommandée est de se connecter à stdout. Dans cet exemple, nous utilisons à la fois les résultats JSON et stdout :

docker run --rm -v $PWD:/target hawkeyesec/scanner-cli:latest -j hawkeye-results.json -f critical 2>&1 | tee hawkeye-results.txt

Sortie console

Par défaut, le scanner affiche ses résultats dans la console sous forme de tableau.

Sumologic

Les résultats peuvent être envoyés à un collecteur SumoLogic de votre choix. Dans cet exemple, nous avons un collecteur avec une seule source HTTP.

hawkeye scan --sumo https://collectors.us2.sumologic.com/receiver/v1/http/your-http-collector-url

Dans SumoLogic, recherchez _collector="hawkeye" | json auto :

N'importe quel point de terminaison HTTP

De manière similaire à l'exemple SumoLogic, le scanner peut envoyer les résultats à n'importe quel point de terminaison HTTP acceptant les messages POST.

hawkeye scan --http http://your.logging.foobar/endpoint

Les résultats seront envoyés avec User-Agent: hawkeye. Comme pour la sortie console, le JSON suivant sera POSTé pour chaque résultat :

{
  "module": "files-contents",
  "level": "critical",
  "offender": "testfile3.yml",
  "description": "Private key in file",
  "mitigation": "Check line number: 3"
}

Comment ça marche

Hawkeye est conçu pour être extensible en ajoutant des modules et des rédacteurs (writers).

• Ajoutez des modules dans le dossier modules.
• Ajoutez des rédacteurs dans le dossier writers.

Modules

Les modules sont essentiellement de petits morceaux de code qui implémentent leur propre logique, ou encapsulent un outil tiers et normalisent la sortie. Ils ne s'exécutent que si les critères requis sont remplis. Par exemple : le module npm outdated ne s'exécuterait que si un package.json est détecté dans la cible d'analyse - par conséquent, vous n'avez pas besoin de dire à Hawkeye quel type de projet vous analysez.

Modules génériques

• files-ccnumber : Analyse les contenus de fichiers suspects susceptibles de contenir des numéros de carte de crédit
• files-contents : Analyse les contenus de fichiers suspects susceptibles de contenir des secrets
• files-entropy : Analyse les fichiers à la recherche de chaînes à haute entropie susceptibles de contenir des mots de passe. L'analyse d'entropie est désactivée par défaut en raison du nombre élevé de faux positifs. Il est utile d'analyser les bases de code de temps en temps pour détecter les clés, auquel cas veuillez l'exécuter en utilisant le commutateur -m files-entropy.
• files-secrets : Analyse les noms de fichiers suspects susceptibles de contenir des secrets

Java / Kotlin / Scala

• java-find-secbugs : Trouve les problèmes de sécurité courants dans le code Java avec findsecbugs
• java-owasp : Analyse les projets Java pour les dépendances gradle/maven avec des vulnérabilités connues à l'aide du vérificateur de dépendances OWASP

Node.js

• node-npmaudit : Vérifie les projets Node pour les dépendances avec des vulnérabilités connues à l'aide de npm audit
• node-npmoutdated : Vérifie les projets Node pour les modules npm obsolètes à l'aide de npm outdated
• node-yarnaudit : Vérifie les projets yarn pour les dépendances avec des vulnérabilités connues à l'aide de yarn audit
• node-yarnoutdated : Vérifie les projets Node pour les modules yarn obsolètes à l'aide de yarn outdated

PHP

• php-security-checker : Vérifie si composer.lock contient des dépendances avec des vulnérabilités connues à l'aide de security-checker

Python

• python-bandit : Analyse les problèmes de sécurité courants dans le code Python avec bandit.
• python-piprot : Analyse les dépendances Python pour les packages obsolètes avec piprot
• python-safety : Vérifie les dépendances Python pour les vulnérabilités de sécurité connues avec l'outil safety.

Ruby

• ruby-brakeman : Analyse statiquement le code Rails pour les problèmes de sécurité avec Brakeman.
• ruby-bundler-scan : Analyse les gems Ruby avec des vulnérabilités connues en utilisant bundler

Rust

• rust-cargoaudit : Vérifie si Cargo.lock contient des dépendances avec des vulnérabilités connues à l'aide de cargo audit

Ajout d'un module

Si vous avez une idée pour un module, n'hésitez pas à ouvrir une demande de fonctionnalité dans la section des issues. Si vous avez un peu de temps libre, veuillez envisager de nous envoyer une pull request. Pour voir comment les modules fonctionnent, rendez-vous dans le dossier modules pour découvrir comment les choses fonctionnent.