Avviso di Deprecazione: Hawkeye ha raggiunto la fine del suo ciclo di vita.

Ci sono opzioni più moderne disponibili per te e il tuo progetto. Se desideri riprendere la manutenzione del progetto, sentiti libero di contattarmi. Troverai i modi per contattarmi sulla mia homepage personale.

.

.

.

.

.

.

Hawkeye scanner-cli è uno strumento per evidenziare la sicurezza del progetto, le vulnerabilità e i rischi generali. È pensato per essere integrato nei tuoi pre-commit hook e nelle tue pipeline.

Esecuzione e configurazione dello scanner

Hawkeye scanner-cli presuppone che la struttura della directory sia tale da mantenere i file della toolchain al livello principale. In sintesi, ecco cosa si riduce a:

• I progetti Node.js hanno un package.json al livello principale
• I progetti Ruby avranno un Gemfile al livello principale
• I progetti Python avranno un requirements.txt al livello principale
• I progetti PHP avranno un composer.lock al livello principale
• I progetti Java avranno una cartella build (gradle) o target (maven) e includeranno file .java e .jar
• I progetti Kotlin avranno una cartella build (gradle) o target (maven) e includeranno file .kt e .jar
• I progetti Scala avranno una cartella target (sbt con plugin sbt-native-packager o sbt-assembly) e includeranno file .scala e .jar. Consulta questo repository per una demo in esecuzione.
• I progetti Rust avranno un Cargo.toml al livello principale

Questo non è esaustivo poiché a volte gli strumenti richiedono ulteriori file per esistere. Per capire come i moduli decidono se possono gestire un progetto, consulta la sezione Come funziona e la cartella moduli.

Docker (consigliato)

L'immagine docker è di gran lunga il modo più semplice per utilizzare lo scanner. Nota che la root del progetto (es. $PWD) deve essere montata su /target.

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

