docker_file_analysis/CONTRIBUTING.md

Contributing to File Analysis Container

Thank you for your interest in improving the File Analysis Container! This guide will help you add and modify help content, cheat sheets, TLDR pages, and shell configurations.

📋 Table of Contents

• Getting Started
• Adding Cheat Sheets
• Adding TLDR Pages
• Adding Fish Shell Completions
• Importing Bulk Cheatsheets
• Checking Help Coverage
• Adding New Tools
• Testing Your Changes

🚀 Getting Started

Prerequisites

# Clone the repository
git clone https://github.com/tabledevil/docker_file_analysis.git
cd docker_file_analysis

# Build the container
make build-upstream

Directory Structure

docker_file_analysis/
├── scripts/
│   ├── fhelp                         # Main help system
│   ├── add-tool-cheats.sh           # Add default cheat sheets
│   ├── create-offline-help-system.sh # Initialize help database
│   ├── import-remnux-cheatsheets.sh # Import from markdown
│   └── convert-remnux-cheats.py     # Markdown converter
├── cheatsheets/
│   └── *.cheat                       # Custom cheat sheets
└── files/
    ├── command_help                  # Detailed examples
    └── README                        # Welcome message

📝 Adding Cheat Sheets

Cheat sheets provide quick command examples and common usage patterns.

Format

Cheat sheets use a simple markdown-like syntax:

# tool-name - Short description

# Example description
tool-name basic_command

# Another example with options
tool-name --option argument

# More complex example
tool-name --verbose --output result.txt input.txt

Location

• Personal cheat sheets: /opt/cheatsheets/personal/
• Community cheat sheets: /opt/cheatsheets/community/

Creating a New Cheat Sheet

Inside the container:

# Create the cheat sheet
cat > /opt/cheatsheets/personal/mytool << 'EOF'
# mytool - Analysis tool for files

# Basic file analysis
mytool sample.bin

# Verbose output
mytool -v sample.bin

# Export results to JSON
mytool --format json --output results.json sample.bin

# Scan directory recursively
mytool -r /data/samples/

# Common analysis workflow
mytool --extract-strings sample.bin | grep -i "http"
EOF

# Test it
fhelp cheat mytool

Outside the container (for permanent addition):

# Add to repository
cat > cheatsheets/mytool.cheat << 'EOF'
# mytool - Analysis tool for files
...
EOF

# Rebuild container
make build-upstream

Cheat Sheet Best Practices

1. Start with tool name and brief description
2. Order examples from simple to complex
3. Include common workflow patterns
4. Add security-relevant examples
5. Keep examples practical and concise

Example: PDF Analysis Cheat Sheet

# pdfid.py - Quick PDF structure analysis

# Basic PDF analysis
pdfid.py document.pdf

# Scan all PDFs in directory
pdfid.py *.pdf

# Look for suspicious elements
pdfid.py -a document.pdf

# Export to JSON
pdfid.py -o json document.pdf

# Detect common malicious patterns
pdfid.py document.pdf | grep -i "javascript\|openaction\|aa\|launch"

📖 Adding TLDR Pages

TLDR pages are simplified man pages focusing on practical examples.

Format

TLDR pages follow a specific structure:

# tool-name

> Brief description of what the tool does.
> More information: <https://tool-website.com>.

- Brief description of example:

`tool-name argument`

- Another example with options:

`tool-name --option {{value}}`

- Complex example:

`tool-name --input {{input.txt}} --output {{output.txt}}`

Location

• TLDR cache: ~/.local/share/tldr/
• Pages: ~/.local/share/tldr/pages/common/

Creating a TLDR Page

# Create directory if needed
mkdir -p ~/.local/share/tldr/pages/common

# Create TLDR page
cat > ~/.local/share/tldr/pages/common/mytool.md << 'EOF'
# mytool

> Analysis tool for examining potentially malicious files.
> Part of the file analysis toolkit.
> More information: <https://github.com/example/mytool>.

- Analyze a single file:

`mytool {{path/to/file}}`

- Analyze with verbose output:

`mytool --verbose {{path/to/file}}`

- Export analysis results:

`mytool --output {{results.json}} {{path/to/file}}`

- Scan directory recursively:

