add docs

Tanq16 · Dec 11, 2024 · 4a2b743 · 4a2b743
1 parent 505e633
commit 4a2b743
Show file tree

Hide file tree

Showing 21 changed files with 1,385 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -1,56 +1,105 @@
 <h1 align="center">
   <br>
-  <img src="docs/assets/CST-Logo.png" alt="DISecT" width="290"></a>
-  <br>Containerized Security Toolkit (CST)<br>
+  <img src="docs/assets/CST-Logo.png" alt="CST" width="290">
+  <br>
+  Containerized Security Toolkit (CST)
+  <br>
 </h1>
 
 <p align="center">
-    <a href="https://tanishq.page/blog/posts/cst-guide/"><b>Companion Blog</b></a>  &bull;  
-    <a href="https://hub.docker.com/r/tanq16/sec_docker"><b>Docker Hub</b></a><br><br>
-    <a href="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/rice-build.yml"><img src="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/rice-build.yml/badge.svg" alt="Release Build"></a>
-    <a href="https://dl.circleci.com/status-badge/redirect/circleci/YPqXqLMjjXxLwPP9TvpyFc/W1CQsWfrfu4rKFiytoHbs9/tree/main"><img src="https://dl.circleci.com/status-badge/img/circleci/YPqXqLMjjXxLwPP9TvpyFc/W1CQsWfrfu4rKFiytoHbs9/tree/main.svg?style=shield"></a><br>
-    (ARM builds through CCI until ARM GHA runners are available)
+  <a href="https://github.com/tanq16/containerized-security-toolkit/releases">
+    <img src="https://img.shields.io/github/v/release/tanq16/containerized-security-toolkit?include_prereleases&style=flat-square">
+  </a>
+  <a href="https://hub.docker.com/r/tanq16/cst">
+    <img src="https://img.shields.io/docker/pulls/tanq16/cst?style=flat-square">
+  </a>
+  <a href="https://github.com/tanq16/containerized-security-toolkit/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/tanq16/containerized-security-toolkit?style=flat-square">
+  </a>
+  <br>
+  <a href="https://tanishq.page/containerized-security-toolkit">Documentation</a> •
+  <a href="https://hub.docker.com/r/tanq16/cst">Docker Hub</a>
 </p>
 
-<br>
+<h4 align="center">A comprehensive suite of containerized security toolkits for various security operations</h4>
 
-This project contains two Dockerfiles for a multi-stage image build that results in an ARM (useful for Apple Silicon Macs) or x86_64 variants of a security focused docker image &rarr;
+<p align="center">
+  <b>Build Status:</b><br>
+  General: 
+  <a href="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/general-build.yml">
+    <img src="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/general-build.yml/badge.svg" alt="General Build">
+  </a>
+  <a href="https://dl.circleci.com/status-badge/redirect/circleci/YPqXqLMjjXxLwPP9TvpyFc/general/tree/main">
+    <img src="https://dl.circleci.com/status-badge/img/circleci/YPqXqLMjjXxLwPP9TvpyFc/general/tree/main.svg?style=shield" alt="General ARM Build">
+  </a>
+  <br>
+  Cloud: 
+  <a href="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/cloud-build.yml">
+    <img src="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/cloud-build.yml/badge.svg" alt="Cloud Build">
+  </a>
+  <a href="https://dl.circleci.com/status-badge/redirect/circleci/YPqXqLMjjXxLwPP9TvpyFc/cloud/tree/main">
+    <img src="https://dl.circleci.com/status-badge/img/circleci/YPqXqLMjjXxLwPP9TvpyFc/cloud/tree/main.svg?style=shield" alt="Cloud ARM Build">
+  </a>
+  <br>
+  Rice: 
+  <a href="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/rice-build.yml">
+    <img src="https://github.com/tanq16/containerized-security-toolkit/actions/workflows/rice-build.yml/badge.svg" alt="Rice Build">
+  </a>
+  <a href="https://dl.circleci.com/status-badge/redirect/circleci/YPqXqLMjjXxLwPP9TvpyFc/rice/tree/main">
+    <img src="https://dl.circleci.com/status-badge/img/circleci/YPqXqLMjjXxLwPP9TvpyFc/rice/tree/main.svg?style=shield" alt="Rice ARM Build">
+  </a>
+</p>
 
