Skip to content

dev #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scope-forensics merged 1 commit into from
Mar 26, 2025
Merged

dev #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
305 changes: 181 additions & 124 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,190 +1,247 @@
# scope
<a id="readme-top"></a>

scope is an open source Cloud Forensic tool for Amazon Web Service (AWS), Microsoft Azure and Google Cloud Platform (GCP).
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![Apache-2.0 license
][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]

Current status: Under rapid development - The initial version will be released soon.
<!-- https://github.com/othneildrew/Best-README-Template/blob/main/BLANK_README.md -->

### AWS - In progress
### AZURE - To be started
### GCP - To be started
<!-- PROJECT LOGO -->
<br />
<div align="center">
<a href="https://github.com/scope-forensics/scope">
<img src="images/logo/logo.png" alt="Logo" width="80" height="80">
</a>

<h3 align="center">Scope</h3>

<p align="center">
Scope is an open source cloud forensic tools to allow for rapid incident responce in Amazon Web Services (AWS). Support for Google Cloud Platform (GCP) and Microsoft Azure (Azure) is comming soon.


<br />
<a href="https://scopeforensics.com/docs"><strong>Explore the docs »</strong></a>
<br />
<br />
<a href="https://github.com/scope-forensics/scope">View Demo</a>
&middot;
<a href="https://github.com/scope-forensics/scope/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
&middot;
<a href="https://github.com/scope-forensics/scope/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
</p>
</div>

## Installation - Docker