`mytool --recursive {{path/to/directory}}`
EOF

# Test it
tldr mytool
# OR
fhelp tldr mytool

TLDR Best Practices

1. Use placeholders like {{filename}} for user input
2. Keep descriptions brief (one line)
3. Include URL to official documentation
4. Start with simplest examples
5. Cover most common use cases (4-8 examples)

🐚 Adding Fish Shell Completions

Fish completions provide smart command-line autocompletion.

Format

Fish completions use a declarative syntax:

# mytool completions
complete -c mytool -s v -l verbose -d "Enable verbose output"
complete -c mytool -s o -l output -d "Output file" -r
complete -c mytool -s r -l recursive -d "Scan recursively"
complete -c mytool -s h -l help -d "Show help message"

Location

Fish completions go in: ~/.config/fish/completions/

Creating Fish Completions

# Create directory
mkdir -p ~/.config/fish/completions

# Create completions file
cat > ~/.config/fish/completions/mytool.fish << 'EOF'
# mytool - File analysis tool completions

# Basic options
complete -c mytool -s v -l verbose -d "Verbose output"
complete -c mytool -s h -l help -d "Show help"
complete -c mytool -s V -l version -d "Show version"

# File/directory arguments
complete -c mytool -s o -l output -d "Output file" -r -F
complete -c mytool -s i -l input -d "Input file" -r -F

# Analysis options
complete -c mytool -l format -d "Output format" -r -a "json xml text"
complete -c mytool -l extract -d "Extract embedded files"
complete -c mytool -s r -l recursive -d "Recursive scan"
EOF

# Test it (restart fish or source completions)
fish
mytool --<TAB>

Fish Completion Best Practices

1. Complete both short (-v) and long (--verbose) options
2. Add descriptions with -d "description"
3. Use -r for options requiring arguments
4. Use -F for file/path completion
5. Use -a for fixed value choices

📦 Importing Bulk Cheatsheets

For adding many cheat sheets at once from a consolidated markdown file.

Prepare Your Markdown

Create a consolidated cheatsheet file with this structure:

## tool1

```bash
# Example 1
tool1 command

tool2

# Example 2
tool2 --option value

### Import Process

```bash
# Inside the container:

# Place your markdown file in /data
# (mounted from host)

# Import cheatsheets
import-remnux-cheatsheets.sh /data/my-cheatsheets.md

# Verify import
fhelp cheat tool1
fhelp cheat tool2

Converter Script

The convert-remnux-cheats.py script handles the conversion:

# Convert markdown to cheat/tldr format
convert-remnux-cheats.py input.md output_dir/

# This creates:
# output_dir/cheat/tool1
# output_dir/cheat/tool2
# output_dir/tldr/tool1.md
# output_dir/tldr/tool2.md

Bulk Import Example

# Example workflow
cat > my-tools.md << 'EOF'
## exiftool

```bash
# Extract metadata
exiftool file.jpg

# Remove all metadata
exiftool -all= file.jpg

binwalk

# Scan for embedded files
binwalk firmware.bin

# Extract files
binwalk -e firmware.bin

EOF

Import

import-remnux-cheatsheets.sh my-tools.md

Verify

fhelp cheat exiftool fhelp cheat binwalk

## 🔍 Checking Help Coverage

Use the coverage checker to find tools missing documentation.

### Run Coverage Check

```bash
# Inside container:
check-help-coverage.sh

# Output shows:
# ✓ Tools with both cheat and TLDR
# ⚠ Tools with only cheat
# ⚠ Tools with only TLDR
# ✗ Tools with no help

Example Output

Checking help coverage for analysis tools...

✓ pdfid        [cheat] [tldr]
✓ pdf-parser   [cheat] [tldr]
⚠ oledump      [cheat] [    ]
⚠ rtfdump      [    ] [tldr]
✗ newtool      [    ] [    ]

Summary:
  Total tools: 5
  Complete: 2 (40%)
  Partial: 2 (40%)
  Missing: 1 (20%)

Adding Missing Help

Based on coverage report, add missing help content:

# Tool with no help
cat > /opt/cheatsheets/personal/newtool << 'EOF'
# newtool - Description
# Basic usage
newtool file
EOF