Se stai usando lo scanner per scrivere un JSON (tramite i flag CLI -j e --json e l'impostazione json nel file .hawkeyerc), assicurati che utilizzi l'UID e GID corretti tramite docker run -u $(id -u):$(id -g). Altrimenti potresti ritrovarti con file non cancellabili, ad esempio durante l'esecuzione in Jenkins.

La build docker è anche il modo consigliato per eseguire lo scanner nelle tue pipeline CI. Questo è un esempio di esecuzione di Hawkeye su uno dei tuoi progetti in 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

Puoi installare ed eseguire hawkeye in un progetto Node.js tramite

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

Questo metodo è consigliato in un progetto Node.js, dove non sono richieste altre toolchain (es. python, ruby).

Con questo metodo, si consiglia anche di invocare lo scanner in un git pre-commit hook (es. tramite il pacchetto pre-commit) per far fallire il commit se vengono trovati problemi.

File di Configurazione (consigliati)

Puoi configurare lo scanner tramite i file .hawkeyerc e .hawkeyeignore nella root del progetto.

Il file .hawkeyerc è un file JSON che ti permette di configurare ...

• i moduli da eseguire,
• i writer da utilizzare, e
• la soglia di fallimento

{
    "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
}

Il file .hawkeyeignore è una raccolta di espressioni regolari che corrispondono a percorsi e codici di errore dei moduli da escludere dalla scansione, ed è equivalente all'uso del flag --exclude. Le righe che iniziano con # sono considerate commenti.

Nota che qualsiasi carattere speciale riservato nelle espressioni regolari (-[]{}()*+?.,^$|#\s) deve essere escapato quando usato come letterale!

Nota anche che i codici di errore dei moduli di solito non vengono mostrati, poiché non sono principalmente rilevanti per l'utente. Se desideri escludere un determinato falso positivo, puoi visualizzare i codici di errore dei moduli con il flag --show-code o la proprietà showCode nel file .hawkeyerc.

^test/

# questo è un commento

^README.md

La CLI

Usa hawkeye modules per elencare i moduli disponibili e il loro stato.

> npx hawkeye modules
[info] Versione: v1.4.0
[info] Stato Moduli
[info] Abilitato:   files-ccnumber
[info]            Scansiona contenuti di file sospetti che probabilmente contengono numeri di carta di credito
[info] Abilitato:   files-contents
[info]            Scansiona contenuti di file sospetti che probabilmente contengono segreti
[info] Disabilitato:  files-entropy
[info]            Scansiona file per stringhe con alta entropia che probabilmente contengono password
[info] Abilitato:   files-secrets
[info]            Scansiona nomi di file sospetti che probabilmente contengono segreti
[info] Abilitato:   java-find-secbugs
[info]            Trova problemi di sicurezza comuni nel codice Java con findsecbugs
[info] Abilitato:   java-owasp
[info]            Scansiona progetti Java per dipendenze gradle/maven con vulnerabilità note utilizzando OWASP dependency checker
[info] Abilitato:   node-npmaudit
[info]            Verifica progetti node per dipendenze con vulnerabilità note
[info] Abilitato:   node-npmoutdated
[info]            Verifica progetti node per moduli npm obsoleti
[info] Abilitato:   node-yarnaudit
[info]            Verifica progetti yarn per dipendenze con vulnerabilità note
[info] Abilitato:   node-yarnoutdated
[info]            Verifica progetti node per moduli yarn obsoleti
[info] Abilitato:   php-security-checker
[info]            Verifica se composer.lock contiene dipendenze con vulnerabilità note utilizzando security-checker
[info] Abilitato:   python-bandit
[info]            Scansiona problemi di sicurezza comuni nel codice Python con bandit.
[info] Abilitato:   python-piprot
[info]            Scansiona dipendenze python per pacchetti obsoleti
[info] Abilitato:   python-safety
[info]            Verifica dipendenze python per vulnerabilità di sicurezza note con lo strumento safety.
[info] Abilitato:   ruby-brakeman
[info]            Analizza staticamente il codice Rails per problemi di sicurezza con Brakeman.
[info] Abilitato:   ruby-bundler-scan
[info]            Scansiona gemme Ruby con vulnerabilità note utilizzando bundler

Usa hawkeye scan per avviare una scansione:

> npx hawkeye scan --help
[info] Versione: v1.3.0
Utilizzo: hawkeye-scan [opzioni]

Opzioni:
  -a, --all                                       Scansiona tutti i file, indipendentemente dal fatto che sia presente un repository git. Il valore predefinito sono i file tracciati nei repository git.
  -t, --target [/path/to/project]                 La posizione da scansionare. Il valore predefinito è $PWD.
  -f, --fail-on [low|medium|high|critical]        Imposta il livello al quale hawkeye restituisce codici di stato non zero. Il valore predefinito è low.
  -m, --module [nome modulo]                      Esegui un modulo specifico. Il valore predefinito sono tutti i moduli applicabili.
  -e, --exclude [pattern]                         Specifica uno o più pattern di esclusione (es. test/*). Può essere specificato più volte.
  -j, --json [/path/to/file.json]                 Scrivi i risultati in un file.
  -s, --sumo [https://sumologic-http-connector]   Scrivi i risultati in SumoLogic.
  -H, --http [https://your-site.com/api/results]  Scrivi i risultati a un dato URL.
  --show-code                                     Mostra il codice che il modulo utilizza per i rapporti, utile per ignorare determinati falsi positivi
  -g, --staged                                    Scansiona solo i file staged di git.
  -h, --help                                      output delle informazioni di utilizzo

Risultati

Codici di Uscita

Il scanner-cli risponde con i seguenti codici di uscita:

• Il codice di uscita 0 indica che non sono stati trovati risultati al di sopra o uguali alla soglia minima.
• Il codice di uscita 1 indica che sono stati trovati problemi al di sopra o uguali alla soglia minima.
• Il codice di uscita 42 indica che si è verificato un errore imprevisto da qualche parte nel programma. Questo è probabilmente un bug e non dovrebbe accadere. Controlla l'output del log e segnala un bug.

Reindirizzamento dell'output della console

Se desideri reindirizzare l'output del logger della console, il metodo consigliato è agganciarsi a stdout. In questo esempio, stiamo utilizzando sia i risultati JSON che stdout:

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

Output della console

Per impostazione predefinita, lo scanner restituisce i risultati alla console in forma tabellare.

Sumologic

I risultati possono essere inviati a un collector SumoLogic di tua scelta. In questo esempio, abbiamo un collector con una singola sorgente HTTP.

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

In SumoLogic, cerca _collector="hawkeye" | json auto:

Qualsiasi endpoint HTTP

Analogamente all'esempio SumoLogic, lo scanner può inviare i risultati a qualsiasi endpoint HTTP che accetti messaggi POST.

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

I risultati verranno inviati con User-Agent: hawkeye. Analogamente all'output della console, il seguente JSON verrà POSTato per ogni risultato:

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

Come funziona

Hawkeye è progettato per essere estensibile aggiungendo moduli e writer.

• Aggiungi moduli nella cartella moduli.
• Aggiungi writer nella cartella writer.

Moduli

I moduli sono essenzialmente piccoli pezzi di codice che implementano la propria logica o avvolgono uno strumento di terze parti e standardizzano l'output. Vengono eseguiti solo se vengono soddisfatti i criteri richiesti. Ad esempio: il modulo npm outdated verrebbe eseguito solo se viene rilevato un package.json nella destinazione della scansione - di conseguenza, non è necessario dire a Hawkeye che tipo di progetto stai scansionando.

Moduli Generici

• files-ccnumber: Scansiona contenuti di file sospetti che probabilmente contengono numeri di carta di credito
• files-contents: Scansiona contenuti di file sospetti che probabilmente contengono segreti
• files-entropy: Scansiona file per stringhe con alta entropia che probabilmente contengono password. La scansione dell'entropia è disabilitata per impostazione predefinita a causa dell'elevato numero di falsi positivi. È utile scansionare i codebase di tanto in tanto per le chiavi, nel qual caso eseguilo utilizzando l'interruttore -m files-entropy.
• files-secrets: Scansiona nomi di file sospetti che probabilmente contengono segreti

Java / Kotlin / Scala

• java-find-secbugs: Trova problemi di sicurezza comuni nel codice Java con findsecbugs
• java-owasp: Scansiona progetti Java per dipendenze gradle/maven con vulnerabilità note utilizzando OWASP dependency checker

Node.js

• node-npmaudit: Verifica progetti node per dipendenze con vulnerabilità note con npm audit
• node-npmoutdated: Verifica progetti node per moduli npm obsoleti con npm outdated
• node-yarnaudit: Verifica progetti yarn per dipendenze con vulnerabilità note con yarn audit
• node-yarnoutdated: Verifica progetti node per moduli yarn obsoleti con yarn outdated

PHP

• php-security-checker: Verifica se composer.lock contiene dipendenze con vulnerabilità note utilizzando security-checker

Python

• python-bandit: Scansiona problemi di sicurezza comuni nel codice Python con bandit.
• python-piprot: Scansiona dipendenze python per pacchetti obsoleti con piprot
• python-safety: Verifica dipendenze python per vulnerabilità di sicurezza note con lo strumento safety.

Ruby

• ruby-brakeman: Analizza staticamente il codice Rails per problemi di sicurezza con Brakeman.
• ruby-bundler-scan: Scansiona gemme Ruby con vulnerabilità note utilizzando bundler

Rust

• rust-cargoaudit: Verifica se Cargo.lock contiene dipendenze con vulnerabilità note utilizzando cargo audit

Aggiungere un modulo

Se hai un'idea per un modulo, sentiti libero di aprire una richiesta di funzionalità nella sezione issues. Se hai un po' di tempo libero, considera di inviarci una pull request. Per vedere come funzionano i moduli, vai alla cartella moduli per scoprire come funzionano le cose.