ModTools is a powerful Flask-based web application designed to streamline the process of moderating user-uploaded images. It leverages AI and human verification to ensure that the content remains appropriate for the platform's audience.
- Secure user authentication using Flask-Login
- Role-based access control (e.g., admin, moderator, user)
- Password hashing with Flask-Bcrypt for enhanced security
- Automatic image scanning through integrated services like HiveAI and PhotoDNA
- Manual review options: approve, dismiss, or escalate
- Detailed image metadata (upload time, location, IP address, etc.)
- Flexible and extensible plugin architecture
- Easy activation/deactivation of moderation plugins
- Customizable workflow tailored to platform needs
- Seamless integration with external APIs (e.g., image analysis, content moderation)
- Modular design for adding or removing APIs based on requirements
- Invite, promote, degrade, or remove users
- Granular control over user access and permissions
- User-friendly interface for submitting images and metadata
- Powerful filtering and sorting capabilities
- Image status tracking (pending, approved, dismissed, escalated)
- Flask: Python web framework for building the application
- Flask-Bcrypt: Hashing user passwords for secure storage
- Flask-Login: Handling user authentication sessions
- dotenv: Loading environment variables from a
.envfile - Regex: Validating user inputs (e.g., email formats)
- Base64: Encoding and decoding images for processing
- Jinja2: Templating engine for rendering the frontend
- smtplib: Email engine for notifications and alerts
- psycopg2: Interacting with the PostgreSQL database
- Python 3.x
- PostgreSQL (or any other supported database)
ModTools Image is available on Docker Hub as qirtaiba/modtools. You can get it running with the following steps:
-
Pull the Docker image:
docker pull qirtaiba/modtools -
Create a
.envfile with the required environment variables (see below). -
Run the Docker container and map the required ports:
docker run -d --name modtools -p 8000:8000 -v $(pwd)/.env:/app/.env qirtaiba/modtoolsThis command maps the
.envfile from the current directory to the/app/.envpath in the container and exposes the application on port8000of the host machine. -
Access the application at
http://localhost:8000.
-
Clone the repository:
git clone https://github.com/qirtaiba/modtools -
Set up a virtual environment:
python3 -m venv venv source venv/bin/activate # For Unix/Linux/MacOS venv\Scripts\activate # For Windows -
Install dependencies:
pip install -r requirements.txt -
Configure environment variables: Create a
.envfile at the root directory and set the required variables (see below.). -
Initialize the database: Run the script provided in
db/create_tables.sqlto set up your database schema. -
Run the application:
flask run --host=0.0.0.0 --port=8000 -
Access the application at
http://localhost:8000.
'SECRET_KEY': create a secret key for your Flask app
'PHOTODNA_KEY': PhotoDNA key, obtained from Microsoft
'x-user': NCMEC reporting username, obtained from NCMEC
'x-pwd': NCMEC reporting password, obtained from NCMEC
'HIVEAI_KEY': your Hive AI key, obtained from Hive AI
'DATABASE_URL': connection string to a database like neondb
eg. postgres://[username]:[password]@[hostname]/[databasename]
'BASE_URL': URL of your website where Modtools Image is hosted
'EMAIL_SENDER': SMTP email sender
'EMAIL_PASSWORD': SMTP email password
- The PhotoDNA credentials can be acquired via https://www.microsoft.com/en-us/photodna/cloudservice.
- To receive the NCMEC credentials for automated report functionality, write an email to espteam@ncmec.org to request the registration form.
-
Login/Register: First, register as a new user or log in with existing credentials through the provided forms.
-
Dashboard: Navigate the dashboard to access moderation features, view submitted or escalated images, and manage plugins or APIs.
-
Actions: Perform actions like approve, dismiss, or escalate on submitted images based on moderation needs.
-
Administration (for admin users): Manage users and invitations, activate or deactivate plugins and APIs.
/upload and /upload_images endpoints are used to upload images that are later going to be processed.
/upload endpoint takes in the following input arguments
'Email': email of the user uploading the the image
'Password': password of the user uploading the the image
'image': base64 image data or in other words the content of the image
'metadata': image metadata
--> metadata fields 'title': image title,
'extension': extension of the image ex. png jpg
'reportee_name': reportee_name,
'reportee_ip_address': reportee_ip_address
'location': location
--> location fields
"latitude": latitude of where the image was taken
"longitude": lognitude of where the image was taken
"altitude": altitude of where the image was taken
/upload endpoint returns the following JSON response:
'status': status of the request
'message': message describing the ouctome of the upload request
'image_metadata': metadata of the uploaded images
'image_id': image_id of the created image on the server
/upload_images takes in the following input arguments
"Email": email of the user uploading the the image
"Password": password of the user uploading the the image
"images": a list of JSON objects
--> images fields:
"image": base64 image data or in other words the content of the image
"metadata": metadata
--> metadata fields
"title": image title,
"extension": extension of the image ex. png jpg
'reportee_name': reportee_name,
'reportee_ip_address': reportee_ip_address,
'location': location
--> location fields
"latitude": latitude of where the image was taken
"longitude": lognitude of where the image was taken
"altitude": altitude of where the image was taken
/upload_images endpoint returns the following object:
'images': a list of JSON response objects used by /upload
The /status/<image_id> endpoint is used to view tha status of the uploaded image.
/status endpoint returns a JSON with the following fields
"image_url": url of the image
"status": status of the image on the server for example "pending"
"photodna_results": photo dna result for the image
"hiveai_results": hive ai result for the image
Modtools Image is currently in the early stages of development. Many features are missing, undocumented, or incomplete. These include:
- Configuration options for the plugins and APIs are not implemented in the web interface.
- The email alerting plugin, intended to send email alerts when a specified scan result is received, has not been implemented.
- Filtering based on the numerical value of HiveAI score has not been implemented.
Further known limitations will be maintained as Issues in Github.
Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.
This project is licensed under the MIT License.
For any inquiries or support, please raise an issue in the repository's issue tracker.