goshred

README

goshred

A robust, cross-platform library for secure file deletion in Go.

goshred provides a reliable way to securely wipe files from disk, implementing data overwriting, cache flushing, and anti-forensics techniques. It includes intelligent inspection to detect SSDs and Copy-on-Write file systems to warn about potential security limitations.

Features

• Cross-Platform: Native support for Linux, Windows, macOS, and Android (Termux).
• Cryptographically Strong: Uses crypto/rand for non-deterministic data generation.
• Hardware Awareness: Detects SSDs and CoW file systems (APFS, ZFS, Btrfs).
• Anti-Forensics: Obfuscates filenames before deletion to hide metadata.
• Cache Flushing: Forces fsync to ensure data reaches the physical disk.
• Configurable: Custom pass counts, zero-filling, and buffer sizes.
• Context Support: Operations can be cancelled via context.Context.

Requirements

• Go 1.20 or higher

Installation

go get github.com/OpexDevelop/goshred

Usage

Basic Usage

Securely delete a file with default settings (1 pass, random data):

package main

import (
	"log"
	"github.com/OpexDevelop/goshred"
)

func main() {
	if err := goshred.File("secret.txt"); err != nil {
		log.Fatal(err)
	}
}

Advanced Usage

Configure passes, zero-filling, and force permissions:

package main

import (
	"log"
	"github.com/OpexDevelop/goshred"
)

func main() {
	// 3 passes (DoD standard), fill with zeros at the end, force write permissions
	err := goshred.File("database.db",
		goshred.WithPasses(3),
		goshred.WithZeroFill(true),
		goshred.WithForce(true),
	)
	
	if err != nil {
		log.Fatal(err)
	}
}

Disk Inspection

Check if secure deletion is guaranteed for a specific file (HDD vs SSD):

package main

import (
	"fmt"
	"github.com/OpexDevelop/goshred"
)

func main() {
	info, err := goshred.Inspect("data.bin")
	if err != nil {
		panic(err)
	}

	fmt.Printf("File System: %s\n", info.FileSystem)
	
	if info.Level == goshred.LevelHigh {
		fmt.Println("Security: High (HDD/Standard FS)")
	} else {
		fmt.Printf("Security: Low/Medium. Warning: %s\n", info.Warning)
	}
}

Security Levels

goshred attempts to determine the underlying storage technology:

• Level High: Standard HDD with non-CoW file system (ext4, NTFS). Overwriting is effective.
• Level Medium: SSD detected (Linux/Android). Wear leveling may prevent complete data destruction.
• Level Low: Copy-on-Write file system detected (APFS, ZFS, Btrfs). Old data blocks likely remain on disk.

Testing

To run the internal tests:

go test -v ./...

Disclaimer

Use at your own risk. While goshred implements industry-standard methods for data destruction, physical recovery of data from modern storage media (especially SSDs and Flash memory) is a complex field. The authors guarantee no liability for data recovery or data loss.

License

MIT License. See LICENSE for details.

Documentation

Index

• Variables
• func File(path string, opts ...Option) error
• func FileWithContext(ctx context.Context, path string, opts ...Option) error
• type Config
  • func NewConfig(opts ...Option) *Config
• type FileInfo
  • func Inspect(path string) (*FileInfo, error)
• type Option
  • func WithBufferSize(size int) Option
  • func WithForce(enable bool) Option
  • func WithPasses(n int) Option
  • func WithZeroFill(enable bool) Option
• type SecurityLevel

Variables

var (
	ErrFileNotExist    = errors.New("file does not exist")
	ErrDirNotSupported = errors.New("directories are not supported")
	ErrPermission      = errors.New("permission denied")
	ErrWipeFailed      = errors.New("failed to wipe data")
	ErrRemoveFailed    = errors.New("failed to remove file")
	ErrNotWritable     = errors.New("file is not writable")
)

Functions

func File

func File(path string, opts ...Option) error

func FileWithContext

func FileWithContext(ctx context.Context, path string, opts ...Option) error

Types

type Config

type Config struct {
	Passes     int
	ZeroFill   bool
	Force      bool
	BufferSize int
}

func NewConfig

func NewConfig(opts ...Option) *Config

type FileInfo

type FileInfo struct {
	Level      SecurityLevel
	IsSSD      bool
	IsCoW      bool
	FileSystem string
	Warning    string
}

func Inspect

func Inspect(path string) (*FileInfo, error)

type Option

type Option func(*Config)

func WithBufferSize

func WithBufferSize(size int) Option

func WithForce

func WithForce(enable bool) Option

func WithPasses

func WithPasses(n int) Option

func WithZeroFill

func WithZeroFill(enable bool) Option

type SecurityLevel

type SecurityLevel int

const (
	LevelHigh SecurityLevel = iota
	LevelMedium
	LevelLow
)