Skip to content

Patchwork PR: GenerateReadme #24

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Patchwork PR: GenerateReadme #24

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
108 changes: 56 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,66 @@
# Description
WARNING: This application contains security vulnerabilities. Run it only in a backed-up and sheltered environment (such as a VM with a recent snapshot and host-only networking) and at your own risk, escpecially if you enable some of the advanced options described below!

AltoroJ is a sample banking J2EE web application. It shows what happens when web applications are written with consideration of app functionality but not app security. It's a simple and uncluttered platform for demonstrating and learning more about real-life application security issues.

AltoroJ uses standard Java & JSP functionality without relying on any additional frameworks. While vast majority of real-life applications do use frameworks, the exact same principles of Application Security apply in both cases. Frameworks can also be hard to understand for someone not familiar with a particular framework and introduce complexities that detract from the overall learning experience. Not to mention, a large number of large and complex "legacy" Java web applications that look very similar to AltoroJ (but are infinitely more complex of course).

AltoroJ uses Apache Derby as its SQL database that is automatically initialized the first time you log into AltoroJ via its web interface. All of the transactions and operations will then be stored in this database from that point on until you delete your repository folder called "altoro" that is located in your OS home folder (e.g. C:\Users\[your_username] or /Users/[your_username]) or enable advanced option to re-initialize your database every time your web application server is restarted (see below).

AltoroJ was created in 2008 and has gone through a number of iterations since then. It currently, being used around the world to demonstrate application security vulnerabilities, educate folks on how easy some of these issues are to exploit and how severe the impact may be, and is even a part of academic curricula. Even though AltoroJ is pretty stable, if you do find a bug or create a cool exploit for one of its vulnerabilities - please let us know!!!

# Binaries and hosted versions
If you'd like to try AltoroJ but want to skip all of the cool software development stuff, use publicly hosted version, available at http://altoromutual.com:8080/ . You will not be able to enable any of the advanced options and this site may not always be available, but it's the easiest way to get started


# Prereqiusites
AltoroJ has been developed using Eclipse and designed to run on Tomcat 7, but since it's a relatively simple J2EE app, it should be pretty easy to port it to a different J2EE IDE or another J2EE web application server. Here are out-of-the-box requirements:

- Eclipse 4.6 or newer recommended (requires Java 8)
# AltoroJ Banking Application

**WARNING**: This application contains security vulnerabilities. Run it only in a backed-up and sheltered environment (such as a VM with a recent snapshot and host-only networking) and at your own risk, especially if you enable some of the advanced options described below!

## Overview
AltoroJ is a sample banking J2EE web application designed to demonstrate application security vulnerabilities. Built with standard Java & JSP functionality, it provides a simple and uncluttered platform for learning about real-life application security issues without the complexity of additional frameworks.

The application uses Apache Derby as its SQL database, which is automatically initialized on first login. Transactions and operations are stored in this database within a repository folder called "altoro" in your OS home directory (e.g. C:\Users\[your_username] or /Users/[your_username]).

## Features
- Standard J2EE/JSP implementation without additional frameworks
- Automatic database initialization
- REST API with Swagger documentation
- Configurable security vulnerabilities for learning/testing
- Sample banking functions including:
- Account management
- Fund transfers
- Transaction history
- Credit card applications
- User feedback system
- Administrative functions

## Credentials
Default login credentials:
- Regular user: jsmith/demo1234
- Admin user: admin/admin

## Prerequisites
- Eclipse 4.6 or newer (requires Java 8)
- Tomcat 7.x
- Gradle 3.0 to build from command line
- Gradle's Buildship Eclipse plug-in to automatically download required 3rd party libraries and run AltoroJ inside Eclipse
-- Easiest way to install Buildship is from Eclipse Marketplace (inside Eclipse, go to Help -> Eclipse Marketplace)

[Read more about importing AltoroJ into Eclipse from GitHub here](https://github.com/AppSecDev/AltoroJ/blob/master/Importing%20AltoroJ%20into%20Eclipse%20from%20GitHub.md)

# AltoroJ credentials
Main usernames and passwords for AltoroJ are as follows:
- jsmith/demo1234
- admin/admin


# Advanced options
AltoroJ’s original design goals were to create an application that is easy to deploy, very stable and less dangerous (as far as vulnerable web apps go). However, these goals meant that certain attacks couldn’t be a part of it. Because of this, there are advanced user-configurable properties that can enable AltoroJ behaviors which are disabled by default.These enable extra functionality, new cool attacks and demos as well as optional behaviors.

Please see WEB-INF/app.properties file for more information on each property


# REST API
- Gradle 3.0 (for command line builds)
- Gradle Buildship Eclipse plugin (for Eclipse builds)
- Install via Eclipse Marketplace (Help -> Eclipse Marketplace)

AltoroJ has a fairly extensive REST API, which is documented using Swagger. You can find out more about and interact with the provided REST services by clicking on the REST API link in the footer of almost every AltoroJ page.
## Getting Started
For detailed setup instructions, see [Importing AltoroJ into Eclipse from GitHub](https://github.com/AppSecDev/AltoroJ/blob/master/Importing%20AltoroJ%20into%20Eclipse%20from%20GitHub.md)

## Advanced Configuration
AltoroJ includes advanced configuration options that can enable additional functionality and security vulnerabilities. These are disabled by default for stability and safety. See WEB-INF/app.properties for details on available options.

# Troubleshooting
## REST API
The application provides a REST API documented using Swagger. Access the API documentation through the REST API link in the application footer.

- Problem: AltoroJ runs, but an error “Failed to create database 'altoro‘” comes up when you try to log in
- Cause: AltoroJ database does not get created. This is usually caused by folder permission issues on a locked-down system
- Solution:
To make sure this isn’t a fluke, try to log in again using jsmith/demo1234.
AltoroJ uses Java’s user.home property as a base directory for its database so this shouldn’t happen. However, if it does. Take a look at your Eclipse Console, or if running directly on Tomcat, open "catalina.out" file from Tomcat’s logs folder in a text editor and look for “user.home=“. This is the folder that AltoroJ is trying to create another folder in and needs write access. You can then:
Give the user Tomcat runs under read/write/create access to this folder (recommended)
OR modify Tomcat’s startup to include –Duser.home=“<new_path>” in Java arguments to change DB location
## Public Demo
A public demo version is available at http://altoromutual.com:8080/. Note that advanced options are disabled on this instance.

- Problem: AltoroJ does not run on Tomcat due to compilation errors
- Cause: If you have compilation errors in Eclipse, Java build path is likely to blame
- Solution: Run AltoroJ's Gradle build in order to download required third party libraries and build AltoroJ
## Troubleshooting

### Database Creation Error
If you receive "Failed to create database 'altoro'" on login:
1. Verify you can log in with jsmith/demo1234
2. Check the Eclipse Console or catalina.out for "user.home=" path
3. Either:
- Grant write permissions to the Tomcat user for that directory
- Change DB location via -Duser.home="<new_path>" Java argument

# License
### Compilation Errors
If you have compilation errors in Eclipse:
1. Run the Gradle build to download required libraries
2. Refresh project dependencies

All files found in this project are licensed under the [Apache License 2.0](https://github.com/AppSecDev/AltoroJ/blob/master/LICENSE).
## License
This project is licensed under the [Apache License 2.0](LICENSE).

## History
AltoroJ was created in 2008 and has been used worldwide for security education, vulnerability demonstration, and academic curricula. While stable, bug reports and vulnerability exploits are welcome!