# Tool missing TLDR
mkdir -p ~/.local/share/tldr/pages/common
cat > ~/.local/share/tldr/pages/common/oledump.md << 'EOF'
# oledump
> Analyze OLE files
...
EOF

# Verify
check-help-coverage.sh

🔧 Adding New Tools

1. Add to Dockerfile

# Install via apt
RUN apt-get update && apt-get install -y newtool

# OR install via pip
RUN pip install newtool

# OR install from source
RUN git clone https://github.com/author/newtool /opt/newtool \
    && cd /opt/newtool \
    && make install

2. Add Help Content

# Cheat sheet
cat > cheatsheets/newtool.cheat << 'EOF'
# newtool - Tool description
# Basic usage
newtool file.bin
EOF

# TLDR page
cat > tldr/newtool.md << 'EOF'
# newtool
> Tool description
- Basic usage:
`newtool {{file}}`
EOF

3. Add to Help System Script

Edit scripts/add-tool-cheats.sh:

# Add newtool cheat sheet
cat > "$CHEAT_DIR/newtool" << 'EOF'
# newtool - Tool description
# Basic usage
newtool file.bin
EOF

4. Rebuild and Test

# Rebuild container
make build-upstream

# Test
docker run --rm tabledevil/file-analysis:remnux newtool --version
docker run --rm tabledevil/file-analysis:remnux fhelp cheat newtool

🧪 Testing Your Changes

Test Locally

# Build container
make build-upstream

# Run interactive session
docker run -it --rm tabledevil/file-analysis:remnux

# Inside container, test help system
fhelp cheat yourtool
fhelp tldr yourtool

Test Help System

# Test main help
docker run --rm tabledevil/file-analysis:remnux fhelp

# Test tool search
docker run --rm tabledevil/file-analysis:remnux fhelp tools pdf

# Test cheat access
docker run --rm tabledevil/file-analysis:remnux fhelp cheat pdfid

# Run coverage check
docker run --rm tabledevil/file-analysis:remnux check-help-coverage.sh

Test Shells

# Test zsh
docker run --rm -it tabledevil/file-analysis:remnux zsh

# Test fish
docker run --rm -it tabledevil/file-analysis:remnux fish

# Test completions
docker run --rm -it tabledevil/file-analysis:remnux fish -c "complete -C'pdfid.py -'"

📤 Submitting Changes

Create a Pull Request

1. Fork the repository
2. Create a feature branch

   git checkout -b add-mytool-help
   

3. Make your changes
   • Add cheat sheets
   • Add TLDR pages
   • Update scripts if needed
4. Test your changes

   make build-upstream
   make test
   

5. Commit and push

   git add cheatsheets/mytool.cheat
   git commit -m "Add cheat sheet for mytool"
   git push origin add-mytool-help
   

6. Open pull request on GitHub

Commit Message Guidelines

Add cheat sheet for mytool

- Include basic usage examples
- Add common workflow patterns
- Covers malware analysis use cases

🎯 Quick Reference

Common Tasks

Task	Command
Add cheat sheet	vim /opt/cheatsheets/personal/tool
Add TLDR page	vim ~/.local/share/tldr/pages/common/tool.md
Test cheat	fhelp cheat tool
Test TLDR	tldr tool or fhelp tldr tool
Check coverage	check-help-coverage.sh
Import bulk	import-remnux-cheatsheets.sh file.md

File Locations

Content Type	Location
Cheat sheets	/opt/cheatsheets/personal/
TLDR pages	~/.local/share/tldr/pages/common/
Fish completions	~/.config/fish/completions/
Help script	/usr/local/bin/fhelp

💡 Tips and Best Practices

1. Test in container - Always test help content inside the container
2. Keep examples practical - Focus on real analysis workflows
3. Use consistent formatting - Follow existing cheat sheet styles
4. Add context - Include brief descriptions for each example
5. Cover common cases - 80% of use cases with 20% of examples
6. Security focus - Emphasize malware analysis patterns
7. Cross-reference - Link related tools in descriptions

🆘 Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See docs/ directory for archived documentation

📚 Additional Resources

• cheat syntax guide
• TLDR pages format
• Fish shell completions
• REMnux documentation

---

Thank you for contributing to the File Analysis Container project! 🎉