Metadata-Version: 2.4
Name: shadowstep
Version: 1.0.0
Summary: Advanced Anti-Forensics & System Artifact Management Tool
Home-page: https://github.com/s4l1hs/ShadowStep
Author: Salih Sefer
Author-email: senin@emailin.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Environment :: Console
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml
Requires-Dist: colorama
Requires-Dist: setproctitle
Requires-Dist: psutil
Requires-Dist: pywin32; sys_platform == "win32"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ShadowStep
ShadowStep is a professional-grade, modular toolkit for artifact management, metadata manipulation, and system sanitization. It is designed as a developer-focused framework for automating and testing cover-track workflows in authorized, legal, and controlled environments.

Key design goals:
- Modular components with clear responsibilities.
- Cross-platform awareness (Windows, Linux, macOS) with safe fallbacks.
- Auditability and testability for research and red-team exercises.

This README documents the project structure, modules, CLI usage, installation, development workflow, and an explicit security & ethics notice.

---

**Table of Contents**

- Project Overview
- Features
- Modules & Files
- Installation
- Configuration
- CLI Usage & Examples
- Development & Testing
- Packaging
- Security, Ethics & Legal Notice
- Roadmap
- Contributing
- License

---

Project Overview
----------------

ShadowStep provides a set of cooperative utilities for managing system artifacts and metadata. The tool is intended for use by security professionals, researchers, and system administrators who need to understand and test artifact lifecycles. The project is not intended to facilitate malicious activity — see the Security & Ethics section.

Features
--------

- Secure file deletion with configurable overwrite passes (`utils/shredder.py`).
- Timestamp manipulation / timestomping for analysis and testing scenarios (`core/forensic_view.py`).
- System trace cleaning helpers: clipboard, shell history, DNS cache, RAM & swap handling (`core/janitor.py`, `core/memory_cleaner.py`).
- Network identity utilities (MAC generation/change; Linux-focused) (`core/network_utils.py`).
- Surgical log operations (text-based logs on Linux/macOS, structured handling for Windows Event Logs) skeleton (`core/log_surgeon.py`).
- Centralized, colorized logging support (`utils/logger.py`, `utils/colors.py`).
- Simple YAML-based configuration (`config/default.yaml`) with a loader in `config/__init__.py`.

Modules & Files
----------------

- `shadowstep.py` — main CLI entry module and argument routing. Installable via `setup.py` entry point `shadowstep=shadowstep:main`.
- `core/forensic_view.py` — `TimeStomper` class: cross-platform timestamp manipulation functions.
- `core/log_surgeon.py` — `LogSurgeon` class: surgical cleaning and (safe) decoy injection strategies; designed with platform checks.
- `core/janitor.py` — `Janitor` class: higher-level cleanup orchestration (clipboard, history, DNS, logs).
- `core/memory_cleaner.py` — `MemoryCleaner` class: RAM & swap utilities (relies on `psutil` when available).
- `core/network_utils.py` — `NetworkManager` class: MAC generation and Linux-focused MAC change functionality.
- `utils/shredder.py` — `secure_delete()` function: overwrites and deletes files.
- `utils/logger.py` & `utils/colors.py` — logging and color helpers.
- `config/default.yaml` — default configuration values (app metadata, logging level, shredder defaults, network defaults).

Installation
------------

Recommended: create and use a Python virtual environment.

```bash
python -m venv .venv
source .venv/bin/activate  # macOS / Linux
\.venv\Scripts\activate   # Windows (PowerShell)
pip install -r requirements.txt
pip install -e .
```

After installing with `pip install -e .`, the `shadowstep` console script will be available on your PATH and resolves to `shadowstep:main`.

Configuration
-------------

Default configuration is located in `config/default.yaml`. The project loads this YAML at import time via `config/__init__.py`. Example config fields include:

- `app.version` and `app.environment`
- `logging.level` and `logging.file_path`
- `shredder.default_passes` and `shredder.method`
- `network.spoof_oui`

Override configuration by editing `config/default.yaml` or by providing a different loader in your own environment when embedding the library.

CLI Usage & Examples
---------------------

ShadowStep exposes a single-script CLI. Run `shadowstep --help` after install, or invoke directly via the module:

```bash
python -m shadowstep --help
```

Common commands and examples:

- Secure delete a file (default 3 passes):

```bash
shadowstep --shred /path/to/secret.txt
```

- Change file timestamps using a reference file:

```bash
shadowstep --timestomp /path/to/target.file --ref /path/to/reference.file
```

- Run janitor to clear shell history, clipboard, DNS, RAM & swap (platform-dependent):

```bash
shadowstep --clean
```

- Surgical log sanitize (text log on Linux/macOS or Event Logs on Windows):

```bash
shadowstep --sanitize /var/log/syslog --keywords password admin  # Linux/macOS
shadowstep --sanitize --keywords "sensitive-hostname" "username"   # Windows (Event Log handling)
```

Notes and caveats:
- Many operations require elevated privileges (root/Administrator). The tool will log warnings or fail gracefully if permissions are insufficient.
- Platform behavior intentionally differs where OS constraints exist (e.g., creation time on Linux cannot be set via `utime`).

Development & Testing
---------------------

Run unit tests (project includes `tests/`):

```bash
python -m unittest discover tests
```

Linting and formatting recommendations:

```bash
pip install -r requirements-dev.txt  # if you maintain a dev requirements file
black .
flake8 .
```

Project packaging and entry points are defined in `setup.py`. Use `pip install -e .` to install in editable mode during development.

Packaging
---------

The `setup.py` declares `shadowstep` as a package and exposes a console script entry point. To build a wheel:

```bash
python -m pip wheel .
```

For a standalone binary, tools such as PyInstaller can be used, but be mindful of platform-specific dependencies and administrative requirements.

Security, Ethics & Legal Notice
------------------------------

ShadowStep contains functions that may be misused. You must not use the project to commit unauthorized or illegal activity. Use this software only in environments where you have explicit written authorization (e.g., your own lab, sanctioned red-team exercise, or customer engagement with a signed rules-of-engagement).

By using or contributing to this project you agree to follow applicable laws and obtain appropriate authorizations. The authors and maintainers are not responsible for misuse.

Roadmap
-------

Planned and suggested improvements:

- Harden and formalize `log_surgeon` with non-destructive simulation modes and improved Windows Event Log handling.
- Add platform-specific safe-check flags and a dry-run mode that reports intended changes without applying them.
- Expand tests and add integration tests for privileged operations (mocked where appropriate).
- Implement pluggable backends for log formats and better decoy generation templates.
- Add a `--sanitize-policy` feature to define reusable cleanup profiles.

Contributing
------------

Contributions are welcome. Recommended workflow:

1. Fork the repository.
2. Create a feature branch: `git checkout -b feature/my-feature`.
3. Add tests for new behavior.
4. Run the test suite and linters.
5. Submit a pull request with a clear description and rationale.

Please keep changes focused and well-tested. Document breaking changes in PR descriptions.

License
-------

This project is provided under the MIT License. See `LICENSE` for details.

Acknowledgements
----------------

ShadowStep was authored and maintained by contributors. The project bundles several third-party helper libraries — see `requirements.txt` and `setup.py` for runtime dependencies.

---

If you want, I can:
- Expand any module-specific documentation in this README (API signatures, examples)
- Add a `docs/` folder and Sphinx/Markdown pages
- Add a `SECURITY.md` and `CONTRIBUTING.md`

Let me know which items to continue with next.
