First commit

Author: seekbytes

.gitignore

@@ -13,3 +13,6 @@
 
 # Dependency directories (remove the comment below to include it)
 # vendor/
+data/
+examples/
+

CHANGELOG

@@ -0,0 +1,2 @@
+Versione 0.0.1-alpha:
+- Prima versione

LICENSE

@@ -1,21 +1,27 @@
-MIT License
+Copyright 2022 MicroSCOPE
 
-Copyright (c) 2022 SeekBytes
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of the MicroSCOPE project nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,2 +1,22 @@
-# MicroSCOPE
-MicroSCOPE analizza binari PE/ELF per individuare comportamenti simili a ransomware
+![MicroSCOPE logo](https://github.com/seekbytes/MicroSCOPE/blob/main/utils/MicroSCOPE.jpg?raw=true)
+
+## Scopo del progetto
+
+MicroSCOPE è un software sviluppato tramite il linguaggio di programmazione [Go](https://go.dev) che permette di inidividuare una precisa categoria di software dannoso. Il programma è stato studiato specificamente per una classe di programmi dannosi chiamata _ransomware_ il cui funzionamento consiste nella crittazione dei dati e richiesta di riscatto per poter riaccedere al contenuto.
+
+In particolare, MicroSCOPE è stato sviluppato per poter supportare due tra i formati principalmente utilizzati: il formato PE (_Portable Executable_) per piattaforme Windows ed ELF (_Executable and Linking Format_) per piattaforme Unix-based. Tramite l'applicazione di alcune euristiche, MicroSCOPE è in grado di attribuire un punteggio che corrisponde al livello di pericolosità del file che si vuole analizzare. Tanto più alto è il punteggio, tanto più il software presenterà caratteristiche simili a ransomware già studiati. Le euristiche sono state estrapolate da numerosi casi di studio e verranno migliorate nel corso del tempo.
+
+## Struttura del progetto
+
+* `analysis`: cartella relativa all'analisi statica dei binari (incluso le varie fasi di MicroSCOPE)
+* `docs`: cartella contenente la documentazione del progetto MicroSCOPE
+* `formats`: cartella relativa ai formati file binari (ELF e PE) incluse costanti, controlli e parsing del binario;
+* `heuristics`: le euristiche vere e proprie
+* `utils`: utilità generali
+
+## Come funziona
+
+L'analisi effettuata da MicroSCOPE ha tre fasi principali:
+* **data mining**: analisi approfondita del file binario in base al tipo di estensione (ad esempio: se file PE o ELF), estrapolando stringhe, funzioni che utilizza e qualsiasi altra informazione potenzialmente utile per prevedere l'esecuzione del programma;
+* **applicazione delle euristiche**: in base alle informazioni estrapolate dalla prima fase, si applicano le euristiche che consentono di capire che comportamento avrà il programma una volta eseguito. In questa fase viene calcolato un punteggio (sommatoria dei vari punteggi delle euristiche);
+* **determinazione del risultato**: in base al punteggio e sopra un certo valore (chiamato valore di threshold - definito dall'utente), MicroSCOPE assocerà un certo punteggio a un comportamento malevolo;

analysis/analysis.go

@@ -0,0 +1,229 @@
+package analysis
+
+import (
+	"bufio"
+	"bytes"
+	"crypto/sha256"
+	"fmt"
+	"html/template"
+	"io"
+	"microscope/formats"
+	"microscope/formats/elf"
+	"microscope/formats/pe"
+	"microscope/heuristics"
+	"os"
+	"strconv"
+	"time"
+)
+
+const (
+	FILE_HEADER_PHASE_1 = 5 // Numero di byte letti all'inizio della fase 1 (vedi documenti) per discriminare il file
+)
+
+var OutputTemplateHTML string
+var OutputTemplateTXT string
+
+func divide(a int, b int) int {
+	return a / b
+}
+
+func PrintResult(Analyzed *formats.FileAnalyzed) {
+	// lista delle funzioni passate al template
+	funcMap := template.FuncMap{
+		"now":                          time.Now,
+		"divide":                       divide,
+		"PEprintArchitecture":          pe.PrintArchitecture,
+		"PEprintResource":              pe.PrintResource,
+		"PEprintSubsystem":             pe.PrintSubsystem,
+		"PEprintMajorOperatingVersion": pe.PrintMajorOperatingSystemVersion,
+		"PEprintCharacteristics":       pe.PrintCharacteristic,
+		"ELFprintMachine":              elf.PrintMachine,
+		"ELFprintSectionType":          elf.PrintSectionType,
+		"ELFprintFileType":             elf.PrintFileType,
+	}
+
+	if Analyzed.OutputFormat == "txt" {
+
+		// carica un template .txt e popolalo con la struttura fileAnalyzed
+		t := template.Must(template.New("output_template.txt").Funcs(funcMap).Parse(OutputTemplateTXT))
+		var processed bytes.Buffer
+
+		err := t.Execute(&processed, Analyzed)
+		if err != nil {
+			fmt.Println("Non è stato possibile eseguire il template per questo motivo: " + err.Error())
+			return
+		}
+		outputPath := "./results/" + Analyzed.Name + "_analysis.txt"
+		f, err := os.Create(outputPath)
+		if err != nil {
+			fmt.Println("Impossibile creare nuovo file.")
+			return
+		}
+		w := bufio.NewWriter(f)
+		_, err = w.WriteString(string(processed.Bytes()))
+		if err != nil {
+			fmt.Println("Impossibile scrivere il template sul file per il seguente errore: " + err.Error())
+			return
+		}
+		err = w.Flush()
+		if err != nil {
+			fmt.Println("Impossibile rimuovere il contenuto dell'IOBuffer.")
+			return
+		}
+
+	} else if Analyzed.OutputFormat == "html" {
+
+		// carica un template html e popolalo con la struttura fileAnalyzed
+		t := template.Must(template.New("output_template.html").Funcs(funcMap).Parse(OutputTemplateHTML))
+
+		var processed bytes.Buffer
+
+		err := t.Execute(&processed, Analyzed)
+		if err != nil {
+			fmt.Println("Non è stato possibile eseguire il template per questo motivo: " + err.Error())
+			return
+		}
+		outputPath := "./results/" + Analyzed.Name + "_analysis.html"
+		f, err := os.Create(outputPath)
+		if err != nil {
+			fmt.Println("Impossibile creare nuovo file.")
+			return
+		}
+		w := bufio.NewWriter(f)
+		_, err = w.WriteString(string(processed.Bytes()))
+		if err != nil {
+			fmt.Println("Impossibile scrivere il template sul file per il seguente errore: " + err.Error())
+			return
+		}
+		err = w.Flush()
+		if err != nil {
+			fmt.Println("Impossibile rimuovere il contenuto dell'IOBuffer.")
+			return
+		}
+	} else {
+		fmt.Println("Formato file non valido.")
+	}
+
+	fmt.Println("Microscope risultato. ")
+	fmt.Println("Formato file : " + Analyzed.Format)
+	fmt.Println("Architettura : " + Analyzed.Architecture)
+	fmt.Println("Dimensione del file " + strconv.FormatInt(Analyzed.Size, 10))
+	fmt.Println("Punteggio " + strconv.FormatInt(int64(Analyzed.Score), 10))
+
+	if Analyzed.Score > Analyzed.Threshold {
+		fmt.Println("!!!!!RANSOMWARE!!!!")
+	}
+
+	if Analyzed.Score > Analyzed.Threshold/2 && Analyzed.Score < Analyzed.Threshold {
+		fmt.Println("È un possibile malware.")
+	}
+
+}
+
+func ReadContentFile(file *os.File) []byte {
+	// Molto importante impostare l'offset del file dall'inizio altrimenti c'è il rischio che la io.ReadAll
+	// legga dal punto in cui l'offset è rimasto dalla funzione analysis
+	newPosition, err := file.Seek(0, io.SeekStart)
+
+	if err != nil {
+		fmt.Println("Errore durante l'impostazione dell'offset " + err.Error())
+		return nil
+	}
+
+	if newPosition != 0 {
+		fmt.Println("Errore durante l'impostazione dell'offset")
+		return nil
+	}
+
+	content, err := io.ReadAll(file)
+	if err != nil {
+		fmt.Println("Impossibile leggere il contenuto del file per il seguente motivo " + err.Error())
+		return nil
+	}
+	return content
+}
+
+func StartAnalysis(file *os.File, Analyzed *formats.FileAnalyzed) {
+
+	// Controlla i primi FILE_HEADER_PHASE_1 byte di file
+	var header [FILE_HEADER_PHASE_1]byte
+	// Ritorna il numero di byte letti
+	n, err := io.ReadFull(file, header[:])
+	if err != nil || n != FILE_HEADER_PHASE_1 {
+		fmt.Println("Impossibile leggere i primi 10 byte.")
+		return
+	}
+
+	// Leggi contenuto del file
+	Analyzed.Raw = ReadContentFile(file)
+	h := sha256.New()
+	h.Write(Analyzed.Raw)
+	Analyzed.Hash = fmt.Sprintf("%x", h.Sum(nil))
+
+	// Se il file contiene un possibile elf header, allora..
+	if IsELFBinary(header) {
+		Analyzed.Format = "ELF"
+		// Procediamo con l'analisi dei segmenti ELF
+		elf.ELFAnalysis(file, &Analyzed.ELFInterface)
+		var machine uint16
+		switch headerFields := Analyzed.ELFInterface.Header.(type) {
+		case elf.Header32:
+			machine = headerFields.Machine
+		case elf.Header64:
+			machine = headerFields.Machine
+		}
+
+		Analyzed.Architecture = elf.PrintMachine(machine)
+	}
+
+	// Altrimenti controlla se è un possibile binario PE
+	if isPEBinary(header) {
+		Analyzed.Format = "PE"
+		// Procediamo con l'analisi del file PE
+		pe.Analysis(&Analyzed.PEInterface, Analyzed.Raw)
+		Analyzed.Architecture = pe.PrintArchitecture(Analyzed.PEInterface.COFFHeader.Machine)
+	}
+
+	if Analyzed.Format == "PE" || Analyzed.Format == "ELF" {
+		// Estrai le stringhe
+		Analyzed.ExtractedStrings = ExtractStrings(file, 6, 256, true)
+
+		// Applica le euristiche
+		heuristics.Execute(Analyzed)
+
+		// Stampa il risultato
+		PrintResult(Analyzed)
+	} else {
+		fmt.Println("Questo tipo di file non è al momento supportato da MicroSCOPE.")
+	}
+}
+
+func IsELFBinary(content [FILE_HEADER_PHASE_1]byte) bool {
+	// Controllo dei primi tre byte "ELF"
+	if content[0] == 0x7f && content[1] == byte('E') && content[2] == byte('L') && content[3] == byte('F') {
+		return true
+	}
+
+	return false
+}
+
+func isPEBinary(content [FILE_HEADER_PHASE_1]byte) bool {
+
+	// TODO: Questa è una prima euristica molto veloce che consente subito di determinare se un file potrebbe essere un file PE oppure no
+	// Rimangono da verificare tutti i casi limite
+	// Potrebbe essere utile passare di nuovo il puntatore del file a questa funzione per cercare l'offset 0x3c che indica la struttura PE
+	// e il successivo controllo sulla signature PE
+
+	// Controlla lo stub per Microsoft MS-DOS (i primi due byte devono essere MZ dal nome del creatore del formato)
+	if content[0] == byte('M') || content[1] == byte('Z') {
+		return true
+	}
+
+	// Esistono anche binari che hanno la sigla "MZ" invertita
+
+	if content[0] == byte('Z') || content[0] == byte('M') {
+		return true
+	}
+
+	return false
+}

analysis/strings.go

@@ -0,0 +1,48 @@
+package analysis
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+)
+
+func ExtractStrings(file *os.File, min, max int, ascii bool) []string {
+	// Optimize the function
+	_, err := file.Seek(1000, io.SeekStart)
+	if err != nil {
+		fmt.Println("Impossibile fare il seek per il seguente motivo: " + err.Error())
+	}
+	content, _ := io.ReadAll(file)
+	in := bytes.NewReader(content)
+
+	str := make([]rune, 0, max)
+	var res []string
+	next := func() {
+		if len(str) >= min {
+			res = append(res, string(str))
+		}
+		str = str[0:0]
+	}
+
+	// One string per loop.
+	for {
+		ch, _, err := in.ReadRune()
+		if err != nil {
+			if err != io.EOF {
+				fmt.Println(err.Error())
+			}
+			return res
+		}
+		if !strconv.IsPrint(ch) || ascii && ch >= 0xFF {
+			next()
+			continue
+		}
+		// It's printable. Keep it.
+		if len(str) >= max {
+			next()
+		}
+		str = append(str, ch)
+	}
+}

docs/HOWTO.md

@@ -0,0 +1,32 @@
+# HOW TO
+
+## Compilare il codice
+
+Attraverso `go build` è possibile compilare il codice e ottenere un binario statico da poter eseguire nella maggior parte delle architetture disponibili sul mercato. Per modificare l'architettura target per il binario che vorremo generare, bisogna impostare le variabili d'ambiente `GOOS` (sistema operativo target) e `GOARCH` (l'architettura di riferimento).
+
+## Utilizzare MicroSCOPE
+
+È possibile avviare l'analisi di un qualsiasi binario utilizzando il comando `microscope` o avviando l'eseguibile tramite `./microscope` (assumendo che il binario sia nella stessa cartella da dove si lancia il comando). Di seguito le flags:
+
+* `-f` **OBBLIGATORIA** specifica il file per l'analisi (di default è vuoto); è possibile specificare path assoluti o relativi, purché siano validi. 
+* `-t` : threshold, valore numerico specifico per il valore di threshold. Default è 100.
+* `-o`: il formato file di analisi: `html` oppure `txt`
+* `-d`: limite che specifica il massimo numero di byte che un binario ha e può essere analizzato da MicroSCOPE. Scarta tutti i binari maggiori del limite. Per default, questo valore è stato impostato a `2^32 - 1` (4 GByte).
+
+Esempio (carica in microscope un binario chiamato sample-ransomware, imposta il threshold a 10 e come output HTML):
+```
+microscope -f sample-ransomware -t 10 -o html
+```
+
+Il risultato sarà all'interno della cartella `results` creato da MicroSCOPE nella stessa cartella da dove viene eseguito. Come nome del file del risultato verrà utilizzato il nome del file analizzato.
+
+## Contribuire a MicroSCOPE
+
+Ognuno può contribuire al progetto MicroSCOPE, a patto di non violare la licenza.
+
+Parti in cui serve un aiuto o un contributo:
+* testing di MicroSCOPE con ransomware recenti;
+* testing di MicroSCOPE con binari malformati;
+* approfondimento e dettagli delle euristiche;
+
+Hai due principali metodi per contribuire: puoi creare un nuova segnalazione se pensi di essere incappato in un [problema](https://github.com/seekbytes/MicroSCOPE/issues), oppure aprire una nuova [Pull Request](https://github.com/seekbytes/MicroSCOPE/pulls).