The easiest way to get Scope up and running is with [Docker](https://www.docker.com/).

Just [install Docker](https://www.docker.com/get-started) and
[Docker Compose](https://docs.docker.com/compose/install/)
and then run:
<!-- TABLE OF CONTENTS -->
<details>
<summary>Table of Contents</summary>
<ol>
<li>
<a href="#about-the-project">About The Project</a>
<ul>
<li><a href="#built-with">Built With</a></li>
</ul>
</li>
<li>
<a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation">Installation</a></li>
</ul>
</li>
<li><a href="#usage">Usage</a></li>
<li><a href="#roadmap">Roadmap</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#acknowledgments">Acknowledgments</a></li>
</ol>
</details>

```
make init
```

This will spin up a database, web worker, celery worker, and Redis broker and run your migrations.

You can then go to [localhost:8000](http://localhost:8000/) to view your local installation of Scope.
<!-- ABOUT THE PROJECT -->
## About The Project

*Note: if you get an error, make sure you have a `.env` file, or create one based on `.env.example`.*
[![Product Name Screen Shot][product-screenshot]](https://example.com)

### Using the Makefile
<p align="right">(<a href="#readme-top">back to top</a>)</p>

You can run `make` to see other helper functions, and you can view the source
of the file in case you need to run any specific commands.

For example, you can run management commands in containers using the same method
used in the `Makefile`. E.g.

```
docker compose exec web python manage.py createsuperuser
```
### Built With

## Installation - Native
* [![Python][python.org]][Python-url]
* [![Django][Djangoproject.com]][Django-url]
* [![Bootstrap][Bootstrap.com]][Bootstrap-url]
* [![HTMX][Htmx.org]][Htmx-url]
* [![Docker][Docker.com]][Docker-url]

You can also install/run Scope directly on your OS using the instructions below.
Setup a virtualenv and install requirements
(this example uses [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)):
<p align="right">(<a href="#readme-top">back to top</a>)</p>

```bash
mkvirtualenv scope -p python3.11
pip install -r dev-requirements.txt
```

## Set up database

*If you are using Docker you can skip these steps.*
<!-- GETTING STARTED -->
## Getting Started

Create a database named `scope`.
This is an example of how you may give instructions on setting up your project locally.
To get a local copy up and running follow these simple example steps.

```
createdb scope
```
### Prerequisites

Create database migrations:
This is an example of how to list things you need to use the software and how to install them.
* npm
```sh
npm install npm@latest -g
```

```
python manage.py makemigrations
```
### Installation

Create database tables:
1. Get a free API Key at [https://example.com](https://example.com)
2. Clone the repo
```sh
git clone https://github.com/scope-forensics/scope.git
```
3. Install NPM packages
```sh
npm install
```
4. Enter your API in `config.js`
```js
const API_KEY = 'ENTER YOUR API';
```
5. Change git remote url to avoid accidental pushes to base project
```sh
git remote set-url origin scope-forensics/scope
git remote -v # confirm the changes
```

```
python manage.py migrate
```
<p align="right">(<a href="#readme-top">back to top</a>)</p>

## Running the Scope server

**Docker:**

```bash
make start
```
<!-- USAGE EXAMPLES -->
## Usage

**Native:**
Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.

```bash
python manage.py runserver
```
_For more examples, please refer to the [Documentation](https://example.com)_

## Building front-end
<p align="right">(<a href="#readme-top">back to top</a>)</p>

To build JavaScript and CSS files, first install npm packages:

**Docker:**

```bash
make npm-install
```
<!-- ROADMAP -->
## Roadmap

**Native:**
- [ ] AWS
- [ ] Azure
- [ ] GCP
- [ ] Feature 3
- [ ] Nested Feature

```bash
npm install
```
See the [open issues](https://github.com/scope-forensics/scope/issues) for a full list of proposed features (and known issues).

Then build (and watch for changes locally):
<p align="right">(<a href="#readme-top">back to top</a>)</p>

**Docker:**

```bash
make npm-watch
```

**Native:**
<!-- CONTRIBUTING -->
## Contributing

```bash
npm run dev-watch
```
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.

## Running Celery
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!

Celery is used to run background tasks and pull large amounts of data while your working with Scope.
If you use Docker it will start automatically.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

If you're not using Docker, you can run it using:
<p align="right">(<a href="#readme-top">back to top</a>)</p>

```bash
celery -A scope worker -l INFO --pool=solo
```
### Top contributors:

Or with celery beat (for scheduled tasks):
<a href="https://github.com/scope-forensics/scope/graphs/contributors">
<img src="https://contrib.rocks/image?repo=scope-forensics/scope" alt="contrib.rocks image" />
</a>

```bash
celery -A scope worker -l INFO -B --pool=solo
```

Note: Using the `solo` pool is recommended for development but not for production.

<!-- LICENSE -->
## License

## Installing Git commit hooks
Distributed under the Apache-2.0 license
. See `LICENSE.txt` for more information.

To install the Git commit hooks run the following:
<p align="right">(<a href="#readme-top">back to top</a>)</p>

```shell
$ pre-commit install --install-hooks
```

Once these are installed they will be run on every commit.

## Running Tests
<!-- CONTACT -->
## Contact

To run tests:
Your Name - [@twitter_handle](https://twitter.com/twitter_handle) - scopeforenscis@protonmail.com.com

**Docker:**
Project Link: [https://github.com/scope-forensics/scope](https://github.com/scope-forensics/scope)

```bash
make test
```
<p align="right">(<a href="#readme-top">back to top</a>)</p>

**Native:**

```bash
python manage.py test
```

Or to test a specific app/module:
<!-- ACKNOWLEDGMENTS -->
## Acknowledgments

**Docker:**
* []()
* []()
* []()

```bash
make test ARGS='apps.utils.tests.test_slugs --keepdb'
```
<p align="right">(<a href="#readme-top">back to top</a>)</p>

**Native:**

```bash
python manage.py test apps.utils.tests.test_slugs
```

On Linux-based systems you can watch for changes using the following:
<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
[contributors-shield]: https://img.shields.io/github/contributors/scope-forensics/scope.svg?style=for-the-badge
[contributors-url]: https://github.com/scope-forensics/scope/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/scope-forensics/scope.svg?style=for-the-badge
[forks-url]: https://github.com/scope-forensics/scope/network/members
[stars-shield]: https://img.shields.io/github/stars/scope-forensics/scope.svg?style=for-the-badge
[stars-url]: https://github.com/scope-forensics/scope/stargazers
[issues-shield]: https://img.shields.io/github/issues/scope-forensics/scope.svg?style=for-the-badge
[issues-url]: https://github.com/scope-forensics/scope/issues
[license-shield]: https://img.shields.io/github/license/scope-forensics/scope.svg?style=for-the-badge
[license-url]: https://github.com/scope-forensics/scope/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/linkedin_username
[product-screenshot]: images/screenshot.png
[Next.js]: https://img.shields.io/badge/next.js-000000?style=for-the-badge&logo=nextdotjs&logoColor=white
[Next-url]: https://nextjs.org/
[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB
[React-url]: https://reactjs.org/
[Vue.js]: https://img.shields.io/badge/Vue.js-35495E?style=for-the-badge&logo=vuedotjs&logoColor=4FC08D
[Vue-url]: https://vuejs.org/
[Angular.io]: https://img.shields.io/badge/Angular-DD0031?style=for-the-badge&logo=angular&logoColor=white
[Angular-url]: https://angular.io/
[Svelte.dev]: https://img.shields.io/badge/Svelte-4A4A55?style=for-the-badge&logo=svelte&logoColor=FF3E00
[Svelte-url]: https://svelte.dev/
[Laravel.com]: https://img.shields.io/badge/Laravel-FF2D20?style=for-the-badge&logo=laravel&logoColor=white
[Laravel-url]: https://laravel.com
[Bootstrap.com]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white
[Bootstrap-url]: https://getbootstrap.com
[Htmx.org]: https://img.shields.io/badge/Htmx-563D7C?style=for-the-badge&logo=htmx&logoColor=white
[Htmx-url]: https://htmx.org
[Docker.com]: https://img.shields.io/badge/Docker-2CA5E0?style=for-the-badge&logo=docker&logoColor=white
[Docker-url]: https://docker.com
[Djangoproject.com]: https://img.shields.io/badge/Django-092E20?style=for-the-badge&logo=django&logoColor=white
[Django-url]: https://djangoproject.com
[Python.org]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white
[Python-url]: https://python.org

**Docker:**

```bash
find . -name '*.py' | entr docker compose exec web python manage.py test apps.utils.tests.test_slugs
```

**Native:**

```bash
find . -name '*.py' | entr python manage.py test apps.utils.tests.test_slugs
```
Loading
Loading