-- **Security Image for x86_64**
-- **Security Image for ARM64**
+## Overview
 
-The image is built automatically on via CI/CD pipelines and pushed to Docker Hub. The image is called `sec_docker` and it presents multiple tags &rarr;
+The Containerized Security Toolkit (CST) provides a comprehensive suite of Docker images tailored for various security operations. Each variant is designed for specific use cases while maintaining consistency in basic functionality:
 
-| | x86\_64 | ARM |
-| --- | --- | --- |
-| tag | `main` | `main_apple` |
-| image ref | `tanq16/sec_docker:main` | `tanq16/sec_docker:main_apple` |
+- **General** (`tanq16/cst-general:*`): Core security tools and utilities for general security operations
+- **Cloud** (`tanq16/cst-cloud:*`): Specialized for cloud security assessments and operations
+- **Dev** (`tanq16/cst-dev:*`): Development environment with security tools (Python, Go, Node.js) - WIP
+- **Netsec** (`tanq16/cst-netsec:*`): Network security assessment and monitoring tools - WIP
+- **Rice** (`tanq16/cst-rice:*`): Enhanced version of General with [CLI Productivity Suite](https://github.com/Tanq16/cli-productivity-suite)
 
-It has the [cli-productivity-suite](https://github.com/tanq16/cli-productivity-suite) preinstalled within the image. The [companion blog post](https://tanishq.page/blog/posts/cst-guide/) goes over using the pre-built image, building it with modifications, conventions considered when creating the Dockerfiles, and different ways it can be used.
+Each variant is available for both x86_64 and ARM64 architectures:
 
----
+```
+tanq16/cst-<variant>:amd  # For x86_64 systems
+tanq16/cst-<variant>:arm  # For ARM64 systems (Apple Silicon, etc.)
+```
+
+## Quickstart
 
-For a quick look into the container and its capabilities, built from this image, is as follows &rarr; 
+Get started with the General variant in seconds:
 
 ```bash
-docker run --name="sec_docker_quickstart" --rm -it tanq16/sec_docker:main /bin/zsh
+# Create persistence directory
+mkdir -p $HOME/docker_work/
+
+# Run container (use general-arm for ARM64 systems)
+docker run --name="cst_general" \
+  -v $HOME/docker_work/:/persist \
+  --rm -it tanq16/cst-general:amd \
+  /bin/bash
 ```
 
-It is also recommended to run the following command (replace with your timezone in second line) after getting into the container &rarr;
+For advanced usage patterns, variant-specific guides, and comprehensive documentation:
+- 📚 [Full Documentation](https://tanishq.page/containerized-security-toolkit)
+- 🚀 [Advanced Workflows](https://tanishq.page/containerized-security-toolkit/advanced/workflows)
+- 🔧 [Tool Lists](https://tanishq.page/containerized-security-toolkit/tools/general-tools)
 
-```bash
-export TERM=xterm-256color && \
-echo "America/Chicago" > /etc/timezone && rm -rf /etc/localtime && \
-ln -s "/usr/share/zoneinfo/$(cat /etc/timezone)" /etc/localtime
-```
+## Key Features
+
+- 🔄 **Persistent Storage**: Mount local directories for data persistence
+- 🔒 **Secure Design**: Regular security updates and best practices
+- 🎯 **Purpose-Built**: Each variant optimized for specific security tasks
+- 🔧 **Rich Tooling**: Comprehensive set of pre-installed security tools
+- 📦 **Consistent Environment**: Reproducible setup across systems
+- 🖥️ **Cross-Platform**: Full support for both x86_64 and ARM64
 
-If you exit the shell, the container will be destroyed along with the information in the ephemeral filesystem. I recommend reading the [companion blog post](https://tanishq.page/blog/posts/cst-guide/) for a better workflow
+## Contributing
 
-There are several other nuances related to running the container, such as &rarr;
+Check out [contribution guidelines](https://tanishq.page/containerized-security-toolkit/home/contributing) for details on how to submit changes.
 
-- setting up a persistence diretcory across container restarts
-- using one-word shell functions to start and stop containers with customized settings
-- connecting to the container via SSH
-- dynamic port-forwarding over SSH to access container-local services
+## License
 
-All of the above nuances are comprehensively explained in the [companion blog post](https://tanishq.page/blog/posts/cst-guide/), especially the *Example Workflow* section.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
diff --git a/docs/advanced/build.md b/docs/advanced/build.md
@@ -0,0 +1,156 @@
+# DIY Build Guide
+
+The CST images can be customized and built locally. This guide explains the build process and customization options.
+
+## Basic Build Process
+
+CST uses a multi-stage build process for efficient image creation:
+
+1. **Builder Stage**
+   ```dockerfile
+   FROM ubuntu:jammy AS executable_builder
+   # Tool compilation and binary creation
+   ```
+
+2. **Final Stage**
+   ```dockerfile
+   FROM ubuntu:jammy
+   # System setup and tool installation
+   ```
+
+### Building Images
+
+Basic build commands:
+
+```bash
+# Change to variant directory
+cd images/<variant>
+
+# Build intermediate layer
+docker build -f builder.Dockerfile -t intermediate_builder .
+
+# Build final image
+docker build -t cst-<variant>:local .
+
+# Clean up
+docker builder prune -f
+```
+
+## Customization Options
+
+### Adding New Tools
+
+1. **Builder Stage Modifications**
+   ```dockerfile
+   # In builder.Dockerfile
+   RUN go install github.com/your/tool@latest && \
+       mv /go/bin/tool /executables/
+   ```
+
+2. **Final Stage Additions**
+   ```dockerfile
+   # In Dockerfile
+   RUN apt-get update && apt-get install -y \
+       your-additional-package
+
+   # Add custom scripts
+   COPY ./scripts/custom.sh /opt/scripts/
+   ```
+
+### Creating New Variants
+
+1. Create new variant directory:
+   ```bash
+   mkdir -p images/custom
+   cp images/general/* images/custom/
+   ```
+
+2. Modify Dockerfiles for specific needs:
+   ```dockerfile
+   # Add specialized tools
+   RUN apt-get update && apt-get install -y \
+       specialized-package
+
+   # Add custom configurations
+   COPY configs/ /etc/custom/
+   ```
+
+## Advanced Building
+
+### Cross-Platform Builds
+
+Building for multiple architectures:
+
+```bash
+# Setup buildx
+docker buildx create --use
+
+# Build multi-platform image
+docker buildx build \
+    --platform linux/amd64,linux/arm64 \
+    -t username/cst-custom:latest .
+```
+
+### Optimization Techniques
+
+1. **Layer Optimization**
+   ```dockerfile
+   # Combine related operations
+   RUN apt-get update && \
+       apt-get install -y \
+       package1 \
+       package2 && \
+       apt-get clean && \
+       rm -rf /var/lib/apt/lists/*
+   ```
+
+2. **Size Reduction**
+   ```dockerfile
+   # Use multi-stage builds
+   FROM build-image AS builder
+   # Build tools
+
+   FROM runtime-image
+   # Copy only necessary files
+   COPY --from=builder /app/binary /usr/local/bin/
+   ```
+
+## Testing Builds
+
+1. **Basic Testing**
+   ```bash
+   # Build test image
+   docker build -t cst-test .
+
+   # Run basic tests
+   docker run --rm cst-test which tool1 tool2 tool3
+   ```
+
+2. **Feature Testing**
+   ```bash
+   # Test specific features
+   docker run --rm cst-test \
+       bash -c "tool --version && tool --help"
+   ```
+
+## Best Practices
+
+1. **Version Control**
+   - Tag images with version numbers
+   - Document changes in changelog
+   - Use semantic versioning
+
+2. **Documentation**
+   - Update tool lists
+   - Document new features
+   - Include usage examples
+
+3. **Security**
+   - Scan images for vulnerabilities
+   - Update base images regularly
+   - Follow security best practices
+
+4. **Maintenance**
+   - Regular dependency updates
+   - Version compatibility checks
+   - Performance optimization