peyeon 0.0.0rc4__tar.gz

peyeon-0.0.0rc4/.flake8

@@ -0,0 +1,4 @@
+[flake8]
+  # ignore = E203,E402,E501,W503
+  max-line-length = 100
+  # max-complexity = 18

peyeon-0.0.0rc4/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

peyeon-0.0.0rc4/.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt  export-subst

peyeon-0.0.0rc4/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

peyeon-0.0.0rc4/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - v*
+
+jobs:
+  build-wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Build wheel
+        run: |
+          pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Upload Python package dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist
+
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    needs: build-wheel
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/peyeon
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+    - name: Download Python package dist artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-dist
+        path: dist
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

peyeon-0.0.0rc4/.github/workflows/unittest.yml

@@ -0,0 +1,29 @@
+name: Eyeon Unit Testing
+on: [push]
+jobs:
+  testing:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Virtual Environment Setup
+        run: |
+          python3 -m venv .venv
+      - name: Install Dependencies
+        run: |
+          source .venv/bin/activate
+          pip install build
+          python3 -m build
+          pip install dist/peyeon*.whl
+          echo "Packages installed"
+      - name: Run Unittests
+        run: |
+          source .venv/bin/activate
+          cd tests/
+          coverage run -m unittest
+          coverage report

peyeon-0.0.0rc4/.gitignore

@@ -0,0 +1,12 @@
+__pycache__
+.ipynb_checkpoints
+.pyc
+.swp
+*.egg-info
+certs
+dist
+.DS_Store
+# *.exe
+outputs/
+docs/build
+_version.py

peyeon-0.0.0rc4/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  # - repo: https://github.com/PyCQA/isort
+  #   rev: 5.12.0
+  #   hooks:
+  #     - id: isort
+  - repo: https://github.com/psf/black
+    rev: 23.7.0
+    hooks:
+      - id: black
+        args: [--config=pyproject.toml, --line-length=100]
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.1.0
+    hooks:
+      - id: flake8
+        additional_dependencies: [flake8-bugbear]
+  # - repo: https://github.com/pycqa/pylint
+  #   rev: v3.0.0a7
+  #   hooks:
+  #     - id: pylint
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-json

peyeon-0.0.0rc4/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+        
+
+

