github_searcher/README.md

# GitHub Searcher

GitHub Searcher is a command-line tool to search GitHub repositories and users for PoC exploits and CVEs. It supports various search types and can output results in JSON format.

## Features

- Search GitHub repositories by query.
- Search GitHub users by query.
- Search within repository names.
- Retrieve open issues and pull requests for repositories.
- Retrieve file contents for repositories.
- Output results in JSON format.

## Requirements

- Python 3.x
- `PyGithub` library

## Installation

1. Clone the repository:
    ```sh
    git clone https://github.com/yourusername/github_searcher.git
    cd github_searcher
    ```

2. Install the required dependencies:
    ```sh
    pip install PyGithub
    ```

3. Set the `GITHUB_ACCESS_TOKEN` environment variable with your GitHub access token:
    ```sh
    export GITHUB_ACCESS_TOKEN=your_access_token
    ```

## Usage

```sh
python github_searcher.py --query QUERY --search_type SEARCH_TYPE [--get_file_contents] [--get_open_issues] [--get_open_pull_requests] [--json]
```

### Arguments

- `--query`: The search query (required).
- `--search_type`: The type of search to perform (required). Choices are:
  - `repo`: Search repositories.
  - `users`: Search users.
  - `in-repo-name`: Search within repository names.
- `--get_file_contents`: Get the contents of repository results (optional).
- `--get_open_issues`: Get the open issues of repository results (optional).
- `--get_open_pull_requests`: Get the open pull requests of repository results (optional).
- `--json`: Output the results in JSON format (optional).

### Examples

1. Search repositories with a query:
    ```sh
    python github_searcher.py --query "machine learning" --search_type repo
    ```

2. Search users with a query:
    ```sh
    python github_searcher.py --query "john doe" --search_type users
    ```

3. Search within repository names:
    ```sh
    python github_searcher.py --query "tensorflow" --search_type in-repo-name
    ```

4. Get open issues and pull requests for repositories:
    ```sh
    python github_searcher.py --query "machine learning" --search_type repo --get_open_issues --get_open_pull_requests
    ```

5. Output results in JSON format:
    ```sh
    python github_searcher.py --query "machine learning" --search_type repo --json
    ```

6. Use Docker Compose to search for a specific CVE-ID and output results to a file:
    ```sh
    docker-compose run --rm app python3 /usr/src/app/github_searcher.py --query=CVE-2024-5932 --search_type=in-repo-name --get_open_issues --get_open_pull_requests --get_file_contents --json > cve-2024-5932
    ```

7. Search for a specific repository by name and get open issues:
    ```sh
    python github_searcher.py --query "torvalds/linux" --search_type in-repo-name --get_open_issues
    ```

8. Search for a specific repository by name and get open pull requests:
    ```sh
    python github_searcher.py --query "apple/swift" --search_type in-repo-name --get_open_pull_requests
    ```

9. Search for a specific repository by name and get file contents:
    ```sh
    python github_searcher.py --query "microsoft/vscode" --search_type in-repo-name --get_file_contents
    ```

10. Search for a specific repository by name and output results in JSON format:
    ```sh
    python github_searcher.py --query "facebook/react" --search_type in-repo-name --json
    ```

## Output

The output will include the following details based on the flags provided:

- **Repository URL**: The URL of the repository.
- **Open Issues**: A list of open issues with their titles and URLs.
- **Open Pull Requests**: A list of open pull requests with their titles and URLs.
- **File Contents**: A list of file contents with their names, SHAs, sizes, encodings, and URLs.

## License

This project is licensed under the MIT License.