peyeon-0.0.0rc4/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+Contributing to EyeON
+
+Thank you for considering contributing to our project! We appreciate your help.
+
+## Reporting Issues
+
+1. If you find a bug or have a feature request, please [open a new issue](https://github.com/LLNL/EyeON/issues) and provide detailed information about the problem.
+2. If you find security issues or vulnerabilities, please [report here](https://github.com/LLNL/EyeON/security)
+
+## Making Contributions
+
+We welcome contributions from the community. To contribute to this project, follow these steps:
+
+1. Fork the repository on GitHub.
+2. Clone your forked repository to your local machine.
+
+All contributions to EyeON are made under the MIT license (MIT).
+
+### For Developers:
+
+1. Create a virtual environment with python >= 3.8 [Optional, but recommended]
+
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+
+2. Clone peyeon
+
+```bash
+git clone git@github.com:LLNL/pEyeON.git
+```
+
+## Code of Conduct
+
+All participants in the EyeON community are expected to follow our [Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+

peyeon-0.0.0rc4/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 Lawrence Livermore National Security, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

peyeon-0.0.0rc4/NOTICE

@@ -0,0 +1,7 @@
+This work was produced under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344.
+
+This work was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor Lawrence Livermore National Security, LLC, nor any of their employees makes any warranty, expressed or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights.
+
+Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or Lawrence Livermore National Security, LLC.
+
+The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or Lawrence Livermore National Security, LLC, and shall not be used for advertising or product endorsement purposes.

peyeon-0.0.0rc4/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.2
+Name: peyeon
+Version: 0.0.0rc4
+Summary: EyeON update tracking utility
+Author-email: Seth Lyles <lyles6@llnl.gov>, Wangmo Tenzing <tenzing1@llnl.gov>, Jack Mooney <mooney7@llnl.gov>, Grant Johnson <johnson30@llnl.gov>, Isabel Gardner <gardner59@llnl.gov>, Grant Espe <espe1@llnl.gov>
+Maintainer-email: Seth Lyles <lyles6@llnl.gov>
+License: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: jsonschema>=4.17
+Requires-Dist: lief>=0.13.2
+Requires-Dist: python-magic==0.4.27
+Requires-Dist: pefile>=2024.8.26
+Requires-Dist: telfhash>=0.9.8
+Requires-Dist: surfactant==0.0.0rc10
+Requires-Dist: coverage>=7.5.3
+Requires-Dist: duckdb>=1.0.0
+Requires-Dist: alive_progress>=3.1.5
+Requires-Dist: dynaconf>=3.2.6
+Requires-Dist: streamlit>=1.37.0
+Requires-Dist: jupyter>=1.1.1
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+
+# pEyeON
+
+EyeON is a CLI tool that allows users to get software data pertaining to their machines by performing threat and inventory analysis. It can be used to quickly generate manifests of installed software or potential firmare patches. These manifests are then submitted to a database and LLNL can use them to continuously monitor OT software for threats.
+
+[![CI Test Status](https://github.com/LLNL/pEyeON/actions/workflows/unittest.yml/badge.svg)](https://github.com/LLNL/pEyeON/actions/workflows/unittest.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/LLNL/pEyeON/main.svg)]()
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/LLNL/pEyeON/blob/main/LICENSE)
+
+<p align="center">
+<img src="Photo/EyeON_Mascot.png" width="300" height="270">
+
+## Motivation
+
+Validation is important when installing new software. Existing tools use a hash/signature check to validate that the software has not been tampered. Knowing that the software works as intended saves a lot of time and energy, but just performing these hash/signature checks doesn't provide all the information needed to understand supply chain threats. 
+
+EyeON provides an automated, consistent process across users to scan software files used for operational technologies. Its findings can be used to generate reports that track software patterns, shedding light on supply chain risks. This tool's main capabilities are focused on increasing the visibility of OT software landscape. 
+
+## Installation
+Eyeon can also be run in linux or WSL.
+
+```bash
+git clone git@github.com:LLNL/pEyeON.git
+```
+or 
+```bash
+git clone https://github.com/LLNL/pEyeON.git
+```
+
+### Dockerfile
+This dockerfile contains all the pertinent tools specific to data extraction. The main tools needed are `ssdeep`, `libmagic`, `tlsh`, and `detect-it-easy`. There are a couple variables that need to be changed in order for it to work.
+
+Run docker build script
+```bash
+./docker-build.sh
+```
+
+Run docker run script
+```bash
+./docker-run.sh
+```
+
+This attaches current the code directory as a working directory in the container. Files that need to be scanned should go in "tests" folder. If running in a docker container, the eyeon root directory is mounted to "/workdir", so place samples in "/workdir/samples" or "/workdir/tests/samples".
+
+Cd into workdir directory, install EyeON, and run 'rein' alias to build python dependencies:
+```bash
+cd workdir
+rein
+```
+
+EyeON commands should work now.
+
+## Usage
+
+This section shows how to run the CLI component. 
+
+1. Displays all arguments 
+```bash
+eyeon --help
+```
+
+2. Displays observe arguments 
+```bash
+eyeon observe --help
+```
+
+3. Displays parse arguments 
+```bash
+eyeon parse --help
+```
+
+EyeON consists of two parts - an observe call and a parse call. `observe.py` works on a single file to return a suite of identifying metrics, whereas `parse.py` expects a folder. Both of these can be run either from a library import or a CLI command.
+
+#### Observe
+
+1. This CLI command calls the observe function and makes an observation of a file. 
+
+CLI command:
+
+```bash
+eyeon observe notepad++.exe
+```
+
+Init file calls observe function in observe.py
+
+```bash
+obs = eyeon.observe.Observe("./tests/binaries/x86/notepad++/notepad++.exe")
+```
+The observation will output a json file containing unique identifying information such as hashes, modify date, certificate info, etc.
+
+Example json file:
+
+```json
+{
+    "bytecount": 9381, 
+    "filename": "demo.ipynb", 
+    "signatures": {"valid": "N/A"}, 
+    "imphash": "N/A", 
+    "magic": "JSON text data", 
+    "modtime": "2023-11-03 20:21:20", 
+    "observation_ts": "2024-01-17 09:16:48", 
+    "permissions": "0o100644", 
+    "md5": "34e11a35c91d57ac249ff1300055a816", 
+    "sha1": "9388f99f2c05e6e36b279dc2453ebea4bdc83242", 
+    "sha256": "fa95b3820d4ee30a635982bf9b02a467e738deaebd0db1ff6a262623d762f60d", 
+    "ssdeep": "96:Ui7ooWT+sPmRBeco20zV32G0r/R4jUkv57nPBSujJfcMZC606/StUbm/lGMipUQy:U/pdratRqJ3ZHStx4UA+I1jS"
+}
+```
+
+#### Parse
+parse.py calls observe recursively, returning an observation for each file in a directory. 
+
+```bash
+obs = eyeon.parse.Parse(args.dir)
+```
+
+#### Jupyter Notebook
+If you want to run jupyter, the `./docker-run.sh` script exposes port 8888. Launch it from the `/workdir` or eyeon root directory via `jupyter notebook --ip=0.0.0.0 --no-browser` and open the `demo.ipynb` notebook for a quick demonstration.
+
+
+#### Streamlit app
+In the `src` directory, there exist the bones of a data exploration applet. To generate data for this, add the database flag like `eyeon parse -d tests/data/20240925-eyeon/dbhelpers/20240925-eyeon.db`. Then, if necessary, update the database path variable in the `src/streamlit/eyeon_settings.toml`. Note that the path needs to point to the grandparent directory of the `dbhelpers` directory. This is a specific path for the streamlit app; the streamlit directory has more information in its own README.
+
+
+## Future Work
+There will be a second part to this project, which will be to develop a cloud application that anonymizes and summarizes the findings to enable OT security analysis.
+
+SPDX-License-Identifier: MIT

peyeon-0.0.0rc4/README.md

@@ -0,0 +1,127 @@
+# pEyeON
+
+EyeON is a CLI tool that allows users to get software data pertaining to their machines by performing threat and inventory analysis. It can be used to quickly generate manifests of installed software or potential firmare patches. These manifests are then submitted to a database and LLNL can use them to continuously monitor OT software for threats.
+
+[![CI Test Status](https://github.com/LLNL/pEyeON/actions/workflows/unittest.yml/badge.svg)](https://github.com/LLNL/pEyeON/actions/workflows/unittest.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/LLNL/pEyeON/main.svg)]()
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/LLNL/pEyeON/blob/main/LICENSE)
+
+<p align="center">
+<img src="Photo/EyeON_Mascot.png" width="300" height="270">
+
+## Motivation
+
+Validation is important when installing new software. Existing tools use a hash/signature check to validate that the software has not been tampered. Knowing that the software works as intended saves a lot of time and energy, but just performing these hash/signature checks doesn't provide all the information needed to understand supply chain threats. 
+
+EyeON provides an automated, consistent process across users to scan software files used for operational technologies. Its findings can be used to generate reports that track software patterns, shedding light on supply chain risks. This tool's main capabilities are focused on increasing the visibility of OT software landscape. 
+
+## Installation
+Eyeon can also be run in linux or WSL.
+
+```bash
+git clone git@github.com:LLNL/pEyeON.git
+```
+or 
+```bash
+git clone https://github.com/LLNL/pEyeON.git
+```
+
+### Dockerfile
+This dockerfile contains all the pertinent tools specific to data extraction. The main tools needed are `ssdeep`, `libmagic`, `tlsh`, and `detect-it-easy`. There are a couple variables that need to be changed in order for it to work.
+
+Run docker build script
+```bash
+./docker-build.sh
+```
+
+Run docker run script
+```bash
+./docker-run.sh
+```
+
+This attaches current the code directory as a working directory in the container. Files that need to be scanned should go in "tests" folder. If running in a docker container, the eyeon root directory is mounted to "/workdir", so place samples in "/workdir/samples" or "/workdir/tests/samples".
+
+Cd into workdir directory, install EyeON, and run 'rein' alias to build python dependencies:
+```bash
+cd workdir
+rein
+```
+
+EyeON commands should work now.
+
+## Usage
+
+This section shows how to run the CLI component. 
+
+1. Displays all arguments 
+```bash
+eyeon --help
+```
+
+2. Displays observe arguments 
+```bash
+eyeon observe --help
+```
+
+3. Displays parse arguments 
+```bash
+eyeon parse --help
+```
+
+EyeON consists of two parts - an observe call and a parse call. `observe.py` works on a single file to return a suite of identifying metrics, whereas `parse.py` expects a folder. Both of these can be run either from a library import or a CLI command.
+
+#### Observe
+
+1. This CLI command calls the observe function and makes an observation of a file. 
+
+CLI command:
+
+```bash
+eyeon observe notepad++.exe
+```
+
+Init file calls observe function in observe.py
+
+```bash
+obs = eyeon.observe.Observe("./tests/binaries/x86/notepad++/notepad++.exe")
+```
+The observation will output a json file containing unique identifying information such as hashes, modify date, certificate info, etc.
+
+Example json file:
+
+```json
+{
+    "bytecount": 9381, 
+    "filename": "demo.ipynb", 
+    "signatures": {"valid": "N/A"}, 
+    "imphash": "N/A", 
+    "magic": "JSON text data", 
+    "modtime": "2023-11-03 20:21:20", 
+    "observation_ts": "2024-01-17 09:16:48", 
+    "permissions": "0o100644", 
+    "md5": "34e11a35c91d57ac249ff1300055a816", 
+    "sha1": "9388f99f2c05e6e36b279dc2453ebea4bdc83242", 
+    "sha256": "fa95b3820d4ee30a635982bf9b02a467e738deaebd0db1ff6a262623d762f60d", 
+    "ssdeep": "96:Ui7ooWT+sPmRBeco20zV32G0r/R4jUkv57nPBSujJfcMZC606/StUbm/lGMipUQy:U/pdratRqJ3ZHStx4UA+I1jS"
+}
+```
+
+#### Parse
+parse.py calls observe recursively, returning an observation for each file in a directory. 
+
+```bash
+obs = eyeon.parse.Parse(args.dir)
+```
+
+#### Jupyter Notebook
+If you want to run jupyter, the `./docker-run.sh` script exposes port 8888. Launch it from the `/workdir` or eyeon root directory via `jupyter notebook --ip=0.0.0.0 --no-browser` and open the `demo.ipynb` notebook for a quick demonstration.
+
+
+#### Streamlit app
+In the `src` directory, there exist the bones of a data exploration applet. To generate data for this, add the database flag like `eyeon parse -d tests/data/20240925-eyeon/dbhelpers/20240925-eyeon.db`. Then, if necessary, update the database path variable in the `src/streamlit/eyeon_settings.toml`. Note that the path needs to point to the grandparent directory of the `dbhelpers` directory. This is a specific path for the streamlit app; the streamlit directory has more information in its own README.
+
+
+## Future Work
+There will be a second part to this project, which will be to develop a cloud application that anonymizes and summarizes the findings to enable OT security analysis.
+
+SPDX-License-Identifier: MIT